[DOCS] Use --mapper expressions for AniDB / TheTVDB cross-entity matching

[rednoah]

The --mapper option accepts a Groovy expression that yields Episode or Episode[] to map one episode object to one or more episode objects to be used for matching. It's based on the same FileBot Format Engine used for --filter and --format expressions, so code and episode bindings work exactly the same.


e.g. use and rename with TheTVDB episode data, but use AnimeList.AniDB episode mappings for matching:

Shell: Select all

filebot -rename *.mkv --db TheTVDB --mapper "AnimeList.AniDB"

e.g. match with Absolute Order but rename with Airdate Order:

Shell: Select all

filebot -rename *.mkv --db TheTVDB -non-strict --order airdate --mapper "order.absolute.episode"

e.g. force Match by Episode Title or Match by Episode Airdate by nullifying SxE numbers:

Shell: Select all

filebot -rename *.mkv --db TheTVDB -non-strict --mapper "episode.number(null)"

Example Mapper Expressions

• Map to AniDB episode numbers using Anime Lists:

  Groovy: Select all

  AnimeList.AniDB

• Map to TheTVDB episode numbers using Anime Lists:

  Groovy: Select all

  AnimeList.TheTVDB

• Map to AniDB episode numbers using TheXEM:

  Groovy: Select all

  XEM.AniDB

• Map to TheTVDB episode numbers using TheXEM:

  Groovy: Select all

  XEM.TheTVDB

Advanced Example Mapper Expressions

• Map to itself:
  (i.e. identity mapper, behave exactly as if there was no mapper)

  Groovy: Select all

  episode

• Map to a different episode order:
  (i.e. match by Absolute numbers, rename with SxE numbers)

  Groovy: Select all

  order.absolute.episode

• Force Season 1 / Episode e+1 and match accordingly:
  (e.g. useful if all SxE numbers are off by 1 for some reason)

  Groovy: Select all

  episode.derive(1, e + 1)

• Use a different mapper depending on some condition:
  (e.g. use AniDB mapper if the Anime label is set, otherwise use identity mapper)

  Groovy: Select all

  label =~ /Anime/ ? AnimeList.AniDB : episode

• Map to multiple episodes at the same time, in the hope that one of these additional options matches your files, and let the matcher figure out the rest:
  (e.g. useful if you don't know what you're dealing with in advance and want FileBot to consider multiple possibilities)

  Groovy: Select all

  [episode, AnimeList.AniDB]

• Map airdate numbers to MM-DD-YYYY if sensible, otherwise stick to the DD-MM-YYYY default interpretation:
  (e.g. useful for matching files that use ambiguous MM-DD-YYYY date patterns)

  Groovy: Select all

  any{ episode.airdate(d.year, d.day, d.month) }{ episode }

• Map season-year ordered episodes to season-number ordered files:
  (e.g. match MythBusters 1x01 to MythBusters 2003x01)

  Groovy: Select all

  any{ s >= y ? episode.derive(s - y + 1, e) : null }{ episode }

• Match by Episode Title but Format by Airdate Episode Group to match multi-episode out-of-order cartoons:

  Groovy: Select all

  episode.number(null).map(episodelist.findAll{ airdate == it.airdate }).reverse()

Please use the Format Editor to test and prototype --mapper expressions.