What is the difference in meaning between a function's 'argument', 'parameter' or 'input'?
In this context 'parameter' and 'input' are just alternative terms for 'argument'. The latter is the terminology upon which aTbRef is now standardising in order to try and make the documentation as a whole more consistent. An argument will always have a value, e.g. '12' or "Green eggs and ham", and it is the value supplied by the argument upon which
What is an 'argument'?
It can be said that an operator 'takes' one or more 'arguments '(inputs), does something (i.e. 'operates') with the value of the arguments, and 'returns' a result. In most cases, operators have at least once argument but a small number of Function-type operators might confuse they may have no arguments or all their arguments are optional (their being optional will be covered further below).
So then, what is an 'argument'? When an action code operator such as a function-type operator needs information to work correctly, that information is passed to the function in an 'argument'. For example, the operator abs() is described as abs(number), indicating the abs() operator takes a single argument that is a number. Other operators can take multiple arguments. For instance, any(scope,testValue) takes two arguments: a scoped argument for the group of notes the function examines, and the type of test the operator should perform.
Generally, if any of the specified arguments are not supplied, the operator will either fail to give an outcome; or if arguments are supplied but in an incorrect form, the operator will either fail or give an unexpected wrong outcome. The documentation of the operator will explain the arguments.
What do arguments do?
Above, the description has centred on how arguments are written, literally, in action code. However, is it possible to ask important questions about an argument, especially when encountering a new operator for the first time or one whose purpose is not self-evident from its name. These aspects are:
- What is the scope of the argument—e.g. is a single note affected or are multiple notes affected?
- What data type does Tinderbox expect—i.e. what information must Tinderbox receive to operate the function?
- What is the purpose of the argument—i.e. what does the operator do with the information in the argument?
- Is the argument evaluated—i.e. how does Tinderbox interpret the information in the argument?
Argument order
In action code arguments must always be supplied in the order they are documented. This also applies to arguments for user-defined functions. If an (optional) argument is omitted, and other arguments follow it, a comma+space placeholder should be inserted for example, in pseudocode:
someOperator(arg1, optArg2, optArg3)
someOperator(arg1, , optArg3)
Argument delimiters and whitespace
A comma must be placed between each argument in function operator. Without the commas, Tinderbox is unable to correctly process the instructions. It is acceptable to type a comma followed by a space, for readability purposes, but that space is not required by Tinderbox and is ignored by the parser. Thus Tinderbox parses both the following examples to the same outcome:
any(children,$Checked)
any(children, $Checked)
Quoting argument content
The literal string parts of expressions are quoted as in normal action code, in straight quotes, e.g. "Name of some note". Single or double quotes may be used as long as correctly paired. If the literal value of a complete path (i.e. starting with a '/') is used in code the quotes may be omitted. If in doubt, use quotes!
By contrast, attribute references, e.g. $MyString or action code variables, e.g. vSomeVar, are not quoted.
Further Aspects of Argument Use
Programming and action coding can at times follow 'rules' that are not obvious in 'the real world'. This can be daunting at first, but careful reading of the documentation and personal experimentation with Tinderbox may quickly lead to mastery of the 'rules'. Meanwhile, those with prior coding/programming expertise will see where these 'rules' can be altered or ignored.
In the notes below, additional aspects of argument use are described: