Skip to main content

Built-in Functions

Phobos provides the following built-in HCL functions that can be used in your pipeline templates and release lifecycle templates:

Collection functions​

chunklist(list, chunk_size)​

Divides a list into smaller sublists of a specified size, useful for batch processing or organizing data into groups.

chunklist(["a", "b", "c", "d"], 2)
# Returns: [["a", "b"], ["c", "d"]]

coalescelist(list1, list2, ...)​

Returns the first list that contains at least one element, providing a fallback mechanism for empty lists.

coalescelist([], ["a", "b"])
# Returns: ["a", "b"]

compact(list)​

Filters out null values and empty strings from a list, cleaning up sparse data structures.

compact(["a", "", "b", null])
# Returns: ["a", "b"]

concat(list1, list2, ...)​

Merges multiple lists into a single list while preserving order, useful for combining data from different sources.

concat(["a"], ["b", "c"])
# Returns: ["a", "b", "c"]

contains(list, value)​

Tests whether a list includes a specific value, returning true if found and false otherwise.

contains(["a", "b"], "a")
# Returns: true

distinct(list)​

Removes duplicate values from a list while preserving the order of first occurrence.

distinct(["a", "b", "a"])
# Returns: ["a", "b"]

element(list, index)​

Retrieves a specific item from a list using zero-based indexing, with wraparound for negative indices.

element(["a", "b", "c"], 1)
# Returns: "b"

flatten(list)​

Converts nested lists into a single flat list, useful for processing hierarchical data structures.

flatten([["a"], ["b", "c"]])
# Returns: ["a", "b", "c"]

hasindex(list, index)​

Checks whether a list has an element at the specified index position without causing an error.

hasindex(["a", "b"], 1)
# Returns: true

index(list, value)​

Finds the position of a value in a list or retrieves a value from a map using a key.

index(["a", "b"], "b")
# Returns: 1

keys(map)​

Extracts all keys from a map and returns them as a list, useful for iterating over map properties.

keys({a = 1, b = 2})
# Returns: ["a", "b"]

length(value)​

Counts the number of elements in a collection (list, map, tuple, or string).

length(["a", "b", "c"])
# Returns: 3

lookup(map, key, default)​

Safely retrieves a value from a map by key, returning a default value if the key doesn't exist.

lookup({a = 1}, "b", 0)
# Returns: 0

merge(map1, map2, ...)​

Combines multiple maps into one, with later maps overriding values from earlier ones for duplicate keys.

merge({a = 1}, {b = 2})
# Returns: {a = 1, b = 2}

range(start, limit, step)​

Creates a sequence of numbers from start to limit (exclusive) with a specified step increment.

range(1, 4, 1)
# Returns: [1, 2, 3]

reverse(list)​

Returns a new list with elements in reverse order, useful for processing data backwards.

reverse(["a", "b", "c"])
# Returns: ["c", "b", "a"]

slice(list, start_index, end_index)​

Extracts a portion of a list from start index to end index (exclusive), similar to array slicing.

slice(["a", "b", "c"], 1, 3)
# Returns: ["b", "c"]

sort(list)​

Arranges list elements in ascending order, useful for organizing data alphabetically or numerically.

sort(["c", "a", "b"])
# Returns: ["a", "b", "c"]

values(map)​

Extracts all values from a map and returns them as a list, complementing the keys function.

values({a = 1, b = 2})
# Returns: [1, 2]

zipmap(keyslist, valueslist)​

Creates a map by pairing elements from a keys list with corresponding elements from a values list.

zipmap(["a", "b"], [1, 2])
# Returns: {a = 1, b = 2}

Set functions​

setintersection(sets...)​

Finds elements that exist in all provided sets, useful for identifying common values across multiple collections.

setintersection(["a", "b"], ["b", "c"])
# Returns: ["b"]

setproduct(sets...)​

Generates all possible combinations by taking one element from each set, creating a Cartesian product.

setproduct(["a"], [1, 2])
# Returns: [["a", 1], ["a", 2]]

setsubtract(set1, set2)​

Returns elements from the first set that are not present in the second set, performing set difference.

setsubtract(["a", "b"], ["b"])
# Returns: ["a"]

setunion(sets...)​

Merges multiple sets into one, removing duplicates while preserving unique elements from all sets.

setunion(["a"], ["b", "a"])
# Returns: ["a", "b"]

sethaselement(set, value)​

Tests whether a set contains a specific element, providing a safe way to check membership.

sethaselement(["a", "b"], "a")
# Returns: true

setsymmetricdifference(set1, set2)​

Returns elements that exist in either set but not in both, finding the symmetric difference.

setsymmetricdifference(["a", "b"], ["b", "c"])
# Returns: ["a", "c"]

String functions​

chomp(string)​

Removes trailing newline characters and carriage returns from a string, useful for cleaning input data.

chomp("hello\n")
# Returns: "hello"

format(string, values...)​

Creates formatted strings using printf-style placeholders, enabling dynamic string construction.

format("Hello %s", "world")
# Returns: "Hello world"

formatlist(format, values...)​

Applies a format string to each element in a list, creating a list of formatted strings.

formatlist("item-%s", ["a", "b"])
# Returns: ["item-a", "item-b"]

indent(num_spaces, string)​

Adds a specified number of spaces to the beginning of each line in a multi-line string.

indent(2, "line1\nline2")
# Returns: "  line1\n  line2"

join(separator, list)​

Concatenates list elements into a single string using a specified delimiter between elements.

join(",", ["a", "b", "c"])
# Returns: "a,b,c"

lower(string)​

Converts all characters in a string to lowercase, useful for case-insensitive comparisons.

lower("HELLO")
# Returns: "hello"

regex(string, pattern)​

Extracts the first substring that matches a regular expression pattern from the input string.

regex("hello123", "[0-9]+")
# Returns: "123"

regexall(string, pattern)​

Finds all substrings that match a regular expression pattern and returns them as a list.

regexall("a1b2c3", "[0-9]")
# Returns: ["1", "2", "3"]

regex_replace(string, pattern, replacement)​

Replaces all occurrences of a regular expression pattern with a replacement string.

regex_replace("hello123", "[0-9]+", "world")
# Returns: "helloworld"

replace(string, substr, replacement)​

Substitutes all occurrences of a substring with a replacement string, performing literal matching.

replace("hello", "ll", "xx")
# Returns: "hexxo"

split(separator, string)​

Divides a string into a list of substrings using a specified delimiter character or string.

split(",", "a,b,c")
# Returns: ["a", "b", "c"]

strlen(string)​

Calculates the number of characters in a string, including spaces and special characters.

strlen("hello")
# Returns: 5

strrev(string)​

Reverses the order of characters in a string, useful for certain text processing operations.

strrev("hello")
# Returns: "olleh"

substr(string, offset, length)​

Extracts a portion of a string starting at a specified position for a given number of characters.

substr("hello", 1, 3)
# Returns: "ell"

title(string)​

Capitalizes the first letter of each word in a string, creating title case formatting.

title("hello world")
# Returns: "Hello World"

trim(string, cutset)​

Removes specified characters from both the beginning and end of a string.

trim("!!hello!!", "!")
# Returns: "hello"

trimprefix(string, prefix)​

Removes a specified prefix from the beginning of a string if it exists.

trimprefix("hello", "he")
# Returns: "llo"

trimspace(string)​

Removes whitespace characters (spaces, tabs, newlines) from both ends of a string.

trimspace("  hello  ")
# Returns: "hello"

trimsuffix(string, suffix)​

Removes a specified suffix from the end of a string if it exists.

trimsuffix("hello", "lo")
# Returns: "hel"

upper(string)​

Converts all characters in a string to uppercase, useful for standardizing text format.

upper("hello")
# Returns: "HELLO"

Numeric functions​

abs(number)​

Returns the absolute value of a number, removing the negative sign if present.

abs(-5)
# Returns: 5

ceil(number)​

Rounds a number up to the nearest integer, always rounding towards positive infinity.

ceil(4.2)
# Returns: 5

floor(number)​

Rounds a number down to the nearest integer, always rounding towards negative infinity.

floor(4.8)
# Returns: 4

log(number, base)​

Calculates the logarithm of a number using the specified base, useful for mathematical operations.

log(8, 2)
# Returns: 3

max(number1, number2, ...)​

Returns the largest value from a set of numbers, useful for finding maximum values.

max(1, 5, 3)
# Returns: 5

min(number1, number2, ...)​

Returns the smallest value from a set of numbers, useful for finding minimum values.

min(1, 5, 3)
# Returns: 1

parseint(string, base)​

Converts a string representation of a number to an integer using the specified base (2-36).

parseint("15", 10)
# Returns: 15

pow(number, power)​

Raises a number to a specified power, performing exponentiation operations.

pow(2, 3)
# Returns: 8

signum(number)​

Returns the sign of a number: -1 for negative, 0 for zero, and 1 for positive values.

signum(-5)
# Returns: -1

Boolean functions​

and(bool1, bool2, ...)​

Performs logical AND operation, returning true only if all provided arguments are true.

and(true, false)
# Returns: false

not(bool)​

Performs logical NOT operation, inverting the boolean value of the argument.

not(true)
# Returns: false

or(bool1, bool2, ...)​

Performs logical OR operation, returning true if at least one argument is true.

or(true, false)
# Returns: true

Comparison functions​

coalesce(value1, value2, ...)​

Returns the first non-null and non-empty value from the provided arguments, useful for default values.

coalesce("", null, "hello")
# Returns: "hello"

equal(value1, value2)​

Compares two values for equality, returning true if they are identical in value and type.

equal("a", "a")
# Returns: true

notequal(value1, value2)​

Compares two values for inequality, returning true if they differ in value or type.

notequal("a", "b")
# Returns: true

Date and time functions​

formatdate(spec, timestamp)​

Formats a timestamp string according to a specified format pattern, enabling custom date representations.

formatdate("YYYY-MM-DD", "2023-01-15T10:00:00Z")
# Returns: "2023-01-15"

timeadd(timestamp, duration)​

Adds a specified duration to a timestamp, useful for calculating future or past times.

timeadd("2023-01-15T10:00:00Z", "1h")
# Returns: "2023-01-15T11:00:00Z"

timestamp()​

Returns the current UTC timestamp in ISO 8601 format, useful for recording execution times.

timestamp()
# Returns: "2023-01-15T10:00:00Z"

Encoding functions​

csvdecode(string)​

Parses a CSV-formatted string into a list of objects, with the first row defining column names.

csvdecode("a,b\n1,2")
# Returns: [{a = "1", b = "2"}]

jsondecode(string)​

Parses a JSON-formatted string into HCL data structures (maps, lists, strings, numbers, booleans).

jsondecode('{"a": 1}')
# Returns: {a = 1}

jsonencode(value)​

Converts HCL data structures into a JSON-formatted string representation.

jsonencode({a = 1})
# Returns: '{"a":1}'

yamldecode(string)​

Parses a YAML-formatted string into HCL data structures, supporting YAML's rich syntax.

yamldecode("a: 1")
# Returns: {a = 1}

yamlencode(value)​

Converts HCL data structures into a YAML-formatted string representation.

yamlencode({a = 1})
# Returns: "a: 1\n"

Type and conversion functions​

convert(value, type)​

Attempts to convert a value to a specified type, with error handling for invalid conversions.

convert("123", number)
# Returns: 123

Control flow functions​

can(expression)​

Tests whether an expression can be evaluated without errors, returning true for valid expressions.

can(tonumber("123"))
# Returns: true

try(expression, fallback)​

Attempts to evaluate an expression, returning a fallback value if the expression fails or errors.

try(tonumber("abc"), 0)
# Returns: 0