Variables and Substitution
The name of a variable is a placeholder for its value — the data it holds. Referencing that value is called variable substitution. Variables referenced inside an expression are expanded to their respective values. For this purpose, variables are represented by a dollar sign ($) followed by the name of the variable.
Variable substitution is the mechanism that makes iXML dynamic. Without substitution, every <output> statement would produce static text. With substitution, you can embed computed values, database results, API responses, and user input directly into your output, your conditionals, and your data structures.
Basic substitution
The simplest form of variable substitution uses the dollar sign followed by a variable name. The variable name must consist of alphanumeric characters and underscores only, and it is case-sensitive:
<set var="name">iXML</set>
<output>My name is $name!</output>
<!-- My name is iXML! -->
When the runtime encounters $name in the output string, it looks up the variable name in the current scope, finds the value "iXML", and replaces $name with that value. The exclamation mark after $name is not part of the variable name because it is a punctuation character — the runtime treats any punctuation character as the end of a variable name.
Substitution rules
- Variable names are case-sensitive and consist of alphanumeric characters and underscores only. The variable
$Nameand the variable$nameare two distinct variables. - The next punctuation character implicitly ends the variable name, though it may explicitly be concluded by a trailing dollar sign (
$). For example, in the string$name!, the!terminates the variable name. If you need to concatenate a variable with alphanumeric text, use the trailing dollar sign:$name$suffixreads two variables, but$name$$suffixreads$name, outputs a literal$, then readssuffix. - A dollar sign (
$) is passed unchanged if not followed by an alphanumeric character or underscore. For example,$!outputs a literal$!because!is not a valid variable name character. - Two adjacent dollar signs (
$$) are substituted with one single dollar sign ($) as an escape syntax. This is the only way to produce a literal dollar sign in output.
Dollar sign escaping
When you need to output a literal dollar sign — for example, in currency formatting — use the double-dollar escape:
<output>Price: $$100</output>
<!-- Price: $100 -->
Invalid variable declaration
The $ symbol is for substitution only — it is not part of variable names. Including a dollar sign in the var attribute of any command is a parser error:
<set var="$a">hello</set>
<!-- Parser error: Invalid variable name for attribute "VAR" -->
The correct form is <set var="a">hello</set>. When you later reference this variable, you write $a — the dollar sign belongs to the substitution expression, not to the variable name.
Array key access and key chains
iXML provides a shortcut syntax for referencing array items directly by specifying the corresponding key. This syntax supports two notations — array notation (square brackets) and object notation (dot syntax) — which can be mixed freely and nested to arbitrary depth.
Array notation (square brackets)
Within square brackets, a key is not interpreted as a literal but as an expression, resulting in further variable substitution. This means you can use variables as dynamic keys, enabling patterns like lookup tables and computed array access.
Empty brackets [] have context-dependent behavior:
- In substitution (
$arr[]) or getting/unsetting: interpreted as an empty key literal - In setting (
<set var="arr[]">value</set>): implicitly generates the next consecutive numeric key, similar to pushing onto an array
<set var="names[bg]">Bill Gates</set>
<set var="names[sj]">Steve Jobs</set>
<output>$names[bg] and $names[sj] are competitors!</output>
<!-- Bill Gates and Steve Jobs are competitors! -->
Dynamic key lookup with nested substitution — the keys themselves are resolved from variables:
<set var="names[bg]">Bill Gates</set>
<set var="names[sj]">Steve Jobs</set>
<set var="key1">bg</set>
<set var="key2">sj</set>
<output>$names[$key1] and $names[$key2] are competitors!</output>
<!-- Bill Gates and Steve Jobs are competitors! -->
Object notation (dot syntax)
A key appended with a dot is always interpreted as a literal. No variable substitution occurs within dot-notation keys. This makes dot notation ideal for accessing known, fixed keys — it is more readable and slightly faster than bracket notation for this purpose.
The restriction is that dot-notation keys may consist of alphanumeric characters and underscores only. If you need to access a key containing special characters (spaces, hyphens, dots), you must use bracket notation.
<set var="names.bg">Bill Gates</set>
<set var="names.sj">Steve Jobs</set>
<output>$names.bg and $names.sj are competitors!</output>
<!-- Bill Gates and Steve Jobs are competitors! -->
Key chains
Several keys may be strung together to form a key chain of arbitrary length, which allows multidimensional arrays to be accessed directly. Array notation and dot notation may be mixed freely within a single key chain:
<set var="names.microsoft[bg]">Bill Gates</set>
<set var="names[apple].sj">Steve Jobs</set>
<output>$names[microsoft].bg and $names.apple[sj] are competitors!</output>
<!-- Bill Gates and Steve Jobs are competitors! -->
Deeply nested references
References of array items may be deeply nested within the array notation. This enables indirection patterns where one array acts as a lookup table for keys into another array:
<set var="names.bg">Bill Gates</set>
<set var="names[sj]">Steve Jobs</set>
<set var="keys[bill_gates]">bg</set>
<set var="keys.steve_jobs">sj</set>
<output>$names[$keys.bill_gates] and $names[$keys[steve_jobs]] are competitors!</output>
<!-- Bill Gates and Steve Jobs are competitors! -->
Nested references can be stacked to any depth, but deeply nested expressions become difficult to read and debug — consider using intermediate variables for clarity in production code.
Inline expression forms
iXML provides two special substitution syntaxes for embedding computed values directly into strings: arithmetic inline substitution for mathematical expressions, and inline function substitution for calling functions with a single argument.
Arithmetic inline substitution
Arithmetic expressions embedded inside another expression are replaced by their result. They are represented by a leading dollar sign ($) followed by parentheses (()):
<set var="birthyear">1950</set>
<output>This person is $(2012 - $birthyear) years old!</output>
<!-- This person is 62 years old! -->
The $() syntax works anywhere that normal substitution works — in <output> content, in <set> content, in attribute values of type string, and even inside other substitution expressions.
Computed array indices:
<array var="names">
<item>Bill Gates</item>
<item>Steve Jobs</item>
</array>
<output>$names[0] and $names[$(0 + 1)] are competitors!</output>
<!-- Bill Gates and Steve Jobs are competitors! -->
Inline function substitution
A leading variable reference followed by a single argument in parentheses calls the function and substitutes its return value:
<function var="lcase">
<tolower var="return">$return</tolower>
</function>
<set var="name">iXML</set>
<output>My name is $lcase($name)!</output>
<!-- My name is ixml! -->
The runtime calls the function with $name as the value of the special return variable, executes the function body, and inserts the return value into the output string.
The inline function syntax $func($arg) passes the argument as the return variable. This is a shorthand — for multiple arguments, use the call command with <param> children instead.