Parentheses: arguments for action code operators and user functions

Although historically user functions came the Tinderbox much later than action code operators, both use the same syntax:

• Operator or function name. Names are case-sensitive.
  • User function names are set by the user by defining the function.
• The trailing parentheses must follow immediately after the operator name , i.e. without any white space between the name and the opeing parenthesis. Otherwise the operator will not be evaluated correctly
• Trailing parentheses containing argument(s)
  • arguments are always comma-delimited. Whitespace before after the commas is ignored by the code parser.
  • where there are no arguments or all arguments are optional and not being used, the parentheses may be omitted, e.g. .sort() vs. .sort. If in doubt, e.g if new to action code, use the empty parentheses. If unsure if parts of the syntax may safely be omitted, do not guess—use the full syntax.
  • operators may have optional arguments. Optional arguments are indicated in the main operator listing.
  • non-optional arguments must have a value, even if only an empty/default value, e.g. "".
    • all user function arguments are always mandatory.
• some operators, and user functions also use a curly-bracket enclosed code block.

Examples

A simple query term:

inside("Projects") 

or basic operator use:

$MyNumber = sin(45) 

Parentheses may be omitted is no arguments, so either:

$MyString = "uncle".capitalize(); 

or

$MyString = "uncle".capitalize; 

But some operators , e.g. return, never allow trailing parentheses (per-operator documentation explains this). So if $SomeNumber is '4', then in a function:

return (2*$SomeNumber); 

returns '8', but

return 2*$SomeNumber); 

returns nothing. In the latter case, the action code parser assumes the execution order parentheses are arguments—invalid for return—and no value is returned.

The syntax for a conditional operation with branching outcomes (depending whether the condition evaluates true or (else) false:

if(condition){actions}[else{actions}] 

In aTbRef documentation presence of '[ ]' indicate that one or more of the of the arguments is optional:

stamp([scope, ]stampName) 

thus implying both these usages are valid:

stamp("Do Stuff");  

stamp("SomeNote","Do Stuff");  

In most cases, optional arguments come at the end of the argument list. In a few case both argument and parentheses may be optional if there are no arguments and all arguments are optional. Thus:

$MyNewList = $MyList.sort;  

$MyNewList = $MyList.sort();  

$MyNewList = $MyList.sort($SomeString);  

A user function (following aTbRef general naming conventions):

myFunction(iArg1,iArg2){ } 

In the last example, as a user-defined panel, all arguments must be populated even if only with an empty value, thus:

$SomeResult = myFunction("hello",24){ } Correct

$SomeResult = myFunction("",24){ } Correct

$SomeResult = myFunction(,24){ } WRONG