Expression Reference
Literals
Literal values can be used to insert data directly into an expression:
- Strings:
"How are you?",'How are you?' - Numbers:
40,30.123 - Arrays:
[1, 2, 3] - Objects:
{ one: 1, two: 2 } - Booleans:
true,false
Math
Expressions allow you to operate on values. The following operators are available:
- Addition:
+ - Subtraction:
- - Division:
/ - Division and integer truncation:
// - Division remainder:
% - Multiplication:
* - Power:
**
You can use them like this:
2 + 3
=> 5
10 / 5
=> 2
3 * 2
=> 6
Tests and Comparisons
Comparison operators may be used to return a Boolean based on the comparison result of two values:
- Equal (value only):
== - Strict Equal (value and type):
=== - Not Equal (value only):
!= - Strict Not Equal (value and type):
!== - Greater Than:
> - Greater Than Or Equal:
>= - Less Than:
< - Less Than Or Equal:
<=
Expressions also support an “if-else” syntax similar to Python. It can be used to choose from two values:
'Yes' if (variables.Foo == true) else 'No'
This is also useful for selecting default values when a variable is optional and may not be defined:
variables.Foo if variables.Foo else 'Foo'
Pipeline Helper Functions
The following top-level helper functions are available when running a pipeline. They’re used in pipeline step properties to help connect steps together.
findStepById(id)
Finds a step in the pipeline by id. Note that you can also access a step by steps.<id>
| Parameters | |
|---|---|
id | The id of the step to return. |
Returns
A step object, or null if there is no step with the given id. See the step module reference for examples.
findStepsByTag(tag)
Finds all steps in the pipeline with the given tag.
| Parameters | |
|---|---|
tag | The tag on the steps to find. |
Returns
An array of step objects. See the step module reference for examples.
findStepsByType(type)
Finds all steps in the pipeline with the given type.
| Parameters | |
|---|---|
type | The step type, such as “file”. |
Returns
An array of step objects. See the step module reference for examples.
findParentStepByType(type)
Searches a step’s parent dependency chain for the first step with the given type. If multiple parent steps are found at the same distance, an arbitrary parent will be chosen.
| Parameters | |
|---|---|
type | The type of step to return. |
Returns
A step object, or null if there is no parent step with the given type. See the step module reference for examples.
Other Helper Functions
The following top-level helper functions are available in any expression.
random_string(generator, length)
Generates a random string using one of several built-in generator functions.
| Parameters | |
|---|---|
generator | The type of string to generate. Allowed values: windowsPassword, alphaNumeric, alphaNumericLower, alphaNumericUpper, alpha, alphaLower, alphaUpper, numeric. |
length | The number of characters in the generated string. Defaults to 8. |
Returns
A randomly generated string.
Examples
To create a random password guaranteed to pass Windows validation (this also works for most Linux systems):
random_string('windowsPassword')
=> "kQi3n49S"
To create a sequence of 10 number characters:
random_string('numeric', 10)
=> "9234576823"
read_file(path, encoding)
Reads a local file on the runner. Only supports text files.
| Parameters | |
|---|---|
path | Local path to an existing file. |
encoding | Text encoding of the file. Defaults to “utf8”. |
Returns
The content of the file as a string.
Examples
To read a file called “example.txt” from the current run directory:
read_file("example.txt")
To read and parse a JSON file:
read_file("package.json") | parse_json
(read_file("package.json") | parse_json).version
credential(id)
Loads a credential’s data. This helper is not needed for step modules with credential support, however it is often useful for manipulating credential data directly in a pipeline step.
| Parameters | |
|---|---|
id | The ID of the credential to retrieve. |
Returns
A credential data object. See the credential reference for more information about credential types.
Examples
To retrive the password from a Username/Password credential with ID myCred:
credential("myCred").password
Filters
Filters are similar to helper functions, except they are “piped” an input value using the | character. For example,
[1, 2, 3] | join(',')
=> "1,2,3"
This allows chaining of filters to perform complex operations on data:
findStepsByTag('vm') | slice(2) | json_query('[*].properties.name') | join(',')
=> "vm1,vm2"
All filters from Nunjucks are available, as well as some additional filters that are listed below.
Filters used commonly in Refactr are documented in more detail here. For a complete list of built-in filters, see the Nunjucks built-in filters.
capitalize()
Make the first letter uppercase, and the rest lower case.
Returns
The capitalized string.
default(value)
Provides a default value when the filtered value is undefined.
| Parameters | |
|---|---|
value | The default value to use. |
Returns
The default value if the filtered value is undefined, otherwise the filtered value.
first()
Returns the first value of a list.
Returns
The first item.
last()
Returns the last value of a list.
Returns
The last item.
random()
Selects a random item from a list.
Returns
The randomly chosen item.
replace(search, value)
Replaces every occurence of search with value.
| Parameters | |
|---|---|
search | The string to be replaced. |
value | The replacement string. |
Returns
The new string with values replaced.
Examples
Replace hyphens with underscores in a string:
'foo-bar-baz' | replace('-', '_')
=> "foo_bar_baz"
join(delimiter)
Return a string which is the concatenation of the strings in a sequence.
| Parameters | |
|---|---|
delimiter | The character to insert between items. Optional. |
Returns
The joined string.
Examples
To convert an array of FQDN segments into a single FQDN string:
['app1', 'mydomain', 'com'] | join('.')
=> "app1.mydomain.com"
ternary(valueA, valueB)
This filter can be used instead of the if-else pattern. It is equivalent to the ternary operator in most programming languages.
Returns valueA if the filtered value is truthy, otherwise returns valueB.
| Parameters | |
|---|---|
valueA | Any value. |
valueB | Any value. |
Returns
valueA or valueB depending on the filtered value.
Examples
The following expression evaluates to “Yes” if the value of variables.Foo is true:
(variables.Foo == true) | ternary('Yes', 'No')
=> "Yes"
json_query(query)
The json_query filter lets you query a complex data structure. It can be used to select sub-values from an object or list of objects, like those returned by the find*() helper functions.
json_query utilizes JMESPath as the query language. Visit the JMESPath Examples page to learn more about JMESPath queries and to try out queries using their embedded tester.
| Parameters | |
|---|---|
query | The query string. |
Returns
The query result.
Examples
To retrieve a list of names from all steps tagged with the rdsh tag:
findStepsByTag('rdsh') | json_query('[*].properties.name')
=> ["Virtual Machine 1", "Virtual Machine 2"]
parse_json(str)
Parses a JSON string. JSON data structures can be represented natively in Refactr’s engine.
| Parameters | |
|---|---|
str | The string to parse. |
Returns
The result of parsing the JSON.
parse_yaml(str)
Parses a YAML string. At minimum, JSON-compatible YAML features are supported.
| Parameters | |
|---|---|
str | The string to parse. |
Returns
A dictionary data structure containing the parsed YAML.
parse_xml(str)
Parses an XML string, such as that returned by an HTTP response, into a dictionary data structure.
The dictionary contains keys matching the tag names in the XML. Attributes are placed in a sub-dictionary under the special $ key. Inner node text is placed under the special _ key. Child nodes are placed recursively as arrays in their respective tag keys, each having the same structure.
parse_xml utilizes xml2js to perform the parsing.
| Parameters | |
|---|---|
str | The string to parse. |
Returns
A dictionary data structure containing the parsed XML.
Examples
{| my_xml_string | parse_xml |}
Given an XML string:
<foo>
<bar name="1">Bar 1</bar>
<bar name="2">Bar 2</bar>
</foo>
parseXML will produce:
{
"foo": {
"bar": [
{
"_": "Bar 1",
"$": {
"name": "1"
}
},
{
"_": "Bar 2",
"$": {
"name": "2"
}
}
]
}
}
base64encode(str)
| Parameters | |
|---|---|
str | The UTF-8 string to encode. |
Returns The base64-encoded result.
Examples
'username:password' | base64encode
=> dXNlcm5hbWU6cGFzc3dvcmQ=
base64decode(str)
| Parameters | |
|---|---|
str | The base64-encoded string to decode. |
Returns
The UTF-8 decoded result.
Examples
'dXNlcm5hbWU6cGFzc3dvcmQ=' | base64decode
=> username:password
Test Expressions
Test expressions perform a comparison or check, and evaluate to true or false. They use the “is” syntax:
<expression to test> is <test function>
e.g., the following expression evaluates to true if the step with id step1 has the content property defined:
steps.step1.properties.content is defined
The following test functions are available:
equalto(value)
Returns true if the input is strictly equal to the value, and false otherwise. Aliased as sameas(value) and eq(value).
ne(value)
Returns true if the input is not strictly equal to the value, and false otherwise.
defined()
Returns true if the input is defined, and false otherwise.
undefined()
Returns true if the input is undefined, and false otherwise.
divisibleby(value)
Returns true if the input is divisible by the value, and false otherwise.
even()
Returns true if the input is an even number, and false otherwise.
odd()
Returns true if the input is an odd number, and false otherwise.
falsy()
Returns true if the input is truthy, which includes false, 0, null, undefined, and empty strings, and false otherwise.
truthy()
Returns true if the input is truthy, which includes true, 1, and non-empty strings, and false otherwise.
greaterthan(value)
Returns true if the input is greater than the value, and false otherwise. Aliased as gt().
lessthan(value)
Returns true if the input is less than the value, and false otherwise. Aliased as lt().
lower()
Returns true if the input is an all-lowercase string , and false otherwise.
upper()
Returns true if the input is an all-uppercase string, and false otherwise.
null()
Returns true if the input is null, and false otherwise.
number()
Returns true if the input is a number, and false otherwise.
string()
Returns true if the input is a string, and false otherwise.
iterable()
Returns true if the input is iterable, which includes arrays and strings, and false otherwise.
