LUTX Variable Expansion Documentation

This document describes the enhanced variable expansion capabilities introduced in lut_hdfpgl.lua.

Core Features

1. Basic Substitution

Standard syntax ${VAR} replaces the placeholder with the value from the environment.

"${user}" -> "Alice"

2. Recursive Resolution

Variables can resolve to strings that contain other variables. The engine recursively expands them up to a limit (default: 20 iterations).

env = {
  root = "${base}/app",
  base = "/var/www"
}
"${root}" -> "/var/www/app"

3. Nested Variables

You can nest variables to compose keys dynamically. The inner variable is resolved first.

env = {
  lang = "en",
  msg_en = "Hello",
  msg_es = "Hola"
}
"${msg_${lang}}" -> "${msg_en}" -> "Hello"

4. Default Values

Use :- to specify a default value if the variable is nil or undefined.

"${user:-Guest}" -> "Guest" (if user is nil)

Note: This works for simple identifiers. For complex Lua expressions, use Lua's or operator.

5. Escaping

Use a backslash `

 to prevent expansion.

"\${var}" -> "${var}" (literal)


Double backslashes are preserved unless they escape a variable syntax.

"\${var}" -> "\value" (backslash + value)



6. Environment & Lua Expressions
The expression inside

${...}

 is evaluated as Lua code within the template environment.

"${os.getenv('HOME')}" -> "/home/user"
"${x + 1}" -> "2"



Safety

Recursion Limit: A maximum depth (20) prevents infinite loops (e.g., a=${b}, b=${a}).
Sandboxing: Lua evaluation runs in a controlled environment (though currently inherits the template's environment).



Implementation Details

The expansion logic uses an iterative scanner that:

Finds the first ${...} block.
Checks for escapes.
Recursively resolves the variable name/expression (handling ${${ref}}`).
Evaluates the expression (Env lookup -> Lua eval -> Default).
Replaces the block.
Repeats until no more substitutions occur or limit is reached.