diff options
Diffstat (limited to 'doc/pcre_man.txt')
| -rw-r--r-- | doc/pcre_man.txt | 1206 |
1 files changed, 1206 insertions, 0 deletions
diff --git a/doc/pcre_man.txt b/doc/pcre_man.txt new file mode 100644 index 0000000..e3b1c7d --- /dev/null +++ b/doc/pcre_man.txt @@ -0,0 +1,1206 @@ +NAME + pcre - Perl-compatible regular expressions. + + +REGULAR EXPRESSION DETAILS + The syntax and semantics of the regular expressions sup- + ported by PCRE are described below. Regular expressions are + also described in the Perl documentation and in a number of + other books, some of which have copious examples. Jeffrey + Friedl's "Mastering Regular Expressions", published by + O'Reilly (ISBN 1-56592-257), covers them in great detail. + + The description here is intended as reference documentation. + The basic operation of PCRE is on strings of bytes. However, + there is the beginnings of some support for UTF-8 character + strings. To use this support you must configure PCRE to + include it, and then call pcre_compile() with the PCRE_UTF8 + option. How this affects the pattern matching is described + in the final section of this document. + + A regular expression is a pattern that is matched against a + subject string from left to right. Most characters stand for + themselves in a pattern, and match the corresponding charac- + ters in the subject. As a trivial example, the pattern + + The quick brown fox + + matches a portion of a subject string that is identical to + itself. The power of regular expressions comes from the + ability to include alternatives and repetitions in the pat- + tern. These are encoded in the pattern by the use of meta- + characters, which do not stand for themselves but instead + are interpreted in some special way. + + There are two different sets of meta-characters: those that + are recognized anywhere in the pattern except within square + brackets, and those that are recognized in square brackets. + Outside square brackets, the meta-characters are as follows: + + \ general escape character with several uses + ^ assert start of subject (or line, in multiline + mode) + $ assert end of subject (or line, in multiline mode) + . match any character except newline (by default) + [ start character class definition + | start of alternative branch + ( start subpattern + ) end subpattern + ? extends the meaning of ( + also 0 or 1 quantifier + also quantifier minimizer + * 0 or more quantifier + + 1 or more quantifier + { start min/max quantifier + + Part of a pattern that is in square brackets is called a + "character class". In a character class the only meta- + characters are: + + \ general escape character + ^ negate the class, but only if the first character + - indicates character range + ] terminates the character class + + The following sections describe the use of each of the + meta-characters. + + + +BACKSLASH + The backslash character has several uses. Firstly, if it is + followed by a non-alphameric character, it takes away any + special meaning that character may have. This use of + + backslash as an escape character applies both inside and + outside character classes. + + For example, if you want to match a "*" character, you write + "\*" in the pattern. This applies whether or not the follow- + ing character would otherwise be interpreted as a meta- + character, so it is always safe to precede a non-alphameric + with "\" to specify that it stands for itself. In particu- + lar, if you want to match a backslash, you write "\\". + + If a pattern is compiled with the PCRE_EXTENDED option, whi- + tespace in the pattern (other than in a character class) and + characters between a "#" outside a character class and the + next newline character are ignored. An escaping backslash + can be used to include a whitespace or "#" character as part + of the pattern. + + A second use of backslash provides a way of encoding non- + printing characters in patterns in a visible manner. There + is no restriction on the appearance of non-printing charac- + ters, apart from the binary zero that terminates a pattern, + but when a pattern is being prepared by text editing, it is + usually easier to use one of the following escape sequences + than the binary character it represents: + + \a alarm, that is, the BEL character (hex 07) + \cx "control-x", where x is any character + \e escape (hex 1B) + \f formfeed (hex 0C) + \n newline (hex 0A) + \r carriage return (hex 0D) + \t tab (hex 09) + \xhh character with hex code hh + \ddd character with octal code ddd, or backreference + + The precise effect of "\cx" is as follows: if "x" is a lower + case letter, it is converted to upper case. Then bit 6 of + the character (hex 40) is inverted. Thus "\cz" becomes hex + 1A, but "\c{" becomes hex 3B, while "\c;" becomes hex 7B. + + After "\x", up to two hexadecimal digits are read (letters + can be in upper or lower case). + + After "\0" up to two further octal digits are read. In both + cases, if there are fewer than two digits, just those that + are present are used. Thus the sequence "\0\x\07" specifies + two binary zeros followed by a BEL character. Make sure you + supply two digits after the initial zero if the character + that follows is itself an octal digit. + + The handling of a backslash followed by a digit other than 0 + is complicated. Outside a character class, PCRE reads it + and any following digits as a decimal number. If the number + is less than 10, or if there have been at least that many + previous capturing left parentheses in the expression, the + entire sequence is taken as a back reference. A description + of how this works is given later, following the discussion + of parenthesized subpatterns. + + Inside a character class, or if the decimal number is + greater than 9 and there have not been that many capturing + subpatterns, PCRE re-reads up to three octal digits follow- + ing the backslash, and generates a single byte from the + least significant 8 bits of the value. Any subsequent digits + stand for themselves. For example: + + \040 is another way of writing a space + \40 is the same, provided there are fewer than 40 + previous capturing subpatterns + \7 is always a back reference + \11 might be a back reference, or another way of + writing a tab + \011 is always a tab + \0113 is a tab followed by the character "3" + \113 is the character with octal code 113 (since there + can be no more than 99 back references) + \377 is a byte consisting entirely of 1 bits + \81 is either a back reference, or a binary zero + followed by the two characters "8" and "1" + + Note that octal values of 100 or greater must not be intro- + duced by a leading zero, because no more than three octal + digits are ever read. + + All the sequences that define a single byte value can be + used both inside and outside character classes. In addition, + inside a character class, the sequence "\b" is interpreted + as the backspace character (hex 08). Outside a character + class it has a different meaning (see below). + + The third use of backslash is for specifying generic charac- + ter types: + + \d any decimal digit + \D any character that is not a decimal digit + \s any whitespace character + \S any character that is not a whitespace character + \w any "word" character + \W any "non-word" character + + Each pair of escape sequences partitions the complete set of + characters into two disjoint sets. Any given character + matches one, and only one, of each pair. + + A "word" character is any letter or digit or the underscore + character, that is, any character which can be part of a + Perl "word". The definition of letters and digits is con- + trolled by PCRE's character tables, and may vary if locale- + specific matching is taking place (see "Locale support" + above). For example, in the "fr" (French) locale, some char- + acter codes greater than 128 are used for accented letters, + and these are matched by \w. + + These character type sequences can appear both inside and + outside character classes. They each match one character of + the appropriate type. If the current matching point is at + the end of the subject string, all of them fail, since there + is no character to match. + + The fourth use of backslash is for certain simple asser- + tions. An assertion specifies a condition that has to be met + at a particular point in a match, without consuming any + characters from the subject string. The use of subpatterns + for more complicated assertions is described below. The + backslashed assertions are + + \b word boundary + \B not a word boundary + \A start of subject (independent of multiline mode) + \Z end of subject or newline at end (independent of + multiline mode) + \z end of subject (independent of multiline mode) + + These assertions may not appear in character classes (but + note that "\b" has a different meaning, namely the backspace + character, inside a character class). + + A word boundary is a position in the subject string where + the current character and the previous character do not both + match \w or \W (i.e. one matches \w and the other matches + \W), or the start or end of the string if the first or last + character matches \w, respectively. + + The \A, \Z, and \z assertions differ from the traditional + circumflex and dollar (described below) in that they only + ever match at the very start and end of the subject string, + whatever options are set. They are not affected by the + PCRE_NOTBOL or PCRE_NOTEOL options. If the startoffset argu- + ment of pcre_exec() is non-zero, \A can never match. The + difference between \Z and \z is that \Z matches before a + newline that is the last character of the string as well as + at the end of the string, whereas \z matches only at the + end. + + + +CIRCUMFLEX AND DOLLAR + Outside a character class, in the default matching mode, the + circumflex character is an assertion which is true only if + the current matching point is at the start of the subject + string. If the startoffset argument of pcre_exec() is non- + zero, circumflex can never match. Inside a character class, + circumflex has an entirely different meaning (see below). + + Circumflex need not be the first character of the pattern if + a number of alternatives are involved, but it should be the + first thing in each alternative in which it appears if the + pattern is ever to match that branch. If all possible alter- + natives start with a circumflex, that is, if the pattern is + constrained to match only at the start of the subject, it is + said to be an "anchored" pattern. (There are also other con- + structs that can cause a pattern to be anchored.) + + A dollar character is an assertion which is true only if the + current matching point is at the end of the subject string, + or immediately before a newline character that is the last + character in the string (by default). Dollar need not be the + last character of the pattern if a number of alternatives + are involved, but it should be the last item in any branch + in which it appears. Dollar has no special meaning in a + character class. + + The meaning of dollar can be changed so that it matches only + at the very end of the string, by setting the + PCRE_DOLLAR_ENDONLY option at compile or matching time. This + does not affect the \Z assertion. + + The meanings of the circumflex and dollar characters are + changed if the PCRE_MULTILINE option is set. When this is + the case, they match immediately after and immediately + before an internal "\n" character, respectively, in addition + to matching at the start and end of the subject string. For + example, the pattern /^abc$/ matches the subject string + "def\nabc" in multiline mode, but not otherwise. Conse- + quently, patterns that are anchored in single line mode + because all branches start with "^" are not anchored in mul- + tiline mode, and a match for circumflex is possible when the + startoffset argument of pcre_exec() is non-zero. The + PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is + set. + + Note that the sequences \A, \Z, and \z can be used to match + the start and end of the subject in both modes, and if all + branches of a pattern start with \A it is always anchored, + whether PCRE_MULTILINE is set or not. + + + +FULL STOP (PERIOD, DOT) + Outside a character class, a dot in the pattern matches any + one character in the subject, including a non-printing char- + acter, but not (by default) newline. If the PCRE_DOTALL + option is set, dots match newlines as well. The handling of + dot is entirely independent of the handling of circumflex + and dollar, the only relationship being that they both + involve newline characters. Dot has no special meaning in a + character class. + + + +SQUARE BRACKETS + An opening square bracket introduces a character class, ter- + minated by a closing square bracket. A closing square + bracket on its own is not special. If a closing square + bracket is required as a member of the class, it should be + the first data character in the class (after an initial cir- + cumflex, if present) or escaped with a backslash. + + A character class matches a single character in the subject; + the character must be in the set of characters defined by + the class, unless the first character in the class is a cir- + cumflex, in which case the subject character must not be in + the set defined by the class. If a circumflex is actually + required as a member of the class, ensure it is not the + first character, or escape it with a backslash. + + For example, the character class [aeiou] matches any lower + case vowel, while [^aeiou] matches any character that is not + a lower case vowel. Note that a circumflex is just a con- + venient notation for specifying the characters which are in + the class by enumerating those that are not. It is not an + assertion: it still consumes a character from the subject + string, and fails if the current pointer is at the end of + the string. + + When caseless matching is set, any letters in a class + represent both their upper case and lower case versions, so + for example, a caseless [aeiou] matches "A" as well as "a", + and a caseless [^aeiou] does not match "A", whereas a case- + ful version would. + + The newline character is never treated in any special way in + character classes, whatever the setting of the PCRE_DOTALL + or PCRE_MULTILINE options is. A class such as [^a] will + always match a newline. + + The minus (hyphen) character can be used to specify a range + of characters in a character class. For example, [d-m] + matches any letter between d and m, inclusive. If a minus + character is required in a class, it must be escaped with a + backslash or appear in a position where it cannot be inter- + preted as indicating a range, typically as the first or last + character in the class. + + It is not possible to have the literal character "]" as the + end character of a range. A pattern such as [W-]46] is + interpreted as a class of two characters ("W" and "-") fol- + lowed by a literal string "46]", so it would match "W46]" or + "-46]". However, if the "]" is escaped with a backslash it + is interpreted as the end of range, so [W-\]46] is inter- + preted as a single class containing a range followed by two + separate characters. The octal or hexadecimal representation + of "]" can also be used to end a range. + + Ranges operate in ASCII collating sequence. They can also be + used for characters specified numerically, for example + [\000-\037]. If a range that includes letters is used when + caseless matching is set, it matches the letters in either + case. For example, [W-c] is equivalent to [][\^_`wxyzabc], + matched caselessly, and if character tables for the "fr" + locale are in use, [\xc8-\xcb] matches accented E characters + in both cases. + + The character types \d, \D, \s, \S, \w, and \W may also + appear in a character class, and add the characters that + they match to the class. For example, [\dABCDEF] matches any + hexadecimal digit. A circumflex can conveniently be used + with the upper case character types to specify a more res- + tricted set of characters than the matching lower case type. + For example, the class [^\W_] matches any letter or digit, + but not underscore. + + All non-alphameric characters other than \, -, ^ (at the + start) and the terminating ] are non-special in character + classes, but it does no harm if they are escaped. + + + +POSIX CHARACTER CLASSES + Perl 5.6 (not yet released at the time of writing) is going + to support the POSIX notation for character classes, which + uses names enclosed by [: and :] within the enclosing + square brackets. PCRE supports this notation. For example, + + [01[:alpha:]%] + + matches "0", "1", any alphabetic character, or "%". The sup- + ported class names are + + alnum letters and digits + alpha letters + ascii character codes 0 - 127 + cntrl control characters + digit decimal digits (same as \d) + graph printing characters, excluding space + lower lower case letters + print printing characters, including space + punct printing characters, excluding letters and digits + space white space (same as \s) + upper upper case letters + word "word" characters (same as \w) + xdigit hexadecimal digits + + The names "ascii" and "word" are Perl extensions. Another + Perl extension is negation, which is indicated by a ^ char- + acter after the colon. For example, + + [12[:^digit:]] + + matches "1", "2", or any non-digit. PCRE (and Perl) also + recognize the POSIX syntax [.ch.] and [=ch=] where "ch" is a + "collating element", but these are not supported, and an + error is given if they are encountered. + + + +VERTICAL BAR + Vertical bar characters are used to separate alternative + patterns. For example, the pattern + + gilbert|sullivan + + matches either "gilbert" or "sullivan". Any number of alter- + natives may appear, and an empty alternative is permitted + (matching the empty string). The matching process tries + each alternative in turn, from left to right, and the first + one that succeeds is used. If the alternatives are within a + subpattern (defined below), "succeeds" means matching the + rest of the main pattern as well as the alternative in the + subpattern. + + + +INTERNAL OPTION SETTING + The settings of PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, + and PCRE_EXTENDED can be changed from within the pattern by + a sequence of Perl option letters enclosed between "(?" and + ")". The option letters are + + i for PCRE_CASELESS + m for PCRE_MULTILINE + s for PCRE_DOTALL + x for PCRE_EXTENDED + + For example, (?im) sets caseless, multiline matching. It is + also possible to unset these options by preceding the letter + with a hyphen, and a combined setting and unsetting such as + (?im-sx), which sets PCRE_CASELESS and PCRE_MULTILINE while + unsetting PCRE_DOTALL and PCRE_EXTENDED, is also permitted. + If a letter appears both before and after the hyphen, the + option is unset. + + The scope of these option changes depends on where in the + pattern the setting occurs. For settings that are outside + any subpattern (defined below), the effect is the same as if + the options were set or unset at the start of matching. The + following patterns all behave in exactly the same way: + + (?i)abc + a(?i)bc + ab(?i)c + abc(?i) + + which in turn is the same as compiling the pattern abc with + PCRE_CASELESS set. In other words, such "top level" set- + tings apply to the whole pattern (unless there are other + changes inside subpatterns). If there is more than one set- + ting of the same option at top level, the rightmost setting + is used. + + If an option change occurs inside a subpattern, the effect + is different. This is a change of behaviour in Perl 5.005. + An option change inside a subpattern affects only that part + of the subpattern that follows it, so + + (a(?i)b)c + + matches abc and aBc and no other strings (assuming + PCRE_CASELESS is not used). By this means, options can be + made to have different settings in different parts of the + pattern. Any changes made in one alternative do carry on + into subsequent branches within the same subpattern. For + example, + + (a(?i)b|c) + + matches "ab", "aB", "c", and "C", even though when matching + "C" the first branch is abandoned before the option setting. + This is because the effects of option settings happen at + compile time. There would be some very weird behaviour oth- + erwise. + + The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can + be changed in the same way as the Perl-compatible options by + using the characters U and X respectively. The (?X) flag + setting is special in that it must always occur earlier in + the pattern than any of the additional features it turns on, + even when it is at top level. It is best put at the start. + + + +SUBPATTERNS + Subpatterns are delimited by parentheses (round brackets), + which can be nested. Marking part of a pattern as a subpat- + tern does two things: + + 1. It localizes a set of alternatives. For example, the pat- + tern + + cat(aract|erpillar|) + + matches one of the words "cat", "cataract", or "caterpil- + lar". Without the parentheses, it would match "cataract", + "erpillar" or the empty string. + + 2. It sets up the subpattern as a capturing subpattern (as + defined above). When the whole pattern matches, that por- + tion of the subject string that matched the subpattern is + passed back to the caller via the ovector argument of + pcre_exec(). Opening parentheses are counted from left to + right (starting from 1) to obtain the numbers of the captur- + ing subpatterns. + + For example, if the string "the red king" is matched against + the pattern + + the ((red|white) (king|queen)) + + the captured substrings are "red king", "red", and "king", + and are numbered 1, 2, and 3, respectively. + + The fact that plain parentheses fulfil two functions is not + always helpful. There are often times when a grouping sub- + pattern is required without a capturing requirement. If an + opening parenthesis is followed by "?:", the subpattern does + not do any capturing, and is not counted when computing the + number of any subsequent capturing subpatterns. For example, + if the string "the white queen" is matched against the pat- + tern + + the ((?:red|white) (king|queen)) + + the captured substrings are "white queen" and "queen", and + are numbered 1 and 2. The maximum number of captured sub- + strings is 99, and the maximum number of all subpatterns, + both capturing and non-capturing, is 200. + + As a convenient shorthand, if any option settings are + required at the start of a non-capturing subpattern, the + option letters may appear between the "?" and the ":". Thus + the two patterns + + (?i:saturday|sunday) + (?:(?i)saturday|sunday) + + match exactly the same set of strings. Because alternative + branches are tried from left to right, and options are not + reset until the end of the subpattern is reached, an option + setting in one branch does affect subsequent branches, so + the above patterns match "SUNDAY" as well as "Saturday". + + + +REPETITION + Repetition is specified by quantifiers, which can follow any + of the following items: + + a single character, possibly escaped + the . metacharacter + a character class + a back reference (see next section) + a parenthesized subpattern (unless it is an assertion - + see below) + + The general repetition quantifier specifies a minimum and + maximum number of permitted matches, by giving the two + numbers in curly brackets (braces), separated by a comma. + The numbers must be less than 65536, and the first must be + less than or equal to the second. For example: + + z{2,4} + + matches "zz", "zzz", or "zzzz". A closing brace on its own + is not a special character. If the second number is omitted, + but the comma is present, there is no upper limit; if the + second number and the comma are both omitted, the quantifier + specifies an exact number of required matches. Thus + + [aeiou]{3,} + + matches at least 3 successive vowels, but may match many + more, while + + \d{8} + + matches exactly 8 digits. An opening curly bracket that + appears in a position where a quantifier is not allowed, or + one that does not match the syntax of a quantifier, is taken + as a literal character. For example, {,6} is not a quantif- + ier, but a literal string of four characters. + The quantifier {0} is permitted, causing the expression to + behave as if the previous item and the quantifier were not + present. + + For convenience (and historical compatibility) the three + most common quantifiers have single-character abbreviations: + + * is equivalent to {0,} + + is equivalent to {1,} + ? is equivalent to {0,1} + + It is possible to construct infinite loops by following a + subpattern that can match no characters with a quantifier + that has no upper limit, for example: + + (a?)* + + Earlier versions of Perl and PCRE used to give an error at + compile time for such patterns. However, because there are + cases where this can be useful, such patterns are now + accepted, but if any repetition of the subpattern does in + fact match no characters, the loop is forcibly broken. + + By default, the quantifiers are "greedy", that is, they + match as much as possible (up to the maximum number of per- + mitted times), without causing the rest of the pattern to + fail. The classic example of where this gives problems is in + trying to match comments in C programs. These appear between + the sequences /* and */ and within the sequence, individual + * and / characters may appear. An attempt to match C com- + ments by applying the pattern + + /\*.*\*/ + + to the string + + /* first command */ not comment /* second comment */ + + fails, because it matches the entire string owing to the + greediness of the .* item. + + However, if a quantifier is followed by a question mark, it + ceases to be greedy, and instead matches the minimum number + of times possible, so the pattern + + /\*.*?\*/ + + does the right thing with the C comments. The meaning of the + various quantifiers is not otherwise changed, just the pre- + ferred number of matches. Do not confuse this use of ques- + tion mark with its use as a quantifier in its own right. + Because it has two uses, it can sometimes appear doubled, as + in + + \d??\d + + which matches one digit by preference, but can match two if + that is the only way the rest of the pattern matches. + + If the PCRE_UNGREEDY option is set (an option which is not + available in Perl), the quantifiers are not greedy by + default, but individual ones can be made greedy by following + them with a question mark. In other words, it inverts the + default behaviour. + + When a parenthesized subpattern is quantified with a minimum + repeat count that is greater than 1 or with a limited max- + imum, more store is required for the compiled pattern, in + proportion to the size of the minimum or maximum. + + If a pattern starts with .* or .{0,} and the PCRE_DOTALL + option (equivalent to Perl's /s) is set, thus allowing the . + to match newlines, the pattern is implicitly anchored, + because whatever follows will be tried against every charac- + ter position in the subject string, so there is no point in + retrying the overall match at any position after the first. + PCRE treats such a pattern as though it were preceded by \A. + In cases where it is known that the subject string contains + no newlines, it is worth setting PCRE_DOTALL when the pat- + tern begins with .* in order to obtain this optimization, or + alternatively using ^ to indicate anchoring explicitly. + + When a capturing subpattern is repeated, the value captured + is the substring that matched the final iteration. For exam- + ple, after + + (tweedle[dume]{3}\s*)+ + + has matched "tweedledum tweedledee" the value of the cap- + tured substring is "tweedledee". However, if there are + nested capturing subpatterns, the corresponding captured + values may have been set in previous iterations. For exam- + ple, after + + /(a|(b))+/ + + matches "aba" the value of the second captured substring is + "b". + + + +BACK REFERENCES + Outside a character class, a backslash followed by a digit + greater than 0 (and possibly further digits) is a back + reference to a capturing subpattern earlier (i.e. to its + left) in the pattern, provided there have been that many + previous capturing left parentheses. + + However, if the decimal number following the backslash is + less than 10, it is always taken as a back reference, and + causes an error only if there are not that many capturing + left parentheses in the entire pattern. In other words, the + parentheses that are referenced need not be to the left of + the reference for numbers less than 10. See the section + entitled "Backslash" above for further details of the han- + dling of digits following a backslash. + + A back reference matches whatever actually matched the cap- + turing subpattern in the current subject string, rather than + anything matching the subpattern itself. So the pattern + + (sens|respons)e and \1ibility + + matches "sense and sensibility" and "response and responsi- + bility", but not "sense and responsibility". If caseful + matching is in force at the time of the back reference, the + case of letters is relevant. For example, + + ((?i)rah)\s+\1 + + matches "rah rah" and "RAH RAH", but not "RAH rah", even + though the original capturing subpattern is matched case- + lessly. + + There may be more than one back reference to the same sub- + pattern. If a subpattern has not actually been used in a + particular match, any back references to it always fail. For + example, the pattern + + (a|(bc))\2 + + always fails if it starts to match "a" rather than "bc". + Because there may be up to 99 back references, all digits + following the backslash are taken as part of a potential + back reference number. If the pattern continues with a digit + character, some delimiter must be used to terminate the back + reference. If the PCRE_EXTENDED option is set, this can be + whitespace. Otherwise an empty comment can be used. + + A back reference that occurs inside the parentheses to which + it refers fails when the subpattern is first used, so, for + example, (a\1) never matches. However, such references can + be useful inside repeated subpatterns. For example, the pat- + tern + + (a|b\1)+ + + matches any number of "a"s and also "aba", "ababbaa" etc. At + each iteration of the subpattern, the back reference matches + the character string corresponding to the previous itera- + tion. In order for this to work, the pattern must be such + that the first iteration does not need to match the back + reference. This can be done using alternation, as in the + example above, or by a quantifier with a minimum of zero. + + + +ASSERTIONS + An assertion is a test on the characters following or + preceding the current matching point that does not actually + consume any characters. The simple assertions coded as \b, + \B, \A, \Z, \z, ^ and $ are described above. More compli- + cated assertions are coded as subpatterns. There are two + kinds: those that look ahead of the current position in the + subject string, and those that look behind it. + + An assertion subpattern is matched in the normal way, except + that it does not cause the current matching position to be + changed. Lookahead assertions start with (?= for positive + assertions and (?! for negative assertions. For example, + + \w+(?=;) + + matches a word followed by a semicolon, but does not include + the semicolon in the match, and + + foo(?!bar) + + matches any occurrence of "foo" that is not followed by + "bar". Note that the apparently similar pattern + + (?!foo)bar + + does not find an occurrence of "bar" that is preceded by + something other than "foo"; it finds any occurrence of "bar" + whatsoever, because the assertion (?!foo) is always true + when the next three characters are "bar". A lookbehind + assertion is needed to achieve this effect. + + Lookbehind assertions start with (?<= for positive asser- + tions and (?<! for negative assertions. For example, + + (?<!foo)bar + + does find an occurrence of "bar" that is not preceded by + "foo". The contents of a lookbehind assertion are restricted + such that all the strings it matches must have a fixed + length. However, if there are several alternatives, they do + not all have to have the same fixed length. Thus + + (?<=bullock|donkey) + + is permitted, but + + (?<!dogs?|cats?) + + causes an error at compile time. Branches that match dif- + ferent length strings are permitted only at the top level of + a lookbehind assertion. This is an extension compared with + Perl 5.005, which requires all branches to match the same + length of string. An assertion such as + + (?<=ab(c|de)) + + is not permitted, because its single top-level branch can + match two different lengths, but it is acceptable if rewrit- + ten to use two top-level branches: + + (?<=abc|abde) + + The implementation of lookbehind assertions is, for each + alternative, to temporarily move the current position back + by the fixed width and then try to match. If there are + insufficient characters before the current position, the + match is deemed to fail. Lookbehinds in conjunction with + once-only subpatterns can be particularly useful for match- + ing at the ends of strings; an example is given at the end + of the section on once-only subpatterns. + + Several assertions (of any sort) may occur in succession. + For example, + + (?<=\d{3})(?<!999)foo + + matches "foo" preceded by three digits that are not "999". + Notice that each of the assertions is applied independently + at the same point in the subject string. First there is a + check that the previous three characters are all digits, and + then there is a check that the same three characters are not + "999". This pattern does not match "foo" preceded by six + characters, the first of which are digits and the last three + of which are not "999". For example, it doesn't match + "123abcfoo". A pattern to do that is + + (?<=\d{3}...)(?<!999)foo + + This time the first assertion looks at the preceding six + characters, checking that the first three are digits, and + then the second assertion checks that the preceding three + characters are not "999". + + Assertions can be nested in any combination. For example, + + (?<=(?<!foo)bar)baz + + matches an occurrence of "baz" that is preceded by "bar" + which in turn is not preceded by "foo", while + + (?<=\d{3}(?!999)...)foo + + is another pattern which matches "foo" preceded by three + digits and any three characters that are not "999". + + Assertion subpatterns are not capturing subpatterns, and may + not be repeated, because it makes no sense to assert the + same thing several times. If any kind of assertion contains + capturing subpatterns within it, these are counted for the + purposes of numbering the capturing subpatterns in the whole + pattern. However, substring capturing is carried out only + for positive assertions, because it does not make sense for + negative assertions. + + Assertions count towards the maximum of 200 parenthesized + subpatterns. + + + +ONCE-ONLY SUBPATTERNS + With both maximizing and minimizing repetition, failure of + what follows normally causes the repeated item to be re- + evaluated to see if a different number of repeats allows the + rest of the pattern to match. Sometimes it is useful to + prevent this, either to change the nature of the match, or + to cause it fail earlier than it otherwise might, when the + author of the pattern knows there is no point in carrying + on. + + Consider, for example, the pattern \d+foo when applied to + the subject line + + 123456bar + + After matching all 6 digits and then failing to match "foo", + the normal action of the matcher is to try again with only 5 + digits matching the \d+ item, and then with 4, and so on, + before ultimately failing. Once-only subpatterns provide the + means for specifying that once a portion of the pattern has + matched, it is not to be re-evaluated in this way, so the + matcher would give up immediately on failing to match "foo" + the first time. The notation is another kind of special + parenthesis, starting with (?> as in this example: + + (?>\d+)bar + + This kind of parenthesis "locks up" the part of the pattern + it contains once it has matched, and a failure further into + the pattern is prevented from backtracking into it. Back- + tracking past it to previous items, however, works as nor- + mal. + + An alternative description is that a subpattern of this type + matches the string of characters that an identical stan- + dalone pattern would match, if anchored at the current point + in the subject string. + + Once-only subpatterns are not capturing subpatterns. Simple + cases such as the above example can be thought of as a max- + imizing repeat that must swallow everything it can. So, + while both \d+ and \d+? are prepared to adjust the number of + digits they match in order to make the rest of the pattern + match, (?>\d+) can only match an entire sequence of digits. + + This construction can of course contain arbitrarily compli- + cated subpatterns, and it can be nested. + + Once-only subpatterns can be used in conjunction with look- + behind assertions to specify efficient matching at the end + of the subject string. Consider a simple pattern such as + + abcd$ + + when applied to a long string which does not match. Because + matching proceeds from left to right, PCRE will look for + each "a" in the subject and then see if what follows matches + the rest of the pattern. If the pattern is specified as + + ^.*abcd$ + + the initial .* matches the entire string at first, but when + this fails (because there is no following "a"), it back- + tracks to match all but the last character, then all but the + last two characters, and so on. Once again the search for + "a" covers the entire string, from right to left, so we are + no better off. However, if the pattern is written as + + ^(?>.*)(?<=abcd) + + there can be no backtracking for the .* item; it can match + only the entire string. The subsequent lookbehind assertion + does a single test on the last four characters. If it fails, + the match fails immediately. For long strings, this approach + makes a significant difference to the processing time. + + When a pattern contains an unlimited repeat inside a subpat- + tern that can itself be repeated an unlimited number of + times, the use of a once-only subpattern is the only way to + avoid some failing matches taking a very long time indeed. + The pattern + + (\D+|<\d+>)*[!?] + + matches an unlimited number of substrings that either con- + sist of non-digits, or digits enclosed in <>, followed by + either ! or ?. When it matches, it runs quickly. However, if + it is applied to + + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + + it takes a long time before reporting failure. This is + because the string can be divided between the two repeats in + a large number of ways, and all have to be tried. (The exam- + ple used [!?] rather than a single character at the end, + because both PCRE and Perl have an optimization that allows + for fast failure when a single character is used. They + remember the last single character that is required for a + match, and fail early if it is not present in the string.) + If the pattern is changed to + + ((?>\D+)|<\d+>)*[!?] + + sequences of non-digits cannot be broken, and failure hap- + pens quickly. + + + +CONDITIONAL SUBPATTERNS + It is possible to cause the matching process to obey a sub- + pattern conditionally or to choose between two alternative + subpatterns, depending on the result of an assertion, or + whether a previous capturing subpattern matched or not. The + two possible forms of conditional subpattern are + + (?(condition)yes-pattern) + (?(condition)yes-pattern|no-pattern) + + If the condition is satisfied, the yes-pattern is used; oth- + erwise the no-pattern (if present) is used. If there are + more than two alternatives in the subpattern, a compile-time + error occurs. + + There are two kinds of condition. If the text between the + parentheses consists of a sequence of digits, the condition + is satisfied if the capturing subpattern of that number has + previously matched. The number must be greater than zero. + Consider the following pattern, which contains non- + significant white space to make it more readable (assume the + PCRE_EXTENDED option) and to divide it into three parts for + ease of discussion: + + ( \( )? [^()]+ (?(1) \) ) + + The first part matches an optional opening parenthesis, and + if that character is present, sets it as the first captured + substring. The second part matches one or more characters + that are not parentheses. The third part is a conditional + subpattern that tests whether the first set of parentheses + matched or not. If they did, that is, if subject started + with an opening parenthesis, the condition is true, and so + the yes-pattern is executed and a closing parenthesis is + required. Otherwise, since no-pattern is not present, the + subpattern matches nothing. In other words, this pattern + matches a sequence of non-parentheses, optionally enclosed + in parentheses. + + If the condition is not a sequence of digits, it must be an + assertion. This may be a positive or negative lookahead or + lookbehind assertion. Consider this pattern, again contain- + ing non-significant white space, and with the two alterna- + tives on the second line: + + (?(?=[^a-z]*[a-z]) + \d{2}-[a-z]{3}-\d{2} | \d{2}-\d{2}-\d{2} ) + + The condition is a positive lookahead assertion that matches + an optional sequence of non-letters followed by a letter. In + other words, it tests for the presence of at least one + letter in the subject. If a letter is found, the subject is + matched against the first alternative; otherwise it is + matched against the second. This pattern matches strings in + one of the two forms dd-aaa-dd or dd-dd-dd, where aaa are + letters and dd are digits. + + + +COMMENTS + The sequence (?# marks the start of a comment which contin- + ues up to the next closing parenthesis. Nested parentheses + are not permitted. The characters that make up a comment + play no part in the pattern matching at all. + + If the PCRE_EXTENDED option is set, an unescaped # character + outside a character class introduces a comment that contin- + ues up to the next newline character in the pattern. + + + +RECURSIVE PATTERNS + Consider the problem of matching a string in parentheses, + allowing for unlimited nested parentheses. Without the use + of recursion, the best that can be done is to use a pattern + that matches up to some fixed depth of nesting. It is not + possible to handle an arbitrary nesting depth. Perl 5.6 has + provided an experimental facility that allows regular + expressions to recurse (amongst other things). It does this + by interpolating Perl code in the expression at run time, + and the code can refer to the expression itself. A Perl pat- + tern to solve the parentheses problem can be created like + this: + + $re = qr{\( (?: (?>[^()]+) | (?p{$re}) )* \)}x; + + The (?p{...}) item interpolates Perl code at run time, and + in this case refers recursively to the pattern in which it + appears. Obviously, PCRE cannot support the interpolation of + Perl code. Instead, the special item (?R) is provided for + the specific case of recursion. This PCRE pattern solves the + parentheses problem (assume the PCRE_EXTENDED option is set + so that white space is ignored): + + \( ( (?>[^()]+) | (?R) )* \) + + First it matches an opening parenthesis. Then it matches any + number of substrings which can either be a sequence of non- + parentheses, or a recursive match of the pattern itself + (i.e. a correctly parenthesized substring). Finally there is + a closing parenthesis. + + This particular example pattern contains nested unlimited + repeats, and so the use of a once-only subpattern for match- + ing strings of non-parentheses is important when applying + the pattern to strings that do not match. For example, when + it is applied to + + (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa() + + it yields "no match" quickly. However, if a once-only sub- + pattern is not used, the match runs for a very long time + indeed because there are so many different ways the + and * + repeats can carve up the subject, and all have to be tested + before failure can be reported. + + The values set for any capturing subpatterns are those from + the outermost level of the recursion at which the subpattern + value is set. If the pattern above is matched against + + (ab(cd)ef) + + the value for the capturing parentheses is "ef", which is + the last value taken on at the top level. If additional + parentheses are added, giving + + \( ( ( (?>[^()]+) | (?R) )* ) \) + ^ ^ + ^ ^ the string they capture is + "ab(cd)ef", the contents of the top level parentheses. If + there are more than 15 capturing parentheses in a pattern, + PCRE has to obtain extra memory to store data during a + recursion, which it does by using pcre_malloc, freeing it + via pcre_free afterwards. If no memory can be obtained, it + saves data for the first 15 capturing parentheses only, as + there is no way to give an out-of-memory error from within a + recursion. + + + +PERFORMANCE + Certain items that may appear in patterns are more efficient + than others. It is more efficient to use a character class + like [aeiou] than a set of alternatives such as (a|e|i|o|u). + In general, the simplest construction that provides the + required behaviour is usually the most efficient. Jeffrey + Friedl's book contains a lot of discussion about optimizing + regular expressions for efficient performance. + + When a pattern begins with .* and the PCRE_DOTALL option is + set, the pattern is implicitly anchored by PCRE, since it + can match only at the start of a subject string. However, if + PCRE_DOTALL is not set, PCRE cannot make this optimization, + because the . metacharacter does not then match a newline, + and if the subject string contains newlines, the pattern may + match from the character immediately following one of them + instead of from the very start. For example, the pattern + + (.*) second + + matches the subject "first\nand second" (where \n stands for + a newline character) with the first captured substring being + "and". In order to do this, PCRE has to retry the match + starting after every newline in the subject. + + If you are using such a pattern with subject strings that do + not contain newlines, the best performance is obtained by + setting PCRE_DOTALL, or starting the pattern with ^.* to + indicate explicit anchoring. That saves PCRE from having to + scan along the subject looking for a newline to restart at. + + Beware of patterns that contain nested indefinite repeats. + These can take a long time to run when applied to a string + that does not match. Consider the pattern fragment + + (a+)* + + This can match "aaaa" in 33 different ways, and this number + increases very rapidly as the string gets longer. (The * + repeat can match 0, 1, 2, 3, or 4 times, and for each of + those cases other than 0, the + repeats can match different + numbers of times.) When the remainder of the pattern is such + that the entire match is going to fail, PCRE has in princi- + ple to try every possible variation, and this can take an + extremely long time. + + An optimization catches some of the more simple cases such + as + + (a+)*b + + where a literal character follows. Before embarking on the + standard matching procedure, PCRE checks that there is a "b" + later in the subject string, and if there is not, it fails + the match immediately. However, when there is no following + literal this optimization cannot be used. You can see the + difference by comparing the behaviour of + + (a+)*\d + + with the pattern above. The former gives a failure almost + instantly when applied to a whole line of "a" characters, + whereas the latter takes an appreciable time with strings + longer than about 20 characters. + + + + +AUTHOR + Philip Hazel <ph10@cam.ac.uk> + University Computing Service, + New Museums Site, + Cambridge CB2 3QG, England. + Phone: +44 1223 334714 + + Last updated: 15 August 2001 + Copyright (c) 1997-2001 University of Cambridge. |