Tinderbox allows user-defined operators, also called 'functions'. Such operators are typically defined in notes inside the Library container in the document's built-in Hints container (if not present this should be added to the document) though they may be defined in other contexts too.
Notes in that container which have names enclosed in parentheses, such as /Hints/Library/(What’s This) are treated as documentation; all other notes are executed at document startup and after they are edited.
Why use functions?
Functions provide a 'define once / use multiple times' feature in documents, and allow:
- storing a process so that it can be used repeatedly throughout the document;
- defining that process once and using it from many different locations, i.e. not needing a copy of the same code in each, rule/agent/etc.;
- storing a long complex action that can be hard to read in the Inspector but more easily read as the $Text of a note (see storing function code)
- allowing a process that takes inputs, which is a limitation of stamps;
- allowing a process that can return results, another limitation of stamps;
- transportable function or libraries of functions that can be copied to and re-used in other document and by other users.
- Note: any (user) attributes called in a function need to pre-exist before use—Tinderbox will not auto-create them, e.g. when copying a function from one document to another.
What sort of things can functions do?
Functions comprise a set of action code instructions that perform a specific set of operations to achieve a specific outcome. In most cases, this will include acting upon optional input arguments provided to the function at the point where it is called (a.k.a., invoked) and optionally return results to the code that called (called) the function. A simple case is as shown in the example below (explained in more detail here):
function fAddTax(iPrice){return(1.18*iPrice);};
It is still possible to define a useful function that takes no input and returns no value but acts on the document based on the functions code, e.g. setting a selection of attribute values. In this mode the function is akin to calling a stamp, though calling a function may seem a more intuitive usage.
Functions fall into broad categories of use:
- Mathematical/logical. Probably the simplest use. A function can easily implement mathematical and statistical calculation tasks. Generally a number in, a number out.
- String manipulation. Slightly more complex due to the ad hoc nature of the inputs. Whilst new stream parsing methods improve basic action code capability a function allows for larger processes.
- Encapsulate complex processes. In more complex documents, workflow may involve a complex series of transformations to support ingests of data or for formatted export using structure beyond normal export code offerings.
More about functions
The following sections should be read through completely on first encounter but are structured as small articles to assist cross-referencing and later reference for refreshing understanding or syntax.
Important note: all examples follow aTbRef naming conventions. These may seem verbose or over-descriptive to experienced programmers but are provided to help the learner, not the expert.
Aspects of using functions: