Paths
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.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:
- todo
- Groceries
- apple
- garlic
- lemons
- Calls
- Jackson
- Letters
- Dr. Bryan
- Edmund Morris
- Mike Bonifer
- Work
- back up hard disk
- write chapter 17
- pay bills
- Groceries
(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 |
|---|---|---|---|---|
| $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 | garlic | not yet | |
| eval(/data/todo/Groceries,$Name(randomChild)) | apple|garlic|lemons | lemons | not yet | |
| eval(/data/todo/Groceries,$Name(randomChild)) | apple|garlic|lemons | lemons | 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 |