Tinderbox v9 Icon

Function arguments

Important note: all examples follow aTbRef naming conventions.


Function arguments

A function's arguments are the terms—zero or more) that are defined within the parentheses following a function's name. Thus function fSomeTask(iNumber, iString){... defines two discrete arguments: 'iNumber' and 'iString'. A function with no arguments function fReset(){... is perfectly allowable, noting that parentheses must be included even if empty. This latter form, though valid, is less commonly used because in general the aim of the function's code is to manipulate one or more values passed to that function.

A function may, or may not, have one or more arguments. Multiple arguments are entered separated by commas (with optional whitespace after).

A value must be passed for every argument defined in the function, i.e. the action code calling the function must be written so as to supply a value for each argument defined by the function.

Naming arguments

Each input argument must have a discrete name. The argument's name must not be an attribute reference, e.g. "$MyString", or an attribute's literal name, e.g. "MyString". Within this restriction, the exact naming of the argument is the user's choice.

The argument name is essentially declaring/naming an internal variable for use (only) within the function, as explained further below: see 'Argument names as internal variables'.

In aTbRef documentation any function arguments in the parentheses use the same CamelCase convention as for attribute names but with an 'i' prefix. For example, this function definition code:

function fMakeTable(iSomeList){ ... code ...}

'iSomeList' will be a variable available within the scope of the function, i.e. in the function but not outside it. Calling the above function like so:

fMakeTable($CategoryList);

will result in iSomeList within the function holding a list containing the value of the calling note's CategoryList attribute.

An argument's name vs. the value name used in action code calling a function

It is important to understand that a function argument's defined name and the string defining the input for that argument as used in the code calling the function code are usually different. Thus, in the above example, the function is called supplying an argument value that is a reference to $CategoryList. But, inside the function for this execution of the function, the value of the first argument iSomeList will be the value read from $CategoryList in the calling note.

But, elsewhere other action code might call the same function but using code fMakeTable($MyList);. For that execution, iSomeList within the function will hold the value of $MyList in the calling note. Or the calling code might pass a literal list, e.g. fMakeTable("ant;bee;cow");, with iSomeList now being the list passed into the function, i.e. "ant;bee;cow".

Despite describing calling the function 'fMakeTable' with three differenly described input, in every case, the supplied argument value is used internally via the argument's name, i.e. here 'iSomeList'.

So:

Argument names as internal variables

When writing a function's code and including argument(s), an argument's name is implicitly defined as an internal variable. Using the example above, if a function's argument were defined as 'iSortList' then that exact name (i.e. the argument's user-defined name) can be used anywhere in the function's code as a variable that with have that value passed to the function via that argument input.

If the argument were instead named 'x' or 'abracadabra', the same applies, the argument name as defined in the function code is the name of the internal variable for that argument's input.

Therefore, the argument/variable name is set by the user by the action of writing the function code.

Note, that when copying another user's function code, as personal styles differ, a user may decide to use attribute names more to their own style. If doing so it is important to change not only the argument name in the function's argument list but any occurrences of the argument name in the whole code of the function. In this simplistic example, function 'fGetListItem' takes a list as an argument and returns the value of the third item in that list (not second, as .at[] is zero-based):

	function fGetListItem(iSomeList){
		return iSomeList.at[2];
	}

If having copied this code it was preferred to have an attribute 'L', then two substitutions are needed, one in the argument declaration and the second where it is used within the function:

	function fGetListItem(L){
		return L.at[2];
	}

Externally, the call is still the same, e.g.:

$MyString = fGetListItem($SomeThings); 

as it is only the internal name of the argument that has changed (from 'iSomeList' to 'L').

Using argument input values within the function

Arguments are a received as a String data type (regardless of the source data in the calling code). Note that may change in future version, to allow enforced date-typing of arguments. But, at present assume type coercion occurs. That means most inputs will be assumed to be a String, List or Dictionary.

In the example above, calling the argument 'iSomeList' may indicate the term is a function argument and is intended to be List-type data, but it doesn't affect Tinderbox normal type coercion. A string with no semi-colons in it will be assumed to be a string. If semi-colons are found a list (essentially a List type) will be assumed.

To avoid incorrect parsing of inputs, it may be necessary to pass the input to a data-typed variable. Re-using the above example:

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

Variable use is discussed further here.

It is equally possible to pass the argument to an attribute of the desired data type in order to assert data type for further use within the function.

Evaluation of input arguments

An argument my be an expression as well as an attribute value, variable or literal string/number. For instance:

$Result=fLastThreeWordsOf(fBestParagraphOf($Text)); 

Here, the actual value passed to function fLastThreeWordsOf() is the evaluated result of fBestParagraphOf($Text), with $Text being the text of the calling note.

Simulating optional arguments

As stated above, every argument defined in the function's code, must receive an import or the function will not run correctly. Despite this it is possible to simulate an optional argument by defining a value for that

To simulate an optional argument, pass a placeholder string ("none") and test that input within the function's code before using the argument, i.e. if "none" do nothing or else carry out some action using the argument's value. Here "none" is not a defined term. The value used in this context is up to the user. The point is that if using 'no value' value, the the input value must match whatever 'no value' string the user has defined in their function.


Next: Returning function values