Coding conventions

How many discrete code syntaxes does Tinderbox use?

This has varied. Going back in time, but there used to be three different syntaxes. Tinderbox 4.6 merged Actions and Queries, so modern Tinderbox uses only action and export syntax. You might still see query syntax in old files.

Export. The original Tinderbox automation syntax was 'export code', used for exporting code to web(log) pages; such code is always started with a caret symbol (^) and optionally closed with the same. Export code could also be used internally in actions and queries but this is now deprecated.

Query. A slightly different set of syntax was used for queries, found primarily in agents, Find dialog and in the 'condition' part of ^if conditional statements. The only codes exclusive to queries are those beginning with a hash (#) sign.

Action. As export code started to be used internally for 'actions', such as carried out by agents, export codes were extended by 'action code' which did not use the caret mark-up and could only be used within Tinderbox and not, for instance, within export templates. Since v4 action code has been massively expanded and now duplicates almost every (as relevant to actions) export code. At the same time, internal use of export codes is deprecated.

In all three types of code parameters are supplied as a list within parentheses (i.e. normal brackets), being comma-delimited if there is more than one.

Changes as from v4.6

As from v4.6 query syntax there are some further changes:

• query code is deprecated (but available for legacy files' code) as all hash-codes now have equivalent actions.
• all action references to attributes, both left and right side of operations now take a '$' prefix. conversely, a $ prefix is not used with the AttributeName(pattern) operator.
• all action code literal strings are now double-quote enclosed. Export codes are 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 action code - i.e. everywhere except in an export context. Internal use of export code is likely to be dropped in the future so existing code should be updated to reflect this.

Case-sensitivity

Attributes 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 , #descendedFrom, urlEncode but you'll 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.

Use of parentheses in export code

In export code where no parameters are required, parentheses can usually safely be omitted. With codes whose only parameter is 'item', the parentheses can usually be omitted is the desired scope is 'this'. Thus Coding conventions is equivalent to Coding conventions.

Delimiting parameters

A comma is used as the delimiter between arguments. Some parameters may be optional. Any syntax examples in the manual or Release Notes where parameter(s) are listed in square brackets (e.g. [data]) are optional.

Where parameters allow non-quoted text strings, if the string includes a comma the whole string should be quoted.

More on coding conventions:

• Case-sensitivity
• Strings in Tinderbox coding - quoting and escaping
• Single and double quotes

Licensed under Creative Commons Attribution-Noncommercial-Share Alike 3.0 License
[See aTbRef CC licence Attribution/Waiver info info]