Reference

Table of Contents  ▸  Substitution Rules◀  Input/Output Properties    |    Mathematical Expressions  ▶

Substitution Rules

items containing $ or {} are substituted before being interpreted. Use these substituting expressions to access various data from the interpreter environment.
$name and ${name} are both substituted by the value of the specified named variable (set previously by the item name=value). If this variable has not been already set, the expression is substituted by the highest positive index of the named image [name]. If no image has this name, the expression is substituted by the value of the OS environment variable with same name (it may be thus an empty string if it is not defined).
The following reserved variables are predefined by the interpreter:
$!: The current number of images in the list.
$> and $<: The increasing/decreasing index of the latest (currently running) repeat...done loop. $> goes from 0 (first loop iteration) to nb_iterations - 1 (last iteration). $< does the opposite.
$/: The current call stack. Stack items are separated by slashes /.
$|: The current value (expressed in seconds) of a millisecond precision timer.
$^: The current verbosity level.
$_cpus: The number of computation cores available on your machine.
$_pid: The current process identifier, as an integer.
$_prerelease: For pre-releases, the date of the pre-release as yymmdd. For stable releases, this variable is set to 0.
$_version: A 3-digits number telling about the current version of the interpreter (e.g. 294).
$_host: A string telling about the host running the interpreter (e.g. cli or gimp).
$_vt100: Set to 1 if colored text output is allowed on the console. Otherwise, set to 0.
$_path_rc: The path to the folder used to store configuration files (its value is OS-dependent).
$_path_user: The path to the user file .gmic or user.gmic (its value is OS-dependent).
$_path_commands: A list of all imported command files (stored as a list-valued variable).

$$name and $${name} are both substituted by the script code of the specified named custom command, or by an empty string if no custom command with specified name exists.
${"-pipeline"} is substituted by the status value after the execution of the specified pipeline (see command status). Expression ${} thus stands for the current status value.
{``string} (starting with two backquotes) is substituted by a double-quoted version of the specified string.
{/string} is substituted by the escaped version of the specified string.
{'string'[:delimiter]} (between single quotes) is substituted by the sequence of character codes that composes the specified string, separated by specified delimiter. Possible delimiters are , (default), ;, /, ^ or . For instance, item {'foo'} is substituted by 102,111,111 and {'foo':;} by 102;111;111.
{image,feature[:delimiter]} is substituted by a specific feature of the image [image]. image can be either an image number or an image name. It can be also eluded, in which case, the last image [-1] of the list is considered for the requested feature. Specified feature can be one of:
b: The image basename (i.e. filename without the folder path nor extension).
f: The image folder name.
n: The image name or filename (if the image has been read from a file).
t: The text string from the image values regarded as character codes.
x: The image extension (i.e the characters after the last . in the image name).
^: The sequence of all image values, separated by commas ,.
@subset: The sequence of image values corresponding to the specified subset, and separated by commas ,.
Any other feature is considered as a mathematical expression associated to the image [image] and is substituted by the result of its evaluation (float value). For instance, expression {0,w+h} is substituted by the sum of the width and height of the first image (see section Mathematical Expressions for more details). If a mathematical expression starts with an underscore _, the resulting value is truncated to a readable format. For instance, item {_pi} is substituted by 3.14159 (while {pi} is substituted by 3.141592653589793).
A feature delimited by backquotes is replaced by a string whose character codes correspond to the list of values resulting from the evaluation of the specified mathematical expression. For instance, item {[102,111,111]} is substituted by foo and item {vector8(65)} by AAAAAAAA.

{*} is substituted by the visibility state of the instant display window #0] (can be { 0=closed | 1=visible }.
{*[index],feature1,...,featureN[:delimiter]} is substituted by a specific set of features of the instant display window #0 (or #index, if specified). Requested features can be:
w: display width (i.e. width of the display area managed by the window).
h: display height (i.e. height of the display area managed by the window).
wh: display width x display height.
d: window width (i.e. width of the window widget).
e: window height (i.e. height of the window widget).
de: window width x window height.
u: screen width (actually independent on the window size).
v: screen height (actually independent on the window size).
uv: screen width x screen height.
n: current normalization type of the instant display.
t: window title of the instant display.
x: X-coordinate of the mouse position (or -1, if outside the display area).
y: Y-coordinate of the mouse position (or -1, if outside the display area).
b: state of the mouse buttons { 1=left-but. | 2=right-but. | 4=middle-but. }.
o: state of the mouse wheel.
k: decimal code of the pressed key if any, 0 otherwise.
c: boolean (0 or 1) telling if the instant display has been closed recently.
r: boolean telling if the instant display has been resized recently.
m: boolean telling if the instant display has been moved recently.
Any other feature stands for a keycode name (in capital letters), and is substituted by a boolean describing the current key state { 0=pressed | 1=released }.
You can also prepend a hyphen - to a feature (that supports it) to flush the corresponding event immediately after reading its state (works for keys, mouse and window events).

Item substitution is never performed in items between double quotes. One must break the quotes to enable substitution if needed, as in "3+8 kg = "{3+8}" kg". Using double quotes is then a convenient way to disable the substitutions mechanism in items, when necessary.
One can also disable the substitution mechanism on items outside double quotes, by escaping the {, } or $ characters, as in \{3+4\}\ doesn't\ evaluate.

◀  Input/Output Properties    |    Mathematical Expressions  ▶