Expression
Expressions can be used to configure actions. They are lazy evaluated - right before invoking action. An expression evaluates to a typed value. Terrabuild supports following types:
- Nothing
- String
- Boolean
- Number
- List
- Map
Type is inferred and the sole consequence of the evaluation.
Types
Nothing
Value for no value (pun intended). Similar to void
or None
in other languages.
Literal is nothing
.
String
A string is a sequence of characters. A string starts with "
and ends with "
:
"this is a string"
""
Boolean
Either literal true
or false
.
Number
A number is a 32 bits signed integer:
42
-123456
List
A list is an ordered sequence of values - values can be of different types:
[ 1 2 3 ]
[ 1 "value" 42]
As Terrabuild does not use comma separator, it’s better to format like this:
[ 1
2
3 ]
[ 1
"value"
42 ]
Map
A map is a collection of named values. Name is always an identifier. Values can be of different types.
{
configuration: "Release"
max: 42
}
{ a: 1 b: 2 }
As Terrabuild does not use comma separator, it’s better to format like this:
{ configuration: "Release"
max: 42 }
{ a: 1
b: 2 }
Functions
Functions can be applied on values.
String
Function | Description | Usage | Result |
---|---|---|---|
+ | concatenate two strings | "Hello" + "world" | "Hello world" |
trim | remove leading and trailing spaces | trim(" Hello world ") | "Hello world" |
upper | convert string to upper case | upper("Hello world") | "HELLO WORLD" |
lower | convert string to lower case | lower("Hello WORLD") | "hello world" |
version | get unique hash for project identifier. | version("/src/apps/webapp") | 159E0A6A3AEDE57BC71A3BD51037778423C7579FBAEC9CE93D47AB6BE3A9E786 |
Number
Function | Description | Usage | Result |
---|---|---|---|
+ | add two numbers | 5 + 2 | 7 |
- | substract two numbers | 5 - 2 | 3 |
List
Function | Description | Usage | Result |
---|---|---|---|
Item | Get item at position: error if index is not valid | [1 2 3].[1] | 2 |
TryItem | Try get item at position: nothing if index is not valid | [1 2 3].?[4] | nothing |
Map
Function | Description | Usage | Result |
---|---|---|---|
Item | Get named item (using identifier): error if index is not valid | { a: 1 b: 2 }.[b] | 2 |
TryItem | Try get named item (using identifier): nothing if index is not valid | { a: 1 b: 2 }.?[c] | nothing |
Item | Get named item (using string): error if index is not valid | { a: 1 b: 2 }.["b"] | 2 |
TryItem | Try get named item (using string): nothing if index is not valid | { a: 1 b: 2 }.?["c"] | nothing |
Variable
A variable can be used in an expression. A variable starts with $
followed by an identifier literal:
$configuration
$terrabuild_project
When expression is evaluated, the variable is replaced with its value (provided either in configuration
block or command line). A variable must be defined to evaluate correctly the expression.
Generic
Function | Description | Usage | Result |
---|---|---|---|
Equal | compares two values for equality | "env" = "prod" | false |
NotEqual | compares two values for inequality | "env" != "prod" | true |
Null-Coalesce | return value or alternate value if nothing | nothing ?? 42 | 42 |
Ternary Conditional | check boolean value and returns truthy or falsy value | nothing ? 42 : 666 | 666 |
Composition
Expressions can be composed: lower("ghcr.io/" + $org + $terrabuild_project)
Predefined variables
Several variables are defined and available when evaluating steps:
Name | Description |
---|---|
terrabuild_project | Name of current project |
terrabuild_target | Name of current target |
terrabuild_configuration | Name of current configuration |
terrabuild_branch_or_tag | Name of current branch or tag |
terrabuild_tag | Tag provided by user or nothing . |
terrabuild_note | Note provided by user or nothing . |
terrabuild_retry | true if build is retried. |
terrabuild_force | true if build is forced. |
terrabuild_ci | true if build is running in known CI. |