Tinderbox v9 Icon


Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Operator First Added: 

Operator Last Altered: 

 Statement  [other Statement type actions]

 Item  [operators of similar scope]

 Data manipulation  [other Data manipulation operators]


 As at baseline



The var statement declares the local variable. No trailing parentheses are used. Occasionally, an action may find it convenient to declare a local variable in which to save intermediate results. In the past, the only choice was to use a user attribute as a temporary store, with the attendant issues of deciding if it is necessary to reset the attribute at the end of the expression.

Depending on how the operator is being used it may be used without parentheses.

Try to use variable names that will not be mistaken for something else. Avoid using a 'var' prefix for variable names, such as 'varX', as this will confuse Tinderbox's parser. In such a case 'vX' might be a better choice and a 'v' prefix is the convention adopted in aTbRef (though there is no requirement to use such naming as it is used for explanatory reasons only).

A local variable acts in most ways like a user attribute. Local variables exist for the duration of the action or, when they are declared inside curly brackets { … }, e.g. an an .each() loop, their scope is the rest of the clause, i.e. the remaining individual statements within the {}.

Declaring a variable

So, the var statement declares the local variable:

var x; declares a variable 'x', but with no value

More sensible is to use a name indicating purpose:

var vNum; declares a variable 'vNum' with no value.

var vNum(5); declares a variable 'vNum' and gives it an initial value of 5.

var vText("this is note "+$Name); declares a variable 'vText' and gives it a calculated string value.

A variable can also be declared and assigned a value is a single expression:

var vCost = 5; 

… defines a temporary variable 'vCost' and then assigns it the value '5'. It is equivalent to the following original syntax, note the explicit use of operator argument parentheses in this case:

var vCost(5); 

In effect, the first form collapses the older two-step method of declaring an empty var before then giving it a value:

var vCost; 


Local variables must be declared before first use. If not explicitly initialised, their initial value is the empty string "". Within scope, a variable maybe reset in the same manner as an attribute. Thus, YY=; resets variable 'YY' to no value.

Setting a variable's data type

From v9.1.0, vars can optionally be given a data type on creation, by colon-appending the data-type to the var operator. Thus:

var:number vCost(5); 

This generates a variable 'vCost' of (expected) data type Number and sets an initial value of '5'.

Available data types include

Note that data type labels are all-lowercase. Other existing attribute data types that are not listed here will be provisioned as a string, as they are strings with a special, contextually different, form of use. Important: defining a date type without an initial value does not set that types value:

var:number vNum; → values is undefined (i.e. "")

var:number vNum = 0; → values is zero (0)

Providing an explicit type helps Tinderbox to understand the user's intent, especially if a default value is applied (though for string-based attributes it is moot). For example, the same numerical value number might react to subsequent operations in various ways:

var:number vCost(5); vCost = vCost + 5; $MyString= vCost; gives '10'

var:list vCost((5); vCost =vCost + 5; $MyString = vCost; gives a 2-member list, '5;5'

var:string x(5); vCost =vCost + 5; $MyString = vCost; gives '55'

Further usage Examples

$MyNumber = 0; var vNum = 2; $MyNumber = vNum; 

$MyNumber = 0; var vNum; vNum = 2; $MyNumber = vNum; 

$MyNumber = 0; var vNum(2); $MyNumber = vNum; 

In all cases $MyNumber is set to 2. In the second example the variable is defined and given a value using a single code expression. Here is a scoped example within a single action the { and } marking the scope:

	$MyNumber = 0;
		var vNum = 2;
		$MyNumber = vNum;
		vNum = 6;
	$MyNumber = vNum;

$MyNumber is set to 0 (nothing) as 'vNum' has no meaning outside the code inside the braces {}. By analogy a variable created inside a loop or function, (i.e. within { } sections of code) cannot be read outside that scope, but variables created outside such scope can be read/set within a loop or function.

Using variable values declared outside loops or functions

A variable declared using var may be altered from within the scope of a List/Set.each() loop or a function. This includes nested loops or functions. The reverse does not hold. In-loop a new value would be to be stored in an attribute or variable declared outside the loop. In a function, this value could be (part of) the return data.

Passing variables into export code

^value()^ can be used, within the context a single template, to insert a var() variable declared within an ^action()^ code. Note that the variable must be declared before use, i.e. before as in reading template code top to bottom. Beware name collisions Assume for a moment you have an actual attribute $vNum, then:
	$MyNumber = 0;
		var vNum(2);
		$MyNumber = vNum;
		vNum = 6;
	vNum = 4;
	$MyNumber = vNum;
$MyNumber is 4, rather than 0, because the vNum = 4 is interpreted as the deprecated legacy syntax of $vNum = 4. So, be careful that a local variable's name does not match existing attributes, note names or string literals that you use in your project. Remember the local variable does not take a $ prefix. It is a value reference but not to an attribute.