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

FunctionDescriptionUsageResult
+concatenate two strings"Hello" + "world""Hello world"
trimremove leading and trailing spacestrim(" Hello world ")"Hello world"
upperconvert string to upper caseupper("Hello world")"HELLO WORLD"
lowerconvert string to lower caselower("Hello WORLD")"hello world"
versionget unique hash for project identifier.version("/src/apps/webapp")159E0A6A3AEDE57BC71A3BD51037778423C7579FBAEC9CE93D47AB6BE3A9E786

Number

FunctionDescriptionUsageResult
+add two numbers5 + 27
-substract two numbers5 - 23

List

FunctionDescriptionUsageResult
ItemGet item at position: error if index is not valid[1 2 3].[1]2
TryItemTry get item at position: nothing if index is not valid[1 2 3].?[4]nothing

Map

FunctionDescriptionUsageResult
ItemGet named item (using identifier): error if index is not valid{ a: 1 b: 2 }.[b]2
TryItemTry get named item (using identifier): nothing if index is not valid{ a: 1 b: 2 }.?[c]nothing
ItemGet named item (using string): error if index is not valid{ a: 1 b: 2 }.["b"]2
TryItemTry 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

FunctionDescriptionUsageResult
Equalcompares two values for equality"env" = "prod"false
NotEqualcompares two values for inequality"env" != "prod"true
Null-Coalescereturn value or alternate value if nothingnothing ?? 4242
Ternary Conditionalcheck boolean value and returns truthy or falsy valuenothing ? 42 : 666666

Composition

Expressions can be composed: lower("ghcr.io/" + $org + $terrabuild_project)

Predefined variables

Several variables are defined and available when evaluating steps:

NameDescription
terrabuild_projectName of current project
terrabuild_targetName of current target
terrabuild_configurationName of current configuration
terrabuild_branch_or_tagName of current branch or tag
terrabuild_tagTag provided by user or nothing.
terrabuild_noteNote provided by user or nothing.
terrabuild_retrytrue if build is retried.
terrabuild_forcetrue if build is forced.
terrabuild_citrue if build is running in known CI.
⚠️
Please note you can’t mix types in expressions.
Last updated on