Coding Conventions

This is Tinderbox Cookbook version 2.0.1, created in conjunction with Tinderbox 7.3.2. The locale settings used to export this document: en-US. Most date tests were written/tested on a UK day/month order system and thus tests may fail if exported using different locale settings.

How many discrete code syntaxes are there?

This has varied, going back in time, but it's effectively 3 though that is in the process if reducing as from v4.6

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 - using a closure is recommended for non-experts.

Query (pre-v4.6 only). A slightly different set of syntax was used for queries, found primarily in agents, Find dialog and in condition part of ^if conditionals 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 3 types of code parameters are supplied as a list, comma delimited if more than one, within parentheses (i.e. normal brackets).

Changes as from v4.6

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

Dot Operators (v5.7.0+)

Dot operators, so called because they start with a dot and are chained to attribute values and string literals, were first added in v5.7.0 in some cases replacing existing operators. Most noticeably $Attribute.contains() replaces the AttributeName() query operator. Dot operators are a mix of functions and properties. The latter are usual read/write or read-only and don't take parameters so don't need trailing parentheses (though will work if such are used).

From v5.8.0, dot operators can be chained to combine several tasks - such as creating a list , sorting it and then reversing the list order. With chaining care should be taken to checking that the commands use all apply to the (implied) data type in scope and the order in which commands are chained.

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, expert/query/action codes as 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^, #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.

Use of parentheses in codes() 

Where no parameters are required (i.e. all paramters are optional) these can usually (always?) safely be omitted. With codes whose only parameter is 'item', the parentheses can usually be omitted is the desired scope is 'this'.

Delimiting parameters

A comma is used as the delimiter between code parameters. Some parameters may be optional, those currently these aren't well documented. 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 to stop it being misinterpreted as a delimiter.

Deprecation

Some codes are now marked 'deprecated'. This means they may still works but this syntax should be avoided. Current/new documents should avoid such syntax and review re-write existing code to avoid deprecations.