[Edit: I’ve updated the page on back-references. I need to better cross refer things, but the update is a first stab at a better aTbRef articlee, for now]
Agree, and I just spotted a typo as well (‘were’ => ‘where’). Grr. In the interim, for a query:
`$Text.contains.("email: (\w+)<(.+)>")`
Back-reference $0 is the contents of ("email: (\w+)<(.+)>")
, i.e. the whole of the matched (sub-)string of the source string—in this case, $Text. The other back-references , $1, $2 etc., are always a part of what is matched by $0.
So $1 returns the contents of the first pair of matched parentheses within the overall query expression, reading left to right.
Thus $1is a string that is the contents of (\w+)
, without the parentheses!
$2 is a string that is the contents of (.+)
.
$3 returns nothing as there is no third set of back-reference generating references. However, Tinderbox does allow up to 9 ($1 - $9) back-references within a query string.
I need to check, but while back-references can be nested I’m not sure if they can overlap (i.e. one reference opens before another closes).
If in doubt about mapping $-numbers to the correct part of the query match, the answer—as with most action code conundrums— is to make a small test file so you can concentrate just on the problem at hand without confounding effects from the rest of your actual work file.
Back references can be used with agent queries, find() queries, .replace(findStr, replaceStr)
where the back-refs are set in findStr
and used in replaceStr
. Back-reference can also be using in macros, both action code do()
and export code ^do()^.
[Edit: I need to check on the find() context]
Hopefully that fills in a few blanks!