Scope and Assignment
Scope and visibility
Variables in iXML exist within a scope — a boundary that determines where the variable can be referenced. Understanding scope is essential for writing correct iXML code, especially when working with functions, includes, and closures.
Variables typically have a single local scope and are therefore only visible within the immediate context, unless they have been specifically declared as global variables, in which case they have global scope and are independent of the context within which they are defined.
Closures may be used to establish a referencing environment for free function variables. Those variables are explicitly bound to corresponding variables from the immediate context within which a function is defined, thereby directly referencing non-local variables from the parent scope outside of the inherent context of that function.
Visibility precedence
When multiple variables with the same name exist at different scope levels, iXML resolves the reference using a strict precedence order from highest to lowest priority:
- Special local variables —
this,return,arguments. These are automatically provided by the runtime inside functions and cannot be overridden by any other mechanism. - Free function variables — declared with
<use>in closures. These are bound references to variables in the function's defining scope. - Regular local variables — parameters passed on context switch (via
<param>in<call>,<include>, or<new>). These are the most common variables in everyday code. - Global variables — declared with
<global>. These have the lowest precedence, meaning any local variable with the same name shadows the global.
By default, variables are local to context boundaries (function calls, includes, REST resources). Use <global var="..." /> when cross-context sharing is intentional, but prefer parameter passing for cleaner, more testable code.
See also
- function — context isolation and closure binding
- global — declaring global variables
- include — context boundaries in code inclusion
Assignment model
The way iXML assigns values to variables depends on the type of value being assigned. This distinction has profound implications for how your code behaves, particularly when passing complex data between functions, modifying arrays during iteration, and building object-oriented structures.
- Primitive non-composite variables (null, bool, int, float, string) are always assigned by value. When you assign a primitive to another variable, the runtime creates an independent copy. Changes to one variable do not affect the other.
- Complex variables (array, function, macro, class) are always assigned by reference. When you assign a complex value to another variable, both variables point to the same underlying data. Changes through one variable are visible through the other.
- Assignment by reference may cause circular references. Avoid creating data structures where array A contains a reference to array B, which in turn contains a reference back to array A — this can cause stack depth exceptions.
- Using a variable before assigning a value to it is possible — it then defaults to the neutral literal of the accordant input type. For example, an uninitialized variable used in an arithmetic context defaults to
0.
The by-reference behavior of arrays is one of the most important concepts to internalize. When you pass an array to a function via <param>, the function receives a reference to the original array — modifications inside the function affect the caller's data. Use <clone> if you need an independent copy.