[DOCS] Split code into external *.groovy script files

[rednoah]

External format @lines

Use @line syntax to copy & paste format expression code from an external text file:

Format: Select all

@/path/to/TargetFolder.groovy
@/path/to/MovieNaming.groovy
@/path/to/MediaInfoTags.groovy

The --format option also accepts *.groovy files as input and will read the text content of the given file as option value:

Shell: Select all

--format "/path/to/MyFormat.groovy"

Note that the @file syntax for reading command-line arguments from external text files is a separate concept and takes precedence on the command-line, so literal argument values cannot start with an @ character, but we can start with a \n character (i.e. newline) instead:

Shell: Select all

filebot … --format "
@/path/to/TargetFolder.groovy
@/path/to/MovieNaming.groovy
@/path/to/MediaInfoTags.groovy
"

You can thus have multiple levels of indirection, i.e. argument level, option level, and finally the format level which can be nested recursively:

Console Output: Select all

$ cat /path/to/MyCommand.args
-rename
-r
--db
TheMovieDB
--format
/path/to/MyFormat.groovy
$ cat /path/to/MyFormat.groovy
@lib/TargetFolder.groovy
@lib/MovieNaming.groovy
@lib/MediaInfoTags.groovy
$ cat /path/to/MovieNaming.groovy
{ plex.id }

External Groovy runtime includes

Dynamically evaluate external Groovy scripts at runtime:

Format: Select all

{ include '/path/to/TargetFolder.groovy' }
{ include '/path/to/MovieNaming.groovy' }
{ include '/path/to/MediaInfoTags.groovy' }

Console Output: Select all

$ cat /path/to/MovieNaming.groovy
plex.id

Your custom code may decide dynamically at runtime which external Groovy scripts to evaluate depending on the context:

Format: Select all

{ include "/path/to/MovieFormat.${y > 1980 ? 'Recent' : 'Classic'}.groovy" }

Your custom code may include external Groovy scripts which themselves reference external files:

Format: Select all

{
	// relative includes are resolved against $HOME or %USERPROFILE% by default
	include 'main.groovy'
}

Groovy: Select all

// File: main.groovy

// relative includes in external script files are resolved against the current script file
include 'lib/function.groovy'

Note that csv() and friends also resolve relative file paths against your home directory or the current script file depending on the context.