CLI Helper:

El CLI de Testform cuenta con un comando dedicado para explorar y poner a prueba las funciones de expresiones directamente en la consola. Esto te permite verificar la salida exacta de una expresión antes de incorporarla en tus archivos locals.yml o variables.yml.

---

1. Listar el Catálogo Completo

Ejecutar testform functions imprime el índice de todas las funciones disponibles con su firma y resumen:

testform functions

Salida:

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. Obtener Ayuda de una Función Específica

Indica el nombre de cualquier función para inspeccionar sus argumentos esperados y ejemplos de uso:

testform functions format

Salida:

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"

Otro ejemplo para colecciones:

testform functions coalesce

---

3. Evaluar Expresiones en Vivo (--eval)

La opción --eval procesa cualquier expresión válida a través del lexer, parser y evaluador AST de Testform, mostrando el resultado formateado y su tipo de dato correspondiente:

Formateo de Cadenas Compuestas

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

Salida:

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

Comprobación de Pertenencia en Listas

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

Salida:

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

Operaciones de Lógica Ternaria

testform functions --eval "length('test') > 2 ? 'largo' : 'corto'"

Salida:

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

Transformación de Objetos JSON

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

Salida:

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