How many discrete code syntaxes does Tinderbox use? Two: action and export. The former is used internally and is Tinderbox's scripting 'language'. Export code is used only for 'HTML' export purposes, enabling the insertion of mark-up and links int the exported text. In both types of code arguments are supplied as a comma-delimited list within parentheses (i.e. normal brackets), being comma-delimited if there is more than one.
Whitespace in codes. For codes using parentheses to hold inputs, there must be no whitespace between the last character of the code and the opening parenthesis. Within the parentheses, additional whitespace—e.g. between inputs or in expressions—is ignored.
Action code syntax. Used within Tinderbox documents for use with rules, agents, $OnAdd and the like. Action code operators are case sensitive. More on Action code syntax.
Export code syntax. The original Tinderbox automation syntax was 'export code', used for exporting code to web(log) pages; such code is always started and ended with a caret symbol (^, typed via shift+6). Expert users may optionally omit the closing carets though this leaves Tinderbox to infer where a code ends. Originally, Export code could also be used internally in actions and queries but this is now deprecated. As most export task-specific codes can be replicated using an action code enclosed in the ^value()^ export tag and so many of the export codes are now deprecated in current use.
Query codes. All now deprecated as there are direct action code replacements. You might still see query codes in agent queries in old files. Such codes start with a hash (#) and all have direct action code replacements.
Case-sensitivity
Attributes and action codes are always case-sensitive, both for system and user attributes. The convention is to use 'CamelCase', i.e. initial capital and capitals for concatenated words; thus the convention would suggest MyString as a user attribute name but alternates such as mystring, Mystring would also work but—importantly—as different attributes from MyString.
Unlike attribute names, export codes are case insensitive but convention when using them is to capitalise internal word joins but not the initial letter; thus 'correct' usage takes forms like ^endIf^, urlEncode but you will find URLEncode, UrlEncode, UrLeNcOdE, etc., will all work just as well.
Documentation will tend to follow the conventions, but feel free to use different casing if it works for you. More on case sensitivity.
Attribute name limitations
This is discussed under Attribute Naming.
Use of parentheses in export code
In export code where no arguments are required, parentheses can usually safely be omitted. With codes whose only argument is 'item', the parentheses can usually be omitted is the desired scope is 'this'. Thus ^title^ is equivalent to ^title(this)^.
Delimiting arguments
A comma is used as the delimiter between arguments. Some arguments may be optional. Any syntax examples in the manual or Release Notes where argument(s) are listed in square brackets (e.g. [data]) are optional.
A notable exception to the comma as a delimiter is the links() operator where a dot (period character) notation is used.
Where arguments allow non-quoted text strings, if the string includes a comma the whole string should be quoted.
Legacy constraints:
- General code conventions from v5.0.0:
- all action references to attributes, both left and right side of operations now take a '$' prefix. A significant exception is that the AttributeName(regex) operator does not take a $ prefix.
- all action code literal strings are now double-quote enclosed.
- export codes use a mix of quoted/non-quoted on a code-by-code basis (i.e.see notes on the individual codes).
- where possible export code is now deprecated in favour of action code, i.e. everywhere except in an export context. Support for internal use of export code is likely to be dropped in the future so existing code should be updated to reflect this.
- Changes as from v5.7.0
A new subs-set of dot-operators were introduced, in the form (data-typed-object or literal value).operator, e.g. $MyString.contains("ant"), "Advice for Defendants".contains("ant"). In this type of operator, the first part is a code expression, an attribute reference or a literal (number, quoted string, etc.). After the dot, the operator name follows post v4.6 conventions; some operators require no inputs and trailing empty parentheses are not required. More advanced users can thus chain operators as long as they know the data type of the object to which they are dot-attaching additional operators.
More on coding conventions:
- Case-sensitivity
- Lexical vs. numerical sorting
- Quoting and escaping strings in Tinderbox coding
- Code: Straight vs. Typographic 'curly' quote characters
- Attribute references: quoting of literal strings vs. paths
- Quoting Regular Expressions
- Using $ and quotes in Export code
- Single and double quotes
- aTbRef's naming conventions
- Code examples using attributes with a 'My' prefix
- Square Brackets in code operator explanations