Tinderbox v10 Icon

Square Brackets in code operator explanations

In the names and text of notes describing action code and export operators, square brackets may be seen. For instance: linkTo(scope[, linkTypeStr]). Generally, these apply to (some) of an operator's arguments.

This notion follows general conventions for documentation of computer code, so should already be familiar to those with some exposure to code documentation.

Optional Use

What the [ ] imply is that the enclosed item(s) are used optionally. Thus in the above example the linkTypeStr does not have to be supplied for the code to work.

The syntax can be though of as a composite of two forms:

linkTo(scope)

linkTo(scope, linkTypeStr)

Lest it seem odd not just to write out both forms, some operators have multiple optional operators so writing out all possible forms would lead to long lists and make articles less easy to read.

Literal [ ] in code

There are some operators where square brackets are intentional and necessary, e.g. attribute(attributeNameStr)[keyStr] where the [ ] enclose and indicate the name of the dictionary key keyStr being referenced.

A further and very recent use is for nested lists.

Which is which usage: optional or literal?

The key is to read the article if unsure; with experience it will be easier to judge by context. For new users, read the whole article and not just browse the title. Optional content/usage is always described as such.