Agents
| Tinderbox User's Manual : Agents |
Agents |
|
Agents are persistent searches.
Agents constantly scour your Tinderbox document, looking for notes of interest — that is, for notes that match their criteria. As you add notes to the document, or change existing notes, your agents automatically update themselves. Agents are active assistants, helping to keep your work organized and to draw your attention to issues you might perhaps overlook.
Agents never move or delete your notes. Instead, agents contain aliases of notes that match their criteria. You can open, inspect, and edit these aliases.
Your agents can also sort their results, and can perform actions on the notes they find.
Actions are discussed in their own chapter.
In any view window,
OR
OR
To finish creating the agent,
The agent’s search criteria or query describes which notes the agent is searching for.
The simplest and most common agents search for notes in which attributes taken on specific values
$Status="important"
or
$DueDate<"tomorrow"
Other agents search for combinations of criteria, or for complex patterns of text.
Tinderbox makes it easy to add new agents when you need them, and to improve agents gradually as your needs change.
Use the expression menus for simple queries
Tinderbox provides two ways for building agent queries. You can build simple agents by using the pulldown expression menus in the middle of the agent dialog; these will help you get started. Alternatively, you can simply type more advanced queries into the agent dialog.
The pulldown menus in the middle of the agent dialog allow you to create a search expression.
Choose an attribute—such as 'text", or a user-defined attribute.
Choose a comparison—such as =, or Contains, or linked from
Enter a value:
Write the search yourself
The text field at the middle of the agent dialog shows the search expression you have built using the expression menus in the dialog. Modify this by typing in the text field, or create a search entirely from scratch by typing in the text field.
Agents regard two dates as being equal if they share the same year, month, and day -- regardless of the time of day.
The comparison operators >, >=, < and <= compare both date and time, so the same note could be found by two agents: one that locates theDate < today and another that searches for theDate = today.
The most common queries examine each note’s attributes and look for particularly interesting notes. For example, we might want to locate notes we made today:
$Created>"yesterday"
or we might seek notes that are colored red:
$Color="red"
The left-hand side of the comparison is always the name of an attribute. The available comparison operators include
= > >= < ≠ !=
The right-hand side of the comparison may be a constant value, as in the examples above, or it may be a reference to another attribute. For example,
$Color=$BorderColor
will find notes where the border color matches the color, and
$Height=$Width
will find square notes. The ‘$’ sign tells Tinderbox, “this is the name of an attribute”; since the left-hand side of the comparison is always an attribute, the $ is optional on the left.
$Name="TrueName" notes named "TrueName"
$Name=$TrueName notes whose name matches the value of the attribute TrueName
More complex queries may be constructed using logical operators & (and), | (or), and ! (not). Parentheses may be used to group expressions:
$DueDate<tomorrow & ($Topic="Iraq" | $Status = "Urgent")
Agents can also search for words, phrases, or even complex patterns that appear in your notes. For example
Text(Abyssinia)
locates notes which mention “Abyssinia” in the text, while
Name(Taipei)
locates notes in which “Taipei” appears anywhere in the note title.
The pattern may be a regular expression with wildcards and subexpressions:
Text(Email: \w+@.+$)
will look for notes that contain lines like the following:
Email: info@eastgate.com
That is, the agent looks for the letters “Email: “, followed by one or more letters (\w+), followed by an ‘@’, followed by one or more characters leading up to the end of a line ($).
Appendix 2 discusses regular expressions in more detail. Some
common and useful special characters include:
. matches any character
* matches zero or more occurrences of the previous character.
+ matches one or more occurrences of the previous character.
\s matches any white space character
\S matches anything EXCEPT a white space character
\w matches a word character, such as a letter
\W matches any non-word character, such as punctuation
Searching for text patterns is powerful and flexible, and Tinderbox works hard to ensure that searching is blindingly fast.
Nonetheless, searching very large documents for complex patterns will eventually become slow.
word ( a word ) — matches all notes that contain the given word in the title, text, or any string attribute. Stricter than regular expression search because it looks only for entire words. word() is true if the word occurs in either name or text.
contains( name of note ) — finds all containers (and agents) that list the note named in the parentheses, such as the note's parents and any agents that list the note.
descendedFrom( name of note ) — finds notes that are descended from the note named in the parentheses. A note’s descendants are its children, its children’s children and so on.
inside( name of note ) — finds notes that are the children of the note named in the parentheses
first( name of note[,count] ) — finds the first count children of the note named in the parentheses. If count is not specified, finds the first child.
last( name of note[,count] ) —finds the first count children of the note named in the parentheses. If count is not specified, finds the first child.
between( attribName,minimum,maximum ) — true if the the value of attribName lies between the minimum and maximum values.
linkedFrom( name of note ) — finds notes that have links coming to them from the note named in the parentheses
linkedTo( name of note ) — finds notes that have links leading to the note named in the parentheses
indented( count ) — finds notes that have exactly count ancestors
similarTo( name of note ) — finds notes whose text is most similar to the text of the named notes. Similarity is based on the number of words that appear in both texts, weighted to give more weight to words that are less common in the rest of the document.
attributeName — An attribute name may stand alone in a query. If the attribute is Boolean, the query is true if the value is true. If the attribute is a string, the query is true if the string is not empty and not the string "false". If the attribute is a number, the query is true if the value is not zero. If the attribute is a date, the query is true if the value is not "never".
Queries may also be export codes. For example, the query ^any(child,Urgent)gathers all notes which have at least one Urgent child. Export templates are discussed in their own chapter. The use of export templates in queries is seldom if ever necessary, and is now deprecated.
An agent may perform an action (or actions) on the notes it finds. For instance, an agent could find all the notes that contain the text Connie and turn them blue.
For information on using agent actions, see the chapter on Actions.
Tinderbox agents search your document for all the notes that match your queries. If your document is large and your queries complicated, your agents need to do a great deal of computational work.
Tinderbox agents do their work every few seconds, and typically are nearly invisible to you. But if your agents require so much time that you find it interrupts your work, you can choose to update agents only on request.
To update agents manually:
To update agents all the time:
To turn this off, select Update Agents Automatically so that the check mark disappears.
A popup menu in the Agent properties dialog lets you change the agent priority from Normal to Highest, Lower, Lowest, or Off.
An agent that has been turned off is sometimes called a frozen agent. It retains whatever aliases it had created when you turned it off, and will behave as a normal container until you turn the agent on once more.
The default value of AgentPriority is 1, which will cause the agent to be checked at roughly ten second intervals. Higher values of AgentPriority cause the agent to be checked less frequently and setting it to 0 asks Tinderbox to check the agent as frequently as possible.
To change the AgentPriority
A popup menu in the Agent properties dialog allows you to sort the contents of agents (and containers). For example, an agent might gather all notes that are red, and sort them alphabetically by title. You may sort by any attribute.
A second popup menu lets you choose to sort capital and lower-case characters separately (case-sensitive), to ignore differences of capitalization when sorting (case-insensitive), or to sort by the last word (as when sorting a list of names).
The popup menus next to "Sort by" are the agent’s primary sort order; the menus next to "and by" are an optional secondary sort order.
| Up: Tinderbox User's Manual | |
| Previous: Aliases | Next: Actions |
