API de Funciones y Expresiones

Testform incorpora un motor nativo de análisis sintáctico (AST) que permite evaluar expresiones computadas y reglas de validación sin dependencias externas inseguras ni uso de eval(). La sintaxis y la biblioteca de funciones siguen el estándar de Terraform HCL, ofreciendo familiaridad y determinismo.

¿Dónde se utilizan las funciones?

Las funciones de Testform se evalúan en dos áreas fundamentales de tu configuración:

1. Variables Locales (`locals.yml`)

Permiten transformar datos, componer URLs dinámicas y normalizar cadenas sin duplicar valores:

locals:
  raw_env: "${lower(var.environment)}"
  api_prefix: "${format('https://api.%s.empresa.com/v1', local.raw_env)}"
  admin_tags: "${split(',', var.tag_list)}"
  session_id: "${uuid()}"

2. Reglas de Validación (`variables.yml`)

Permiten asegurar que los valores proporcionados en testform.tfvars.yml o vía --var cumplan con las restricciones del proyecto antes de ejecutar cualquier plan:

variable:
  environment:
    type: string
    default: "dev"
    validation:
      condition: "${contains(['dev', 'staging', 'production'], var.environment)}"
      error_message: "El entorno debe ser 'dev', 'staging' o 'production'."

  project_code:
    type: string
    validation:
      condition: "${startswith(var.project_code, 'TF-') && length(var.project_code) >= 6}"
      error_message: "El código de proyecto debe iniciar con 'TF-' y tener al menos 6 caracteres."

Características del Motor de Expresiones

Propiedad	Descripción
Sandboxed AST	Cada expresión es tokenizada y analizada en un árbol de sintaxis abstracta; no se utiliza `eval()` de JavaScript ni ejecución arbitraria de código.
Tipado Seguro	Coerción predecible entre tipos primitivos (`string`, `number`, `boolean`, `list`, `map`).
Interpolación Limpia	Cadenas que contienen `${...}` resuelven la expresión interna; si la cadena es únicamente `${...}`, preserva el tipo nativo resultante (ej. listas u objetos).
Manejo de Errores Descriptivo	Si una función recibe argumentos incompatibles o una variable no existe, el motor reporta la línea y el motivo exacto.

Asistente CLI Integrado

Para explorar la documentación o probar expresiones de forma interactiva sin modificar archivos, puedes usar el comando testform functions:

# Ver el catálogo completo
testform functions

# Consultar ayuda detallada de una función
testform functions format

# Evaluar una expresión en vivo
testform functions --eval "format('%s/%s', 'https://api.test.com', lower('V1'))"

Categorías de Funciones

CLI Helper (testform functions): Guía de ayuda interactiva y pruebas en terminal.
Funciones de Texto (String): lower, upper, trim, format, replace, split, join, substr, etc.
Colecciones y Lógica: contains, coalesce, lookup, length, element, slice, merge.
Sistema y Codificación: env, uuid, timestamp, jsonencode, jsondecode, file.