-
Notifications
You must be signed in to change notification settings - Fork 0
Command Reference
All predefined @ commands are listed here.
🗒️ Commands with a ⛔ suffix are not yet implemented, those suffixed 🚧 are under development and those suffixed ❓ are being considered for removal. Commands with no suffix have been implemented and tested.
⚠️ Commands on this page are subject to change or removal.
Creates an array with an element for each parameter. Elements can have any type and do not have to be all the same type.
Parameters: zero or more parameters, type Any.
Output type: Array
Example arrays:
Text array: {{ @array < "Lorem", "ipsum", "delor" }}
Int array with unset element: {{ @array < 1, 2, 3, {{ @null }}, 5, 6}}
File object array: {{ @array < {{ @construct < "File","c:\foo\bar.txt" }}, {{ @construct < "File","c:\alice\bob.txt" }} }}
Mixed array: {{ @array < "Alice", 42, "Bob", 56.6 }}
Empty array: {{ @array }}
The output of the above placeholders is:
Text array: ["Lorem", "ipsum", "delor"]
Int array with unset element: [1, 2, 3, , 5, 6]
File object array: ["c:\foo\bar.txt", "c:\alice\bob.txt"]
Mixed array: ["Alice", 42, "Bob", 56.6]
Empty array: []
🗒 @array < a,b,c is a shorthand for @construct "Array", a,b,c
Converts the parameter into a Boolean value, depending on the parameter's truthiness. Truthy and falsy values for different types are described on the Data Types page.
Parameter: the value to that is to be converted, Any type.
Return type: Boolean
For example, consider the following code where foo is a variable:
{{ bar := @bool < foo ; }}
bar will be set to @true if foo = 42 (i.e. truthy) while bar will be set to @false if foo = 0 (i.e. falsey).
🗒️ {{ @bool < param }} is shorthand for {{ @construct < "Boolean",param }}
Returns a concatenation of all its parameters. Each parameter is converted to text using its data type's default text converter and is then appended to the text to be output. Parameters are processed from left to right, with the text value of the first parameter being the first text in the output.
Where only one parameter is provided it is converted to text and returned.
Note that @concat with one parameter differs from @echo in that @echo performs no type conversion while @concat converts the parameter to Text.
If any parameter is has type Array then each element of the array is treated as a separate parameter. Nested arrays are recursed.
Parameters: one or more of Any type.
Return type: Text
For example:
{{ @concat < 42, {{ 'foo' > upcase }}, {{ @null }}, 56.9 }}
returns 42FOO56.9. Note that {{ @null }} gets converted to an empty string and so has no effect on the output.
Another example that shows how arrays are treated:
{{ @concat < 42, ['foo', 'bar', 56], 99 }}
is equivalent to:
{{ @concat < 42, 'foo', 'bar', 56, 99 }}
which returns 42foobar5699.
Returns a concatenation of all its parameters except the first. with each concatenated param separated by the text of the first parameter. Each concatenated parameter is converted to text using its data type's default text converter and is then appended to the text to be output. Parameters are processed from left to right, with the text value of the second parameter being the first text in the output.
Where only one parameter is given an any string is returned. Where two parameters are given the text value of the second parameter is returned.
Parameters:
- Separator to use, type Text.
- Zero or more parameters to be concatenated, each of type Any.
Return type: Text
For example:
{{ @concat-sep < "|", 42, {{ 'foo' > upcase }}, {{ @null }}, 56.9 }}
returns 42|FOO||56.9. Note that {{ @null }} gets converted to an empty string which is why there is an adjacent pair of pipe characters in the output.
Another example that shows how arrays are treated:
{{ @concat-sep < ', ', 42, ['foo', 'bar', 56], 99 }}
is equivalent to:
{{ @concat < ', ', 42, 'foo', 'bar', 56, 99 }}
which returns 42, foo, bar, 56, 99.
Constructs and returns a new data object of a given type.
Parameters
- The name of the type of object to be constructed. Must be the name of a supported type - see Data Types for a list. Case is ignored. Type Text.
- Zero or more parameters to be passed to the constructor for the required data type. The number and type of parameters depends on the required object's data type.
Return type: the type of the object being constructed.
Examples
{{ t := @construct < "Text", "Lorem ipsum" ; }}
{{ f := @construct < "File", "C:\alice\bob\clara.txt" ; }}
{{ d := @construct < "DateTime", 2023,02,10,13,34 ; }}
{{ t }} : {{ f > fs-name }} : {{ d | month-name }}
Outputs
Lorem ipsum : clara.txt : February
🗒️ Notes
-
Using
@constructto construct a Text object as shown above is not strictly necessary since a literal string can simply be assigned to the variable, as in{{ t := "Lorem ipsum"; }}. However, behind the scenes rpt translates the string literal assignment into a call to@construct. Other simple types, e.g. Int and Boolean can be easily constructed by direct assignment of a literal value, but more complex types, e.g. File and DateTime, can only be constructed by calling@construct. -
Some filters can also be used to construct complex objects on the fly. For example, the following placeholder creates a Directory object:
{{ d := "C:\alice\bob" > to-dir ; }}
Creates and returns a DateTime value from the provided Int parameters.
Parameters: seven Int values, of which the last four are optional, as follows:
- year (required). An Int >=
1900. - month (required). An Int in the range [
1..12]. - day (required). An Int in the range [
1..31]. - hour (optional: default is
0). An Int in the range [0..23]. - minute (optional: default is
0). An Int in the range [0..59]. - second (optional: default is
0). An Int in the range [0..59]. - micro second (option: default is
0). An Int in the range [0..999].
If there is an error in conversion, if parameters are out of range or if any parameter is not Int then Null is returned.
Output type: DateTime | Null on error.
Examples:
{{ @datetime < 2026, 4, 17, 14, 21, 59, 123 }}
{{ @datetime < 1959, 1, 3 }}
The output of the above placeholders is:
2026-04-17T14:21:59.123Z
1959-01-03T00:00:00.000Z
🗒 @datetime < a,b,c,d,e,f,g is a shorthand for @construct "Array", a,b,c,d,e,f,g
Creates and returns a Directory value from the provided Text parameter.
Parameters: Type is Text. The name of the directory as Text. The parameter is required. An empty string is permitted. A fully specified path or a relative path are both permitted.
The directory separator character should be the correct one for the operating system, i.e. \ on Windows and / on Linux.
🗒️ On Windows
/is an alternative directory separator and can be specified instead of\. All occurrences of/will be replaced by\.🗒️ On Linux
\is a valid directory name character and is not an alternative for/, so\is not converted to/.
⚠️ When the directory name is specified as a string literal,\must be escaped, e.g. "\foo\bar".
⚠️ To include a\in a Linux directory name it must be escaped, i.e.\\. Therefore to include such a name in a string literal parameter\\need to be escaped again to\\\\.
If any error occurs then a Null value is returned.
Return type: Directory | Null.
Examples:
Backslash separator: {{ @directory < "foo\\bar\\" }}
Forward slash separator: {{ @directory < "foo/bar/" }}
returns
Backslash separator: foo\bar\
Forward slash separator: foo\bar\
on Windows and
Backslash separator: foo\bar\
Forward slash: foo/bar/
on Linux.
🗒 @directory < "/foo/bar/" is the equivalent of @construct < "Directory", "/foo/bar/".
Returns the directory separator used by the operating system. This is \ on Windows and / on Unix/Linux based systems.
Parameters: none
Return type: Text
In the following example directory foo and subdirectory bar are joined together into a relative path:
{{ "foo" > append < {{ @directory-sep }} > append < "bar" }}
This placeholder resolves as foo\bar on Windows and foo/bar on Linux.
Returns the value of its sole parameter.
This command is used under the cover to process string literal, numeric literal, variable and recursive placeholder sources in placeholders. It need not (but can) be called directly.
Parameters: value to be processed, any type
Return type: same type as parameter
For example the following placeholders:
{{ 'example text' }}
{{ 42 }}
{{ 5.6 }}
{{ my_variable }}
{{ {{ @command > inner_filter }} > outer_filter }}
are equivalent to
{{ @echo < 'example text' }}
{{ @echo < 42 }}
{{ @echo < 5.6 }}
{{ @echo < my_variable }}
{{ @echo < {{ @command > inner_filter }} > outer_filter }}
respectively.
Returns the value of an environment variable whose name is passed as a parameter. If the environment variable doesn't then an empty Text value returned. If the name is empty or a the parameter is not Text then a Null value is returned.
Parameter: Name of the environment variable, type Text.
Return type: Text or Null
Returns an object describing the fully specified file from which rpt was executed.
Use filters to extract detailed file information.
Parameters: none
Return type: File
Returns a Boolean false value.
This command is useful in arguments whenever a Boolean false value is required.
Parameters: none
Return type: Boolean
Creates and returns a File value from the provided Text parameter.
Parameters: Type is Text. The name of the file as Text. The parameter is required. An empty string is permitted. As simple file name, fully specified path or a relative path are all permitted.
Directory separator characters a adjusted to be correct for the underlying operating system, i.e. \ or Windows or / on Linux.
If the file name includes directory separators, they should be the correct one for the operating system, i.e. \ on Windows and / on Linux.
🗒️ On Windows
/is an alternative separator and can be specified instead of\. All occurrences of/will be replaced by\.🗒️ On Linux
\is a valid file name character and is not an alternative for/, so\is not converted to/.
⚠️ When the file name is specified as a string literal,\must be escaped, e.g. "\foo\bar".
⚠️ To include a\in a Linux file name it must be escaped, i.e.\\. Therefore to include such a name in a string literal parameter\\need to be escaped again to\\\\.
If any error occurs then a Null value is returned.
Return type: File | Null.
Examples:
Backslash separator: {{ @directory < "foo\\bar\\baz.txt" }}
Forward slash separator: {{ @directory < "foo/bar/baz.txt" }}
returns
Backslash separator: foo\bar\baz.txt
Forward slash separator: foo\bar\baz.txt
on Windows and
Backslash separator: foo\bar\baz.txt
Forward slash: foo/bar/baz.txt
on Linux.
🗒 @file < "/foo/bar/baz.txt" is the equivalent of @construct < "File", "/foo/bar/baz.txt".
Returns the value of the 2nd parameter if the 1st parameter is truthy or returns the 3rd parameter otherwise.
This command is equivalent to the @unless command with its first parameter logically negated.
Parameters:
- parameter to test for truthiness, type Any.
- parameter whose value is returned if parameter 1 is truthy, type Any.
- parameter whose value is returned if parameter 1 is falsey, type Any. (May be omitted, in which case Null is returned.)
Return type: Any (The type is that of the returned parameter).
For example, given a variable us-english, the following placeholder outputs color if us-english is truthy or colour otherwise:
{{ @if < us-english,'color','colour' }}
Returns the content of the file whose name or object is passed as a parameter. If the included file contains placeholders they are evaluated and resolved before @include returns.
Parameters: type Text (file name) or File object.
Return type: Text
Returns the content of the file whose name, relative to the project directory, is passed as a parameter. If the included file contains placeholders they are evaluated and resolved before @include-relative returns.
Parameters: relative file name, type Text.
Return type: Text
🗒 @include-relative is effectively shorthand for:
{{ file := @construct < "File", {{ @project-dir }}, rel-path ; }}
{{ @include < file }}
where rel-path is the relative file name passed as a parameter.
Returns an object providing details about the input text file currently being processed.
Use filters to extract detailed file information.
If input is being read from standard input rather than a file then Null will be returned.
Parameters: none
Return type: File or Null
Returns the largest of all the command's parameters.
Parameters: one or more Numeric parameters
Return type: Int if all parameters are type Int or Float if at least one parameter is a Float.
Examples:
{{ @max < 3, 5 }}
{{ @max < 3.4, 2.3, 7.8, 1.6 }}
{{ @max < 3, 4.2, 5 }}
Results:
5
7.8
5.0
Note that, in the 3rd example, Int 5 gets converted to a Float, because one parameter is a Float.
Returns the smallest of all the command's parameters.
Parameters: one or more Numeric parameters
Return type: Int if all parameters are type Int or Float if at least one parameter is a Float.
Examples:
{{ @min < 3, 5 }}
{{ @min < 3.4, 2.3, 7.8, 1.6 }}
{{ @min < 3, 4.2, 5 }}
Results:
3
1.6
3.0
Note that, in the 3rd example, Int 3 gets converted to a Float, because one parameter is a Float.
Returns the default newline character sequence for the operating system, i.e. \r\n for Windows and \n for Linux/Unix based systems.
Parameters: none
Return type: Text
The following example shows how to append the system newline to text:
{{ "Lorem ipsum" > append < {{ @newline }} }}
This second example shows how to ensure all newlines in an included file are correct for the operating system:
{{ @include < "c:\myfile.txt" > replace-newlines < {{ @newline }} }}
Returns the date and time that rpt was executed as UTC.
Use filters to format the date as required.
Parameters: none
Return type: DateTime
Returns the null value.
The main use case for this command is for use in variable assignments to clear a variable's value, i.e to unset the variable.
Parameters: none
Return type: Null
Here is an example of unsetting variable foo:
{{ foo := 42 ; }}
foo is {{ @if < {{ foo > is-null }}, "unset", foo }}
{{ foo := @null ; }}
foo is now {{ @if < {{ foo > is-null }}, "unset", foo }}
Assuming filter is-null returns true iff its input is Null, the above code renders as:
foo is 42
foo is now unset
🗒️ {{ @null }} is shorthand for {{ @construct < "Null" }}
Returns an object giving information about the operating system on which the program is being run.
Use filters to extract various pieces of information, such as folder names, version data, etc.
The default string value is a description of the Windows version.
Parameters: none
Return type: OS
🗒️ {{ @os }} is shorthand for {{ @construct < "OS" }}
Returns an object providing details about the output file currently being processed.
Use filters to extract detailed file information.
If input is being written to standard output rather than a file then Null will be returned.
Parameters: none
Return type: File or Null
Returns an object describing the project directory. Defaults to the directory from where any variables definition file was loaded, but can be overridden on the command line.
Use filters to extract detailed directory information.
Parameters: none
Return type: Directory
Returns a Boolean true value.
This command is useful in arguments whenever a Boolean true value is required.
Parameters: none
Return type: Boolean
Returns the value of the 2nd or parameter unless the 1st parameter is truthy in which case the 3rd parameter is output.
This command is equivalent to the @if command with its first parameter logically negated.
Parameters:
- parameter to test for truthiness, type Any.
- parameter whose value is returned if parameter 1 is falsey, type Any.
- parameter whose value is returned if parameter 1 is truthy, type Any. (May be omitted, in which case Null is returned.)
Return type: Any (Same type as returned parameter).
For example, given a variable us-english, the following placeholder outputs colour unless us-english is truthy in which case color is output:
{{ @unless < us-english,'colour','color' }}
Returns the value of the variable whose name is passed as a parameter.
This command is used under the cover to process variable names and need not (but can) be called directly. A variable name, say myvar is actually an alias for @var < "myvar".
If the named variable does not exist then @var returns Null.
As an aside, this means that you can get the name of a variable from a placeholder by using:
{{ @var < {{ alias }} }}
where alias is a variable whose value is the name of the variable we want! Of course alias could be passed through filters to get the desired name.
Parameters: name of variable of type Text
Return type: Text or Null
Returns the version number of the program in the standard format used for semantic versioning.
Parameters: none
Return type: Text
Returns an object describing the program's working directory.
Use filters to extract detailed directory information.
Parameters: none
Return type: Directory