Defining an 'item' object—a single item

The term 'item' is not a Tinderbox definition but is useful in the context of discussing action code and documenting action code usage.

Where an argument is defined as item scope this means it returns one and only one object (as compared to a group scope). If more than one item is returned where only one is desired, e.g. from a find() query) Tinderbox will use only the first item of the list, by ascending $OutlineOrder, as the specified item; the same holds for an expression that evaluates with an ambiguous result. It thus makes sense to avoid such ambiguity and ensure the query is sufficiently scoped to return only one match. The overall point is that whether using a string literal value (i.e. just stating a name) or using a code expression, the outcome must evaluate to provide Tinderbox with a reference to a single note.

A single note 'item' can be referenced as:

A note's title (its value for $Name).
A notes's path (its value for $Path). This is useful if the note's name is not unique.
(less commonly) A note's ID ($ID). This is less usual but can be useful if there are problematic characters in the title or path, especially if using (un)linking actions.
An item-scope note designator, e.g. 'parent' or 'firstSibling'. Designators return, $Path data for the matching object.
A query function, e.g. find(), c ollect(), collect_if(), links(). The query must resolve to a single note item. Query functions return $Path data for the matching object.
An expression, i.e. action code that evaluates as any of the above. Complex expressions may require use of parentheses and/or use of eval() to help Tinderbox understand the order of evaluation and to deal with encapsulated evaluations.
A string attribute value that is an expression or a literal title/path.
A discrete value in a list attribute that is an expression or a literal title/path.
A literal string, e.g. "This note".

See also—notes linking to here: