CLI Helper

The Testform CLI includes a dedicated command to explore and test expression functions directly from your terminal. This allows you to verify the exact output of an expression before incorporating it into your locals.yml or variables.yml files.

---

1. Listing the Complete Catalog

Running testform functions prints an index of all available built-in functions with their signatures and summaries:

testform functions

Output:

Testform Expression Engine — Built-in Functions Catalog

• String & Text:
  lower(string)                          → Converts all letters in a string to lowercase.
  upper(string)                          → Converts all letters in a string to uppercase.
  trim(string, [cutset])                 → Removes leading and trailing whitespace or specified characters.
  trimprefix(string, prefix)             → Removes the specified prefix from the beginning of a string.
  trimsuffix(string, suffix)             → Removes the specified suffix from the end of a string.
  startswith(string, prefix)             → Returns true if the string begins with the specified prefix.
  endswith(string, suffix)               → Returns true if the string ends with the specified suffix.
  replace(string, search, replacement)   → Replaces all occurrences of a search string.
  split(separator, string)               → Divides a string into a list of substrings.
  join(separator, list)                  → Concatenates elements of a list into a single string.
  format(format, ...args)                → Formats a string using verbs (%s, %d, %j, %%).
  substr(string, offset, length)         → Extracts a substring from offset up to length characters.

• Collections & Logic:
  coalesce(...args)                      → Returns the first argument that is not null or empty.
  lookup(map, key, [default])            → Retrieves the value of a key from a map.
  contains(list_or_string, value)        → Checks whether a list or string contains a value.
  length(value)                          → Returns the number of elements, keys, or characters.
  element(list, index)                   → Retrieves an element at the specified index.
  slice(list, start, [end])              → Returns a sublist of elements.
  merge(...maps)                         → Merges multiple maps into a single map.

• System & Encoding:
  env(name)                              → Reads an environment variable from the host process.
  uuid()                                 → Generates a random RFC 4122 version 4 UUID.
  timestamp()                            → Returns current UTC date and time formatted in ISO 8601.
  jsonencode(value)                      → Serializes a value into a standard JSON string.
  jsondecode(string)                     → Parses a JSON string into its native data structure.
  file(path)                             → Reads the contents of a local file as UTF-8 text.

---

2. Inspecting a Specific Function

Specify any function name to inspect its expected arguments, return types, and concrete examples:

testform functions format

Output:

Testform Expression Function: format
  Category:    String & Text
  Signature:   format(format, ...args) -> string
  Description: Formats a string using verbs (%s for string, %d for integer, %j for JSON, %% for literal %).

Arguments:
  - format [string]: Format string containing placeholders.
  - args [any...]: Values to interpolate.

Examples:
  $ format("%s/%s", var.base_url, "api/v1")
    => "https://example.com/api/v1"
  $ format("run-%03d", 5)
    => "run-5"

Another example for collections:

testform functions coalesce

---

3. Live Evaluation (--eval)

The --eval flag processes any valid expression through Testform’s lexer, parser, and AST evaluator, outputting the formatted result and its inferred data type:

String Formatting

testform functions --eval "format('https://%s.example.com/api/%s', lower('STAGING'), 'v2')"

Output:

Expression Evaluation:
  Input:  format('https://%s.example.com/api/%s', lower('STAGING'), 'v2')
  Type:   string
  Result: "https://staging.example.com/api/v2"

List Membership Testing

testform functions --eval "contains(['dev', 'staging', 'prod'], 'dev')"

Output:

Expression Evaluation:
  Input:  contains(['dev', 'staging', 'prod'], 'dev')
  Type:   boolean
  Result: true

Ternary Logical Operations

testform functions --eval "length('test') > 2 ? 'long' : 'short'"

Output:

Expression Evaluation:
  Input:  length('test') > 2 ? 'long' : 'short'
  Type:   string
  Result: "long"

JSON Object Parsing

testform functions --eval "jsondecode('{\"enabled\": true, \"retries\": 3}')"

Output:

Expression Evaluation:
  Input:  jsondecode('{"enabled": true, "retries": 3}')
  Type:   object
  Result: {
  "enabled": true,
  "retries": 3
}