This version is out of date, covering development from v9.0.0 to v9.3.0. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v9 Icon

Variable use in functions

Important note: all examples follow aTbRef naming conventions.

Uses of variables in functions

There are three ways that a variable are used in functions:

Defining a variable in a function

A function variable is defined exactly the same way as in other action code:

var vThing; 

As the basic assumed data type, if not set, is a String, it can be more helpful to use explicit typing, whether or not a value is applied straightway. The point is that the variable has a notified data type from the outset, rather than one coerced by Tinderbox based on context of use:

	var:string vThing;
	var:number vCount;
	var:date vNow = date("today");
	var:boolean vBoolean = true;

A variable needs to be defined before first use, as with attributes. It makes good sense to define variables at the start of the function, noting that loop variables are defined in the loop operator. Do consider also adding comments about the variable's purpose, as once written the code may only be re-read occasionally and the code's intent may get forgotten over time.)

Using variables to set data type of inputs

Currently, as at v9.1.0, the function's arguments when accessed from within the function supply String-type data (this is regardless of the data type supplied in the action calling the function). Thus, to avoid unexpected type coercion, e.g. a Date being misread as a String, it can be useful to pass an argument into a typed varaible before using the argument value in the functions action code:

	function fMakeTable(iSomeList){
		var:list vList = iSomeList;
			// ... etc.

Variable duration

Variables created in a function are destroyed when the function execution completes. If a variables value is needed, other than as a return value, the value will need to be passed to an attribute for more persistent storage.

Variables only exist while the function is being executed after having been called. Whilst variables are most often used to temporarily keep intermediate results while the function is executing, if a variable holds some value that is needed elsewhere, it should either be passed back to the calling code via the return operator or an attribute should be assigned to the variable's value. Some examples of assigning attributes to function variables are:

	// ...
	$MyString = vString;
	$SomeNumber ("config-note") = vCount;
	// ...

In the first case, $MyString in the calling note is set. In the latter case, $SomeNumber in note "config-note" is set. The choice of where a stored value is saved is dependent on the wider context of use, i.e. there is no single 'correct' choice.

A variable may be used as an input argument for a call to another function:

	// ...
	var:string vString = "Testing!";
	 // ...

Variable scope

A variable created in a function is only accessible from within that same function. For experienced programmers this may seem unexpected (see more) and may change in the future. At present, a variable should only be used within the function in which it is defined.

Next: Attributes vs. variables in functions