-
Notifications
You must be signed in to change notification settings - Fork 0
Command Reference
⚠️ ⚠️ THIS WIKI IS BEING USED TO JOT DOWN IDEAS AT PRESENT. DON'T ASSUME ANYTHING IS FIXED.⚠️ ⚠️
All predefined @ commands are listed here.
Command labelled ⛔ are not yet implemented.
⛔ 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.
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.
⛔ 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 ; }}
⛔ 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 exist then Null is returned.
Parameter: Name of the environment variable, type Text.
Return type: Text or Null
⛔ Returns a Boolean false value.
This command is useful in arguments whenever a Boolean false value is required.
Parameters: none
Return type: Boolean
Returns the file path 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 < {{ @file-path-sep }} > append < "bar" }}
This placeholder resolves as foo\bar on Windows and foo/bar on Linux.
⛔ 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 an object describing the directory where rpt is installed.
Use filters to extract detailed file information.
Parameters: none
Return type: Directory
⛔ 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.
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