You can combine a pattern 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 whole target $Text were:
Source email: John<john@example.com>, on 24/03/2010
…then the above query gives these back-references:
$0: email: John<john@example.com>
$1: John
$2: johndoe@example.com
$0 is always the whole matched (sub-)string for the target attribute value but if the regex pattern creates additional back-references then $1 through $9 may be used to access those additional match string. Back-references are returned in the order created; to understand that process better, read up on regular expression back-references. 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")
This syntax for using back-references can only be used in the context of a query, such as:
- agents
- if() operators in actions/rules.
If the regular expression pattern used with the contains() family of dot-operators (e.g. String.contains()) is found the function now 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.
Since v6.5.0, use of back-reference sources has been extended to if() statement; the conditional statement is already written in query language.