Agent Queries

A significant change from v4.6 onwards is that queries move from being a syntax variant of their own to being action code expressions. This makes it easier to write queries, reduces ambiguity and means there is less overall syntax to learn.

Also, from v4.6 the old special query codes are replaced by action operators of the same name, without the # prefix. This reflects the fact that queries are now action code expressions, albeit requiring to be in a conditional form resolving to true/false.

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

• Attribute value pattern matching
• String Attributes - comparison operators
• $Attribute = $1 (in queries only)
• Controlling Agent Update Cycle Time
• Self-referring agents
• Legacy query code

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. Also all references to attribute names should be prefixed with a $ character. Consider this very simplistic example of a query (legacy code version first):

DateAttribute = date 

$DateAttribute == "date" 

In the first, Tinderbox must decide if the user is attempting to call (incorrectly) the new v4+ date() function or simply wishes to match the string 'date'. The double [sic] quotes in the latter example tell Tinderbox this is a string literal. For long term users, changing to always quoting strings like this as a matter of course should pre-empt hard to spot errors in more complex queries.

Although queries used to allow inclusion of export codes this is now deprecated in favour of action code where possible. Examples of legacy versions:

$MyString(^title^) 

$MyString==^title^ 

..both the above will resolve the export code (as a regular expression match or an exact match respectively) before processing the query. Now these would be coded as:

$MyString($Name) 

$MyString==$Name 

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 recognises

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.

Agent special query names, those beginning with a #, are case insensitive. Thus #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 normal usage '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'.

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