Tinderbox users can create action code, export code, user-defined attributes, rules, edicts, stamps, functions, prototypes, templates, etc. This is a bit like programming, and for good documentation and readability, a common technique is to use "standard" conventions. The following discussion suggests some conventions that are most commonly used by Tinderbox users which will be found in aTbRef.
Thus the document will appear to assert as rules, constraints which are not actually so. Expert users can apply their own, less consistent naming and it is assumed they are expert enough to know where it is safe to do so. Otherwise, qualifying all the above 'rules' will be undervalued. However, it is understood expert users may (within Tinderbox's actual limits) with to use naming styles with which they are more familiar in other areas of their works (other apps, coding languages, etc.).
A few terms are used in the discussion:
- 'CamelCase'. A typographical convention in which an either an initial capital, or an initial lower case letter, is used for the first letter of a word forming the elements of a closed compound, e.g. PayPal, iPhone, MasterCard. Camel case is seen in two forms in Tinderbox: with capital initial letter, e.g. AgentQuery, and with lower-case initial, e.g. wordsRelatedTo().
What things in code can the user name? Individual items lists are discussed in more detail further detail below:
- User Attributes
- Stamp names
- Action code functions
- Action code variables
In addition, some things like the action and export code operators have strict formatting so must be typed correctly. In the case of action code, some code input location support auto-completion, so helping with typing operator names correctly.
Attributes
Attribute names. User attributes (only) can be named by the user and should follow the CamelCase convention seen with system attributes. Attributes are always a single word (no spaces). At simplest: start with a capital, Roman letter (i.e. A–Z), accents and non-Roman scripts are allowed (from v9.1.0), then capitalise each compounded word, i.e. 'Price' or 'LastName'. Acronym styling is a choice for the user: 'SourceURL' or 'SourceUrl' are both valid attribute names. However, note that Tinderbox will consider 'SourceURL' and 'SourceUrl' as two different user attributes.
Although there is some support for other scripts, beginners are advised to use unaccented Roman characters whilst getting to know how Tinderbox works.
Abiding by these guideline will avoid surprises. More nuanced aspects are discussed under Attribute Naming below.
System attributes always use the CamelCase beginning with an initial and cannot be renamed by the user.
Reference to attribute values. In action code (see below), referring to the value of an attribute to get or set its value is done using a '$' prefix. Thus, $ChildCount refers to the value of the attribute named 'ChildCount'. However, within aTbRef and much general Tinderbox documentation, inline references in general text which refer to Tinderbox attributes names generally use a $-prefix as a marker that it is an attribute name being cited. The latter is a slight variance with in-app usage but does aid clarity in the articles. In actual action code, the $-prefix always indicates a reference to a value.
For example, consider a user creating an attribute named BookCategory, and assigns it a value "Non-Fiction". Then, then the action code in a stamp that accesses BookCategory's value in the selected note would refer to it via the code $BookCategory.
Code example attribute naming. A convention, adopted before the Sandbox group of system attributes for testing were added, is to use a left-side attribute name that indicates the type of data to be expected from the right side. This 'MyString' indicates receipt of String (textual) data, 'MyList' a list of values, 'MyDate' a date-object, etc. The reader is not required to use the exact left-side attribute stated but rather to understand the data type they should use for their own attributes
Export codes
Tinderbox export codes are case-sensitive and use the CamelCase convention with a lowercase initial letter. Export codes cannot be renamed. They must be indicated with a caret '^' before and (optionally) after the code, i.e. ^children("t_item")^. If the optional closing caret is omitted, Tinderbox guesses where the code ends. For this reason, and to help signal intent, aTbRef always uses a closing caret and suggests the same a standard best practice.
Action code operator codes
Action codes are case-sensitive and use use the CamelCase convention with a lowercase initial letter. Action codes cannot be renamed. Queries, either for agents or for query-based operators use action code, albeit with special query operators. Basic actions take a syntax of 'left-side is set to the value of right-side where either may be as simple as an attribute value or a complex expression resulting in such a value. At simplest, an example is: $MyColor = "red";. A left-side Color-type attribute is being set to a literal string value of 'red'. Note that in this context the attribute name in the action code is prefaced with "$" as it is setting a value for the attribute..
Export and Action code inputs
In code examples in Tinderbox Help and in aTbRef, or in descriptions, there is a convention where inputs (or arguments, or parameters) are named to show data type (string vs. number) or purpose to indicate that input is used. Optional inputs are enclosed with square brackets (i.e. […]) and may be omitted when using that operator. If no inputs are used and there is no clear statement stating trailing empty parentheses may be omitted, include them, i.e. 'code()' not 'c ode()'. This way, the intent of the code is clear. In Tinderbox documentation, inputs use the CamelCase convention with a lower-case initial letter, as with the codes themselves.
Designators
Designators are case-sensitive and follow the Camelcase convention using a lowercase initial letter. Designators cannot be renamed. Care should be taken not to use input values that are the same are designator names. As a result, the convention is that designators used as input are not quote-enclosed even though they are strings. By comparison, a string value that is the same as a designator must be quote-enclosed to make clear to Tinderbox that it is not a designator.
For example, grandparent is a note designator. The code
$MyString = grandparent;
has a completely different meaning to Tinderbox than
$MyString = "grandparent";
Action code Functions & Variables
Functions and Variables have no stipulated limits on naming but should not use a name already used by any Tinderbox system attributes, export, action code, or designator. A function name is always followed by opening and closing parentheses after the name, even if the function has no arguments defined.
aTbRef naming prefixes
Again, for consistency and to aid learning, aTbRef is (moving to) a system of using prefix letters to refer to other objects in action and export code. These are for guidance: users are not required to use these conventions in their own work. If nothing else prefixes both indicate intent and avoid naming-collisions with other codes or note names. If writing code to share with other users (who may have less expertise also consider adopting all or part of these suggestions.
These prefixes are suggested to make reading one's code easier and for distinguishing among different elements of a document. It is suggested that single, initial lower-case prefixes can help indicate what kind of element is being defined. The recommended prefixes are all single-letter and lower case (assuming use in a case-sensitive context):
- 'p' for prototype names. Examples: pCharacter, pStudent.
- 't' for export template names. Examples: tMain_Report, tSummary.
- 'f' for function names. Example: fSetColorRed().
- 'i' for function arguments (i.e. inputs). Note, these effectively define a variable of that name within the scope of the function. Example: fSetColorRed(iNoteList), fProcessFeatures(iProductName).
- v for variable names. Examples: vDessert, vLinkList.
- 'a' (or 'an' for readability) for loop variables, such as with .each(). Examples: aProduct, anItem.
For the last three (all types of variable) it can—depending on complexity/context—be useful for the name to indicate the purpose and/or data type of the variable. Examples: 'iProductName', 'vLinkList', 'aProduct'.