Tinderbox v8 Icon

Query back-references

Using parentheses within a query's pattern it is possible to set up to 9 back-references within the overall pattern. These sub-matches can then be used in the action connected with the query. The most normal means of setting a query pattern with back-references is by using the operators String.contains(pattern) or String.icontains(pattern).

Back-references can be used in actions in several context. Most obvious is an agent's action (referencing the agent query). Within general action code, with the if(query){actions} conditional action, back-references for the conditional query can be used within any action(s) enclosed within the operators' {} brackets—in both the 'if' and 'else' branches.

Although not formal queries, the action String.replace(pattern,replacement) can set back-references in its pattern query argument and then use them in the operator's replacement parameter.

Although Macros use back-reference notation for inserting content, in that case the values are drawn from the macro's input parameters rather than from a query.

The method of referring to a back-reference is via a $-prefixed number, $0 through $9. The back-reference $0 always refers to the the whole matched string (or sub-string) for the stated query pattern. $1 to $9 refer to any defined back-references within the overall pattern. Back-references are returned in the order created. The order is usually left-to right in order the parentheses open (note this allows for nesting) but to understand that process better, read up on regular expression back-references.

In use, a query with an action that will use the value of the found pattern:

query: $Text.contains.("email: (\w+)<(.+)>")

action: $Email=$2

…will set the value of attribute $Email to the third back-reference pattern found in text, in the above case the string enclosed by angle brackets. If the entire whole matched section of $Text was:

Source email: John, on 24/03/2010 

…then the above query gives these back-references:

$0: email: John 

$1: John i.e. the contents of the parentheses-delimited code \w+ 

$2: johndoe@example.com i.e. the contents of the parentheses-delimited code .+ 

$3 through $9: returns nothing, as they have no source match defined 

Thus $0 is always the whole matched (sub-)string for the stated attribute value but if the regex pattern creates additional back-references within the query then $1 through $9 may be used to access those additional match sub-strings.

Back-references may be nested:

Query: $Name.contains("(a(ard))v(ark)")

Action: $MyString =$1; $MyStringA = $2; $MyStringB = $3;

For the matched note the 3 attributes will hold, in order, "aard", "ard" and "ark". This shows back-references are numbered in the order encountered running left to right and not by some other system such as the level of nesting.

Literal parentheses in patterns must be escaped by a backslash. To match "this (that) other", use:

$Text.contains("this \(that\) other") 

To capture "(that)" as back-reference $1:

$Text.contains("this (\(that\)) other") 

If the regular expression pattern used with the contains() family of dot-operators (e.g. String.contains()) is found the function returns the match's offset+1, where offset is the distance from the start of the string to the start of the matched pattern. Formerly, .contains() returned true if the pattern was found. The '+1' modifier ensures that a match at position zero return a number higher than zero which would otherwise coerce to false. Since 1+offset is always true, no changes are required in existing documents but the function also now gives usable offset information.

In the same manner, see String.replace() for use of back-references within an action context. In short, the operator can be thought of as $SourceDataString("query","return string") where the "return string" might be one or more back references and may include string literals. See String.replace() for examples.

Use of back-reference sources includes the if() statement; the conditional statement is already written in query language.

Whilst find() uses queries, the operator uses this to return the paths of matching notes and does not support back-references.

A Tinderbox Reference File : Agent & Queries : Query back-references