Table of Contents  ▸  Adding Custom Commands◀  Image and Data Viewers    |    List of Commands  ▶

Adding Custom Commands

New custom commands can be added by the user, through the use of G'MIC custom commands files.
A command file is a simple text file, where each line starts either by
command_name: command_definition
command_definition (continuation)

At startup, G'MIC automatically includes user's command file $HOME/.gmic (on Unix) or %APPDATA%/user.gmic (on Windows). The CLI tool gmic automatically runs the command cli_start if defined.
Custom command names must use character set [a-zA-Z0-9_] and cannot start with a number.
Any # comment expression found in a custom commands file is discarded by the G'MIC parser, wherever it is located in a line.
In a custom command, the following $-expressions are recognized and substituted:
$* is substituted by a copy of the specified string of arguments.
$"*" is substituted by a copy of the specified string of arguments, each being double-quoted.
$# is substituted by the maximum index of known arguments (either specified by the user or set to a default value in the custom command).
$[] is substituted by the list of selected image indices that have been specified in the command invocation.
$? is substituted by a printable version of $[] to be used in command descriptions.
$i and ${i} are both substituted by the i-th specified argument. Negative indices such as ${-j} are allowed and refer to the j-th latest argument. $0 is substituted by the custom command name.
${i=default} is substituted by the value of $i (if defined) or by its new value set to default otherwise (default may be a $-expression as well).
${subset} is substituted by the argument values (separated by commas ,) of a specified argument subset. For instance expression ${2--2} is substituted by all specified command arguments except the first and the last one. Expression ${^0} is then substituted by all arguments of the invoked command (eq. to $* if all arguments have been indeed specified).
$=var is substituted by the set of instructions that will assign each argument $i to the named variable var$i (for i in [0...$#]. This is particularly useful when a custom command want to manage variable numbers of arguments. Variables names must use character set [a-zA-Z0-9_] and cannot start with a number.

These particular $-expressions for custom commands are always substituted, even in double-quoted items or when the dollar sign $ is escaped with a backslash $. To avoid substitution, place an empty double quoted string just after the $ (as in $""1).
Specifying arguments may be skipped when invoking a custom command, by replacing them by commas , as in expression
flower ,,3
 Omitted arguments are set to their default values, which must be thus explicitly defined in the code of the corresponding custom command (using default argument expressions as ${1=default}).
If one numbered argument required by a custom command misses a value, an error is thrown by the G'MIC interpreter.
It is possible to specialize the invokation of a +command by defining it as
+command_name: command_definition
A +-specialization takes priority over the regular command definition when the command is invoked with a prepended +.
When only a +-specialization of a command is defined, invoking command is actually equivalent to +command.

◀  Image and Data Viewers    |    List of Commands  ▶