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.

Best practice is to move to always placing actual text (i.e. string literals) in double quotes - "some text", to indicate they aren't to be parsed for the action operator syntax. 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.

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.

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

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

Unlike early versions of Tinderbox, uses normal regular expression escaping (i.e. no double-escaped backslashes). For example, the original query syntax this\\sthat is currently written:

this\sthat

now recognizes

this&[tab char]&that

as well as

this   that

Agent actions can 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.

If the query string does not parse the agent's query will be disabled. If the query entered into the query box on the Create/Rename agent dialog does not parse, the dialog will not dismiss until the query (or action code) parses.

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