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. Functions take a tuple as argument (param1, param2) which can be built from aforementioned primitives.

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`
replace	replace in string.	`replace("Hello world", "world", "Terrabuild")`	`Hello Terrabuild`
format	format a string.	`format("Hello", " ", "Terrabuild")`	`Hello Terrabuild`

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`
Count	Get number of element of list	`count([1 2 3])`	`3`
+	Concatenate two lists	`[1 2 3] + [4 5 6]`	`[1 2 3 4 5 6]`

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`
Count	Get number of element of map	`count({ a: 1 b: 2 })`	`2`
+	Merge two maps	`{ a: 1 b: 1} + { b: 2 c: 2}`	`{ a: 1 b: 2 c: 2}`

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
Not	`true` if falsy (`nothing` or `false`)	`!false`	`true`
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	checks 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_hash`	Hash of current project
`terrabuild_configuration`	Name of current configuration
`terrabuild_branch_or_tag`	Name of current branch or tag
`terrabuild_head_commit`	Head commit commit
`terrabuild_retry`	`true` if build is retried.
`terrabuild_force`	`true` if build is forced.
`terrabuild_ci`	`true` if build is running in known CI.
`terrabuild_debug`	`true` if debug is enabled.
`terrabuild_tag`	Tag provided by user or `nothing`.
`terrabuild_note`	Note provided by user or `nothing`.

Last updated on November 7, 2024

Attribute Identifier