# Text Patterns

The operator `.contains()` tests whether a text pattern or regular expression appears in a note’s attribute. For example,

> `$Text.contains("frog")`

is true if the text of the note contains the string "frog". The .contains() operator is case-sensitive, but

> `$Text.icontains("frog")`

will match both "frog" and "Frog".

In older documents, you may encounter the obsolete syntax Text(pattern). This is equivalent to $Text.contains(pattern) — note that the '$' is omitted in the older syntax. This deprecated syntax continues to function but is harder to read than the modern .contains().

### Regular Expressions

A number of special characters represent “wild cards” and other classes of text patterns. Complete information on Tinderbox’s regular expression engine may be found at:

> http://www.boost.org/libs/regex/doc/

#### Wildcard Characters

The period character, “.”, matches any single character.

The plus sign, “+”, matches one or more occurrences of the expression that precedes it. The pattern

> `!+`

will match one or more exclamation points, and the pattern

> `....+`

will match any string with at least four characters.

An asterisk matches zero or more occurrences of whatever precedes it;

> `10*`

matches 1, 10, or 1000.

The question mark “?” matches zero or one occurrence of whatever precedes it.

You can also specify the minimum and maximum number of repetitions:

> `Xa{2,4}Y`

will match XaaY, XaaaY, or XaaaaY, but won’t match XaaaaaaY.

#### Character Ranges

A set of characters to be matched may be enclosed in square brackets. For example,

> `[0123456789]`

will match any digit. Ranges of consecutive characters can be written more concisely:

> `[0-9]`

will match any digit, and

> `[A-Z][a-z]*`

will match any capitalized word. Beginning a set with the character “^” matches everything except the set;

> `[A-Z][^0-9]`

will match any capital letter provided it’s not followed by a digit.

Several special sequences represent common sets of characters:

> \w - any word character (including underscore)

> \W - any non-word character

> \< - the start of a word

> \> - the end of a word

> \s - any white space character

> \d - any digit

> \l - any lowercase letter

> \u - any uppercase letter

#### Anchors

The special character "^" matches the beginning of the text or attribute being searched. When searching the text of a note, ^ matches the beginning of any paragraph in the note.

The special character “$” matches the end of the text or attribute being searched. When searching the text of a note, $ matches the end of the paragraph in the note.

#### The \ [backslash] Character

The backslash character "\" removes the special meaning from the character that follows it. Use "\\" to search for the backslash character itself.

### Parentheses

Grouping expressions in parenthesis determines the scope of wildcards. For example,

> `Name=(\u\l+)+`

Would match “Rochester” and “SmallTalk”.

In addition, when Tinderbox sees a parenthetical expression, it remembers the substring(s) that matched it and can use those substrings in actions. For example, the agent

> Query: `Text(^ color: (\w+)\b$)`

> Action: `$Color=$1`

scans the document for any notes that contain paragraphs like this:

> `Color: red`

If it finds any matching notes, the agent extracts the word that follows the string “Color: ” and changes the note’s color to match. Here, $1 stands for “whatever matched the first set of parenthesis”, $2 for the second set, and so forth. $0 stands for the entire matched string.

#### Back References

When agents search for regular expressions, the agent saves substrings that match parenthesized sub-expressions. These substrings or back references can be used in actions, and are especially useful for automatically extracting information from notes.

For example, an agent might search for notes that contain fields like this:

> From: Henry Higgins

by searching for the pattern

> From: (.+)$

An action can then refer to the name extracted following "From: " as $1

> `$Author=$1;`

The author will now be set to Henry Higgins. Subsequent subexpressions may be referred to as $2, $3, and so on.