Class Regex

$ - anchor to end of line

The match must end at the last character of a line of text in order to be accepted. If Multiline is true, then an embedded newline character qualifies as marking the end of a line, but the end of the string always qualifies.

Example: R$('/end$/') matches 'friend', but not 'friends'.

( ) - group sub-expressions

Parentheses can be used to override the usual operator precedence by grouping operations together. Additionally, parenthesized sub-expressions are counted from left to right (by their open parenthesis) to number them from 1 to the number of sub-expressions encountered, unless the ExplicitCapture option is enabled. The text that matched each sub-expression can be accessed later on within the pattern by using \1 through \9, or from the MatchData object returned from the method match by indexing it. Thus for example,

match = R$('/.*(c)/').match("abcd")
assert(match[1].start == 3)
assert(match[1].length == 1)

Additionally, in the replace method, the replacement string may contain escaped references to these sub-expressions.

If a sub-expression is completed more than once within a match, the last one wins.

(?# ) - comment

If a parenthesized group begins with "?#", then everything up to the next close parenthesis is taken as a comment and ignored. Note that this is the next parenthesis, not the matching one. You cannot include a close parenthesis in this type of comment (but see the x option).

This class of comment, although matching no input, is taken to be an operand. Thus, it cannot separate an operand and its intended operator. For example:

R$('/a(?# a comment)*/').match('aa')

will have a length of 1, because the '*' repeats the comment, not the 'a'. However,

R$('/a(?# a comment)b/').match('ab')

does match, because the comment matches zero-length text.

(?() ) - conditional group

If the condition within the inner parentheses is true, then the expression that follows up until the final parenthesis applies. If that expression contains a union (|), then the left side of the union will be treated as the 'then' section (applied if the condition is true), and the right side will be treated as 'else' (applied if the condition is false). To force a union to remain a union, enclose it within another level of parentheses.

A conditional group does not consume a numbered back-reference.

The condition can have one of three forms:

1. Numbered group reference - if all of the characters in the condition are numeric, then the corresponding captured group will be tested for membership (as in a \1..\9 back-reference). If that group has been captured, the condition is true, otherwise it is false. Note that a zero-length group is counted as captured.
2. If the condition begins with "?", then it must be a look-ahead or look-behind test. If that test passes, then the condition is true, otherwise false.
3. If neither of the above, then the condition is taken as the name of a captured named group. If that group has been captured, the condition is true, otherwise false.

Examples:

R$('/(John )?\bSmith(?(1)son)\b/') - matches 'Smith' alone, but if preceeded by 'John ' then it must be 'Smithson'.

R$('/((?(dot)\.)(?P<dot>\d{1,3})){4}/') - matches an IP address, because the \. is not applied until a numeric group has been captured.

R$('/(?:(x)|y) = (?(1)0|-1)/') - matches "x = 0" or "y = -1", but no other combinations.

R$('/\d+(?(?=.*\boverdrawn\b)\*)/i') - matches a number, which must include a trailing '*' if the word "overdrawn" occurs later on in the string.

R$('/\d(?(?<=[0-5])A|B)/') - matches "0A", "1A", "2A", "3A", "4A", "5A", "6B", "7B", "8B", and "9B"

(?: ) - group sub-expressions without back-reference

If a parenthesized group begins with "?:", then it operates exactly like a normal sub-expression, except that it can't be subsequently referenced by a sub-expression number. That means that the MatchData object returned by match does not include that sub-expression in its indexer, nor can it be referenced later in the pattern via \1..\9, nor accessed within the a2 argument to replace. The sub-expression is not included in the count of sub-expressions, so the next counted sub-expression will have the index following the previous one.

Example:

match = R$('/(?:a|l)*(.*)tor/').match('alligator')
assert(match[1].start == 4)
assert(match[1].length == 3)

To make this behavior the default for unadorned parentheses, see the ExplicitCapture option.

(?<group> ), (?'group' ) - named group sub-expression (.NET syntax)

For compatibility with .NET named group capture, I've included support for the .NET syntax. .NET named groups differ from the Python style named groups not only in syntax, but also in the assignment of numbered back-references. While Python groups are numbered along with unnumbered groups, .NET groups are numbered after all other groups -- unless they duplicate a Python group name, in which case they get the number of the group they duplicate. As implied by that exception, .NET group names share the same namespace as Python named groups. They can be used interchangeably, and you can use either syntax for back-references and text-replacement.

Examples:

(?<= ), (?<! ) - look-behind

If a parenthesized group begins with "?<=" or "?<!", then the remainder of the group is matched against the part of the string that has already been consumed. If a match can be found that ends at the current location, then the outer match proceeds as if the group were not there. Otherwise, it doesn't match.

You can use any regular expression syntax within a look-behind, including group capture and anchors.

You can also use a look-behind as the condition in a conditional.

Examples:

R$('/(?<=(\w+)\s+)Smith/') - matches "Smith" when it is preceded by another word, and captures that word as sub-expression 1.

R$('/\b\w+\b(?<!s)/') - matches words that don't end with 's'.

(?= ), (?! ) - look-ahead

If a parenthesized group begins with "?=" or "?!", then the remainder of the group is matched against what follows in the string, without changing the position for the rest of the expression. If a match can be found that begins at the current location, then the outer match proceeds as if the group were not there. Otherwise, it doesn't match.

You can use any regular expression syntax within a look-ahead, including group capture and anchors.

You can also use a look-ahead as the condition in a conditional.

Examples:

R$('/John(?=\s+(\w+))/') - matches "John" when it is followed by another word, and captures that word as sub-expression 1.

R$('/(?!\d*5)\d+/') - matches a group of digits, but only if they don't contain a 5.

(?imnsx) - dynamically set options

For each of the letters that this group includes, the corresponding option is turned on for the remainder of the expression. You can explicitly turn off an option by preceding it with a '-'. The options are the same as when specified following the pattern (which sets their initial states), except that Continue (c) and GlobalSearch (g) are not included because those options cannot be applied to only part of an expression.

Examples:

If the options are followed by a colon (:), then they only apply to the expression that follows the colon up to the close parenthesis. The above examples can therefore be rewritten as:

When using the first form, be aware that the ExplicitCapture and Extended options affect the operation of the compile phase, while the other three (IgnoreCase, Multiline, and DotMatchesNewline) affect pattern matching. Thus, the former always apply left to right, while the latter can affect earlier parts of the expression when repeating. For example:

The above matches any word where only the first character may be capitalized or not (thanks to the initial IgnoreCase option selected after the pattern), but the remaining characters must be lowercase. That's because the (?-i) still applies on the second and following repetitions of the loop. While this can be useful, it can also be confusing. To avoid these situations, use the encapsulated form (with the colon) where the scope of the setting is clear.

(?P<group> ) - named group sub-expression (Python syntax)

Creates a sub-expression that does have a numbered back-reference, but may also be referenced by the name group. Group names are always case-sensitive. They may contain any characters except > and ). The text following the >, up to but not including the ) is the sub-expression to capture.

Group names do not have to be unique. In cases where they collide, both sub-expressions map to the same collector, which may be accessed by name or by number. The number assigned to all sub-expressions having the same name will be based on when the first one was encountered. When back-referenced or accessed from the replace or MatchData object, the contents of the group will be from the last time a group with that name was matched.

This form of named group capture is based on Python syntax. Unlike the .NET syntax for named groups, these groups are numbered where they occur, along with unnamed groups.

Examples:

match = R$('/a(?<els>l+)i/').match('alligator')
assert(match['els'].start == 2)
assert(match['els'].length == 2)
assert(match[1].start == 2)
assert(match[1].length == 2)

r1 = r$('/a(?P<x>\d)|b(?P<x>\w)/')
match = r1.match('a5')
assert_equal('5', match['x'].matched)
match = r1.match('bd')
assert_equal('d', match['x'].matched)

(?P=group) - named group back-reference

Back-references the text previously captured in the named group group. If that group has not yet been captured, an empty string is used.

Example:

match = r$('/(?P<quote>[''"]).*?(?P=quote)/').match('I said, "She''s a witch"')
assert_equal(9, match.start)
assert_equal(15, match.length)

* - zero or more

Also known as a Kleene closure, this operator matches as many of the preceding expression as possible (greedy search, but see ? below), but can match none of them, depending on the constraints of the rest of the expression.

Example: R$('/A*B/') matches 'B', 'AB', 'ZAAB', and even 'AZB' (because the final 'B' matches the "zero A's followed by B" case.

+ - one or more

This operator matches at least one, but as many as possible (greedy search, but see ? below), of the preceding expression.

Example: R$('/A+B/') matches 'AB' and 'ZAAB', but not 'B' or 'AZB'.

. - any single character

This metacharacter matches any character (except sometimes newline). It's often used to skip over stuff you don't care what it is. But be careful of searches that are greedier than you intended.

By default, the period does not match a newline character (linefeed, char(10)). You can force period to match newline by enabling the DotMatchesNewline option.

Example: R$('/A.B/') matches 'AAB' and 'ACB', but not 'AB'. R$('/.*B/') matches 'ABRACADABRA' at position 1, but the length of the match is 9 (inclusive of the second 'B').

? - zero or one

This operator matches one or none of the preceding expression. It prefers one by default (greedy), but if immediately followed by another ? (see below) it prefers none.

Example: R$('/A?B/') matchs 'B', 'AB', 'ZAAB' (at position 3) and even 'AZB' (also at position 3).

? - non-greedy match

If a ? immediately follows a *, +, or ? operator, then the match is non-greedy, meaning that it prefers fewer repetitions rather than greater.

Example: R$('/A*?/') matches 'AAA' at position 1, with a length of zero, whereas without the ? it would match to a length of 3.

[ ] - character class

The characters between matching square brackets forms a specification of a character class. In its simplest form, it's just a list of the characters that qualify. For example: R$('/[xyz]/') matches "x", "y" or "z". In this form, it's synonymous with R$('/x|y|z/').

If the first character within the brackets is "^", then the sense of the character class is reversed. That is, anything except these characters. For example, R$('/[^abc]/') will not match any of the first three lower-case letters of the alphabet.

The back-slash can be used to introduce special characters into the sequence, as detailed below. Thus, R$('/[\d.]/') matches any numeric digit or a period. Note that the period (along with most special characters) has a literal meaning when used within a character class.

A dash ('-') can be used to specify a range of characters. For example, R$('/[A-Z]/') matches all uppercase letters.

If a dash is immediately followed by a [, then it is taken to mean character class subtraction, and the [ is expected to have a matching ] to indicate the end of the class to subtract from the main class. For instance, to match all consonants, you could use R$('/[a-z-[aieou]]/i'). Note, therefore, that to end a range with [ you would need to escape it with a \. You may subtract more than one subclass, and you may nest subtractions. For example, R$('/[a-z-[k-o-[lm]]]'/) is functionally equivalent to R$('/[a-z-[kno]]/'), which could also be expressed as R$('/[a-jlmp-z]/'). Subtraction is more useful for readability than performance: R$('/[\d-[5]]/') says "all digits except 5" better than R$('/[0-46-9]/') does.

POSIX character classes can be enclosed within another level of brackets and colons. For instance, R$('/[[:punct:]]/') matches a punctuation character. See the list of supported character classes.

Once introduced, a character class becomes an expression like any other character. Thus, it can be repeated with '*', '+', or '?'. For example, R$('/[A-Za-z]*/)' matches any number of letters.

\ - escape a special character

The back-slash can be used to insert the character that follows, without special interpretation. However, there are some characters that have special meaning when following a back-slash, depending on context.

Legend
Only available within a character class
Only available when not within a character class
Available in both contexts

* The operation of \G differs between various regex engines, so it bears explaining here. \G represents an anchor to the end of the last match, meaning that what follows \G must match what follows that position. The actual position used is maintained in the public member ContinueFrom, so that implies that it is Regex-specific, but not string-specific. If you reuse a Regex that contains \G with another target string, you may want to clear the ContinueFrom member first. Conversely, if you want to use another Regex with the same string and have it continue from the match of the other Regex, you must first copy the ContinueFrom value from the first Regex to the second one. When a match fails, ContinueFrom is set to 0, unless the Continue option is true.

^ - anchor to beginning of line

The match must begin with the first character of a line of text in order to be accepted. If Multiline is true, then an embedded newline character qualifies as marking the beginning of line, but the beginning of the string always qualifies.

Example: R$('/^front/') matches 'front-end', but not 'affront'.

{ } - specify minimum/maximum repetitions

This operator optionally specifies the minimum and maximum number of repetitions for the term that it follows. It can take any of the following forms:

• {n} - repeat exactly n times.
• {n,m} - repeat at least n times, but not more than m times.
• {n,} - repeat at least n times, but with no maximum.
• {,m} - repeat no more than m times, but with no minimum.

| - union (or)

This operator occurs between two expressions to specify that either one or the other is required. It has the lowest operator priority of any operator, so to prevent everything on one side or the other from being lumped together, use parentheses.

Example: R$('/c(a|u)t/') matches 'cat' and 'cut' at position 1. But R$('/ca|ut/') matches 'cut' at position 2 ("ut").

Note: when used in a conditional group, this operator can be taken as an "else" instead.