Agent Queries

References in the listings below to "BooleanAttribute", DateAttribute", "NumberAttribute" and "TextAttribute" refer to any attribute, system or user, that is of the data type specified. Thus "BooleanAttribute" implies any attribute of the data type "Boolean".

• Basic Comparison Operators
• Attribute Name
• Template Code Arguments
• Special Query Arguments
• Multiple Query Arguments
• Controlling Agent Update Cycle Time
• Macros in Agents

Agent query names are case insensitive. #descendedFrom(note), #Descendedfrom(note) and #dEsCeDeDfRoM(note) all work — though use of the published case sense is best lest these become case sensitive in later versions. The basic rule seems to be intercapitalised; that is, the first letter is lower case but the first letter of all joined words is upper case, i.e. 'linkedFrom'.

Note that an agent's query only controls which notes are matched and whose aliases are added as children of the agent. Anything done to the (aliases of) matching notes is controlled via the the code stored in the AgentAction attribute. Action code can also be seen via the agent's Create or Rename dialogs.

From v4.0.2, best practice is to move to always placing actual text ('string literals') in double quotes, to indicate they aren't to be parsed for the new v4.0.0+ operators. Consider this very simplistic example of a query:

AnAttribute = date

AnAttribute = "date"

In the first, Tinderbox must decide if the user is attempting to (incorrectly) call the new v4+ date() function or simple wishes to match the string 'date'. The double [sic] quotes indicate this is a string literal. If you move to quoting strings like this as a matter of course it should pre-empt a few hard to spot errors with more complex queries.

From v3.0.0, queries can include export codes. Examples:

Name(^title^)

Name=^title^

..both the above will resolve the export code (as a regular expression match or an exact match respectively) before processing the query.

As from v3.0.0 also note that the caret (^) character has a special meaning for Tinderbox, you need to escape it, but in a different way, use ^^ and not \^.

From v3.0.2, a minor change in agent query syntax will require modification of some existing agents.

Tinderbox regular expressions recognise a number of patterns containing the backslash character. Some common examples are

\s matches any whitespace character

\S matches anything EXCEPT a whitespace character

\w matches a word character, such as a letter

\W matches any non-word character, such as punctuation

In previous versions, the \ character (which Tinderbox uses as an 'escape' character to remove the special meaning of quotation marks, parentheses, etc.) had to be escaped: \\s. This often created confusion.

When parsing a regular expression agent query, Tinderbox no longer requires double-escaped backslashes. For example, the old query syntax this\\sthat is now written:

this\sthat

now recognizes

this&[tab char]&that

as well as

this   that

In v3.0.0/3.0.1 trailing spaces in query expressions such as "(Color=Red )" were parsed as part of the query. In v3.02 onwards this is fixed and trailing white space is now trimmed before the query is parsed.

From v4.0.0, agent actions can now refer to the attributes of the current agent using the new agent object. For example:

Query: status=Important

Action: Color=$Color(agent)

This agent gathers all "Important" notes and sets their color to match the color of the agent. Note that this is different from

Action: Color=$Color(this)

since "this" refers to the note being gathered, and is also different from

Action: Color=$Color(parent)

since "parent" is the parent of the original note, not the parent of the newly-made alias.

Licensed under Creative Commons Attribution-Noncommercial-Share Alike 3.0 License
[See aTbRef CC licence Attribution/Waiver info info]