Paths

This is Tinderbox Cookbook version 2.0.0, created in conjunction with Tinderbox 5.11.2.

The locale settings used to export this document: en-GB. Most date tests were written/tested on a UK day/month order system and thus tests may fail if exported using different locale settings.

This page explores Tinderbox’s path references — ways Tinderbox actions, rules, and export templates refer to specific Tinderbox notes.

Many examples on this page use the following data:

Deprecation. Some codes are now marked 'deprecated'. This means that while they may still work, such syntax should be avoided. New documents should not use such syntax and existing documents in regular use should be have their code reviewed to avoid retaining deprecated usage.

this

Designates the immediate context. For an Agent, this is the note under examination. For a Rule, this is the note to which the rule applies. For a container or adornment’s OnAdd action, this is the note being added.

description try expect result ok
eval(/data/todo/Groceries,$Name(this)) Groceries Groceries not yet

If no note is specified, this is assumed.

eval(/data/todo/Groceries,$Name) Groceries Groceries not yet

Path designators may not be expressions

eval(/data/todo/Groceries,$Name("th"+"is")) Groceries not yet

$UserString is "this"

eval(/data/todo/Groceries,$Name($UserString)) Groceries not yet

(unique name)

An expression may refer to a note by its unique name.

description try expect result ok
$Name(Groceries) Groceries Groceries not yet

References to non-existent notes return the empty string

$Name(mythical) not yet

path expression

An expression may refer to a note by a path of names, separated by forward slashes '/'.

description try expect result ok
$Name(/data/todo/Groceries) Groceries Groceries not yet
$Width(/data/todo/Groceries) 3 3 not yet

References to notes that do not exist return an empty string

$Name(/data/todo/Groceries/mythical) not yet

References to notes that do not exist return an empty string

$Width(/data/todo/Groceries/mythical) not yet

parent

Refers to the container or agent that holds the note

description try expect result ok
eval(/data/todo/Groceries/apple,$Name(parent)) Groceries Groceries not yet

References to notes that do not exist return the empty string, even if the note referred to does exist)

eval(/data/todo/Groceries/mythical,$Name(parent)) not yet

Path expressions normally refer to this, but may take an argument that describes another note. Here, we retrieve the parent of the parent.

eval(/data/todo/Groceries/apple,$Name(parent(parent))) todo todo not yet

Path expressions normally refer to this, but may take an argument that describes another note. Here, we retrieve the next sibling of our parent.

eval(/data/todo/Groceries/apple,$Name(nextSibling(parent))) Calls Calls not yet

Here, we retrieve our first cousin; the child of the next sibling of our parent.

eval(/data/todo/Groceries/apple,$Name(child(nextSibling(parent)))) Jackson Jackson not yet

..

In a path expression, .. refers to the parent container.

description try expect result ok
eval(/data/todo/Groceries/apple,$Name(..)) Groceries Groceries not yet
eval(/data/todo/Groceries/apple,$Name(../..)) todo todo not yet

grandparent

description try expect result ok
eval(/data/todo/Groceries/apple,$Name(grandparent)) todo todo not yet

next

Refers to the next note, in outline order.

description try expect result ok

For a note that is not a container, next is the younger sibling (if the note has a younger sibling)

eval(/data/todo/Groceries/garlic,$Name(next)) lemons lemons not yet

If a note has no children and no younger sibling, next is the parent's younger sibling (if it exists). If the parent has no younger sibling, next is the grandparent's younger sibling, etc.

eval(/data/todo/Groceries/lemons,$Name(next)) Calls Calls not yet

For a container, next is the first child

eval(/data/todo/Calls,$Name(next)) Jackson Jackson not yet

previous

Refers to the previous note in outline order

description try expect result ok
eval(/data/todo/Groceries/garlic,$Name(previous)) apple apple not yet

If we have no elder sibling, previous refers to our parent

eval(/data/todo/Groceries/apple,$Name(previous)) Groceries Groceries not yet

If our previous sibling is a container, previous refers to the youngest descendant of that container

eval(/data/todo/Calls,$Name(previous)) lemons lemons not yet

prevSibling

Refers to the previous or elder sibling of the note.

description try expect result ok
eval(/data/todo/Groceries/garlic,$Name(prevSibling)) apple apple not yet

prevSibling and previousSibling are both acceptable, but the latter is deprecated

eval(/data/todo/Groceries/garlic,$Name(prevSibling)) apple apple not yet

If no previous sibling exists, the attribute reference returns an empty string

eval(/data/todo/Groceries/apple,$Name(prevSibling)) not yet

nextSibling

Refers to the next or younger sibling of the note

description try expect result ok
eval(/data/todo/Groceries/apple,$Name(nextSibling)) garlic garlic not yet
eval(/data/todo/Groceries/garlic,$Name(nextSibling)) lemons lemons not yet

If there is no sibling, the attribute reference returns the empty string. Contrast next.

eval(/data/todo/Groceries/lemons,$Name(nextSibling)) not yet

Refers to the first or eldest sibling of the note

description try expect result ok
eval(/data/todo/Groceries/garlic,$Name(firstSibling)) apple apple not yet

A note might be its own firstSibling

eval(/data/todo/Groceries/apple,$Name(firstSibling)) apple apple not yet

lastSibling

Refers to the last or youngest sibling of the note.

description try expect result ok
eval(/data/todo/Groceries/garlic,$Name(lastSibling)) lemons lemons not yet

A note might be its own last sibling

eval(/data/todo/Groceries/lemons,$Name(lastSibling)) lemons lemons not yet

child

The first child of a container

description try expect result ok
eval(/data/todo/Groceries,$Name(child)) apple apple not yet
eval(/data/todo/Calls,$Name(child)) Jackson Jackson not yet

If a note is not a container, the attribute reference returns the empty string

eval(/data/todo/Groceries/garlic,$Name(child)) not yet

lastChild

Refers to the last or youngest immediate child of a container

description try expect result ok
eval(/data/todo/Groceries,$Name(lastChild)) lemons lemons not yet

firstChild and lastChild may refer to the same note if a container has exactly one child

eval(/data/todo/Calls,$Name(lastChild)) Jackson Jackson not yet

original

If a note is an alias, original refers to the original note. If a note is not an alias, original is equivalent to this.

randomChild

Refers to a randomly-selected child of the container

description try expect result ok

If the container has exactly one child, randomChild is equivalent to child.

eval(/data/todo/Calls,$Name(randomChild)) Jackson Jackson not yet
eval(/data/todo/Groceries,$Name(randomChild)) apple|garlic|lemons apple not yet
eval(/data/todo/Groceries,$Name(randomChild)) apple|garlic|lemons garlic not yet
eval(/data/todo/Groceries,$Name(randomChild)) apple|garlic|lemons apple not yet

cover

Refers to the first note in outline order in the entire document.

current

When exporting, notes may be included in other notes via ^include, ^children, and ^descendants. If a note is being exported, this refers to the immediate note and current refers to the note being exported. For example, if Page includes Sidebar, then when the sidebar is exported this refers to Sidebar and current refers to Page.

Otherwise, current is undefined

description try expect result ok

Since the context of eval is not part of exporting a page, current is not defined

eval(/data/todo/Groceries,$Name(current)) Paths Paths not yet

Since this test is part of the page named Paths, ^title(current) is: Paths

not yet

agent

In an agent's query or action, this refers to the note that the agent is examining, and agent refers to the agent.

In other contexts, agent is undefined

description try expect result ok

agent is undefined except in an agent query or action

eval(/data/todo/Groceries,$Name(agent)) agent not yet