/[pcre]/code/trunk/doc/pcrepattern.3
ViewVC logotype

Contents of /code/trunk/doc/pcrepattern.3

Parent Directory Parent Directory | Revision Log Revision Log


Revision 73 - (hide annotations) (download)
Sat Feb 24 21:40:30 2007 UTC (7 years, 7 months ago) by nigel
File size: 55268 byte(s)
Load pcre-4.5 into code/trunk.

1 nigel 63 .TH PCRE 3
2     .SH NAME
3     PCRE - Perl-compatible regular expressions
4     .SH PCRE REGULAR EXPRESSION DETAILS
5     .rs
6     .sp
7     The syntax and semantics of the regular expressions supported by PCRE are
8     described below. Regular expressions are also described in the Perl
9     documentation and in a number of other books, some of which have copious
10     examples. Jeffrey Friedl's "Mastering Regular Expressions", published by
11     O'Reilly, covers them in great detail. The description here is intended as
12     reference documentation.
13    
14     The basic operation of PCRE is on strings of bytes. However, there is also
15     support for UTF-8 character strings. To use this support you must build PCRE to
16     include UTF-8 support, and then call \fBpcre_compile()\fR with the PCRE_UTF8
17     option. How this affects the pattern matching is mentioned in several places
18     below. There is also a summary of UTF-8 features in the
19     .\" HTML <a href="pcre.html#utf8support">
20     .\" </a>
21     section on UTF-8 support
22     .\"
23     in the main
24     .\" HREF
25     \fBpcre\fR
26     .\"
27     page.
28    
29     A regular expression is a pattern that is matched against a subject string from
30     left to right. Most characters stand for themselves in a pattern, and match the
31     corresponding characters in the subject. As a trivial example, the pattern
32    
33     The quick brown fox
34    
35     matches a portion of a subject string that is identical to itself. The power of
36     regular expressions comes from the ability to include alternatives and
37     repetitions in the pattern. These are encoded in the pattern by the use of
38     \fImeta-characters\fR, which do not stand for themselves but instead are
39     interpreted in some special way.
40    
41     There are two different sets of meta-characters: those that are recognized
42     anywhere in the pattern except within square brackets, and those that are
43     recognized in square brackets. Outside square brackets, the meta-characters are
44     as follows:
45    
46     \\ general escape character with several uses
47     ^ assert start of string (or line, in multiline mode)
48     $ assert end of string (or line, in multiline mode)
49     . match any character except newline (by default)
50     [ start character class definition
51     | start of alternative branch
52     ( start subpattern
53     ) end subpattern
54     ? extends the meaning of (
55     also 0 or 1 quantifier
56     also quantifier minimizer
57     * 0 or more quantifier
58     + 1 or more quantifier
59     also "possessive quantifier"
60     { start min/max quantifier
61    
62     Part of a pattern that is in square brackets is called a "character class". In
63     a character class the only meta-characters are:
64    
65     \\ general escape character
66     ^ negate the class, but only if the first character
67     - indicates character range
68     [ POSIX character class (only if followed by POSIX
69     syntax)
70     ] terminates the character class
71    
72     The following sections describe the use of each of the meta-characters.
73    
74     .SH BACKSLASH
75     .rs
76     .sp
77     The backslash character has several uses. Firstly, if it is followed by a
78     non-alphameric character, it takes away any special meaning that character may
79     have. This use of backslash as an escape character applies both inside and
80     outside character classes.
81    
82     For example, if you want to match a * character, you write \\* in the pattern.
83     This escaping action applies whether or not the following character would
84     otherwise be interpreted as a meta-character, so it is always safe to precede a
85     non-alphameric with backslash to specify that it stands for itself. In
86     particular, if you want to match a backslash, you write \\\\.
87    
88     If a pattern is compiled with the PCRE_EXTENDED option, whitespace in the
89     pattern (other than in a character class) and characters between a # outside
90     a character class and the next newline character are ignored. An escaping
91     backslash can be used to include a whitespace or # character as part of the
92     pattern.
93    
94     If you want to remove the special meaning from a sequence of characters, you
95     can do so by putting them between \\Q and \\E. This is different from Perl in
96     that $ and @ are handled as literals in \\Q...\\E sequences in PCRE, whereas in
97     Perl, $ and @ cause variable interpolation. Note the following examples:
98    
99     Pattern PCRE matches Perl matches
100    
101     \\Qabc$xyz\\E abc$xyz abc followed by the
102     contents of $xyz
103     \\Qabc\\$xyz\\E abc\\$xyz abc\\$xyz
104     \\Qabc\\E\\$\\Qxyz\\E abc$xyz abc$xyz
105    
106     The \\Q...\\E sequence is recognized both inside and outside character classes.
107    
108     A second use of backslash provides a way of encoding non-printing characters
109     in patterns in a visible manner. There is no restriction on the appearance of
110     non-printing characters, apart from the binary zero that terminates a pattern,
111     but when a pattern is being prepared by text editing, it is usually easier to
112     use one of the following escape sequences than the binary character it
113     represents:
114    
115     \\a alarm, that is, the BEL character (hex 07)
116     \\cx "control-x", where x is any character
117     \\e escape (hex 1B)
118     \\f formfeed (hex 0C)
119     \\n newline (hex 0A)
120     \\r carriage return (hex 0D)
121     \\t tab (hex 09)
122     \\ddd character with octal code ddd, or backreference
123     \\xhh character with hex code hh
124     \\x{hhh..} character with hex code hhh... (UTF-8 mode only)
125    
126     The precise effect of \\cx is as follows: if x is a lower case letter, it
127     is converted to upper case. Then bit 6 of the character (hex 40) is inverted.
128     Thus \\cz becomes hex 1A, but \\c{ becomes hex 3B, while \\c; becomes hex
129     7B.
130    
131     After \\x, from zero to two hexadecimal digits are read (letters can be in
132     upper or lower case). In UTF-8 mode, any number of hexadecimal digits may
133     appear between \\x{ and }, but the value of the character code must be less
134     than 2**31 (that is, the maximum hexadecimal value is 7FFFFFFF). If characters
135     other than hexadecimal digits appear between \\x{ and }, or if there is no
136     terminating }, this form of escape is not recognized. Instead, the initial
137     \\x will be interpreted as a basic hexadecimal escape, with no following
138     digits, giving a byte whose value is zero.
139    
140     Characters whose value is less than 256 can be defined by either of the two
141     syntaxes for \\x when PCRE is in UTF-8 mode. There is no difference in the
142     way they are handled. For example, \\xdc is exactly the same as \\x{dc}.
143    
144     After \\0 up to two further octal digits are read. In both cases, if there
145     are fewer than two digits, just those that are present are used. Thus the
146     sequence \\0\\x\\07 specifies two binary zeros followed by a BEL character
147     (code value 7). Make sure you supply two digits after the initial zero if the
148     character that follows is itself an octal digit.
149    
150     The handling of a backslash followed by a digit other than 0 is complicated.
151     Outside a character class, PCRE reads it and any following digits as a decimal
152     number. If the number is less than 10, or if there have been at least that many
153     previous capturing left parentheses in the expression, the entire sequence is
154     taken as a \fIback reference\fR. A description of how this works is given
155     later, following the discussion of parenthesized subpatterns.
156    
157     Inside a character class, or if the decimal number is greater than 9 and there
158     have not been that many capturing subpatterns, PCRE re-reads up to three octal
159     digits following the backslash, and generates a single byte from the least
160     significant 8 bits of the value. Any subsequent digits stand for themselves.
161     For example:
162    
163     \\040 is another way of writing a space
164     \\40 is the same, provided there are fewer than 40
165     previous capturing subpatterns
166     \\7 is always a back reference
167     \\11 might be a back reference, or another way of
168     writing a tab
169     \\011 is always a tab
170     \\0113 is a tab followed by the character "3"
171     \\113 might be a back reference, otherwise the
172     character with octal code 113
173     \\377 might be a back reference, otherwise
174     the byte consisting entirely of 1 bits
175     \\81 is either a back reference, or a binary zero
176     followed by the two characters "8" and "1"
177    
178     Note that octal values of 100 or greater must not be introduced by a leading
179     zero, because no more than three octal digits are ever read.
180    
181     All the sequences that define a single byte value or a single UTF-8 character
182     (in UTF-8 mode) can be used both inside and outside character classes. In
183     addition, inside a character class, the sequence \\b is interpreted as the
184     backspace character (hex 08). Outside a character class it has a different
185     meaning (see below).
186    
187     The third use of backslash is for specifying generic character types:
188    
189     \\d any decimal digit
190     \\D any character that is not a decimal digit
191     \\s any whitespace character
192     \\S any character that is not a whitespace character
193     \\w any "word" character
194     \\W any "non-word" character
195    
196     Each pair of escape sequences partitions the complete set of characters into
197     two disjoint sets. Any given character matches one, and only one, of each pair.
198    
199     In UTF-8 mode, characters with values greater than 255 never match \\d, \\s, or
200     \\w, and always match \\D, \\S, and \\W.
201    
202     For compatibility with Perl, \\s does not match the VT character (code 11).
203     This makes it different from the the POSIX "space" class. The \\s characters
204     are HT (9), LF (10), FF (12), CR (13), and space (32).
205    
206     A "word" character is any letter or digit or the underscore character, that is,
207     any character which can be part of a Perl "word". The definition of letters and
208     digits is controlled by PCRE's character tables, and may vary if locale-
209     specific matching is taking place (see
210     .\" HTML <a href="pcreapi.html#localesupport">
211     .\" </a>
212     "Locale support"
213     .\"
214     in the
215     .\" HREF
216     \fBpcreapi\fR
217     .\"
218     page). For example, in the "fr" (French) locale, some character codes greater
219     than 128 are used for accented letters, and these are matched by \\w.
220    
221     These character type sequences can appear both inside and outside character
222     classes. They each match one character of the appropriate type. If the current
223     matching point is at the end of the subject string, all of them fail, since
224     there is no character to match.
225    
226     The fourth use of backslash is for certain simple assertions. An assertion
227     specifies a condition that has to be met at a particular point in a match,
228     without consuming any characters from the subject string. The use of
229     subpatterns for more complicated assertions is described below. The backslashed
230     assertions are
231    
232     \\b matches at a word boundary
233     \\B matches when not at a word boundary
234     \\A matches at start of subject
235     \\Z matches at end of subject or before newline at end
236     \\z matches at end of subject
237     \\G matches at first matching position in subject
238    
239     These assertions may not appear in character classes (but note that \\b has a
240     different meaning, namely the backspace character, inside a character class).
241    
242     A word boundary is a position in the subject string where the current character
243     and the previous character do not both match \\w or \\W (i.e. one matches
244     \\w and the other matches \\W), or the start or end of the string if the
245     first or last character matches \\w, respectively.
246    
247     The \\A, \\Z, and \\z assertions differ from the traditional circumflex and
248     dollar (described below) in that they only ever match at the very start and end
249     of the subject string, whatever options are set. Thus, they are independent of
250     multiline mode.
251    
252     They are not affected by the PCRE_NOTBOL or PCRE_NOTEOL options. If the
253     \fIstartoffset\fR argument of \fBpcre_exec()\fR is non-zero, indicating that
254     matching is to start at a point other than the beginning of the subject, \\A
255     can never match. The difference between \\Z and \\z is that \\Z matches before
256     a newline that is the last character of the string as well as at the end of the
257     string, whereas \\z matches only at the end.
258    
259     The \\G assertion is true only when the current matching position is at the
260     start point of the match, as specified by the \fIstartoffset\fR argument of
261     \fBpcre_exec()\fR. It differs from \\A when the value of \fIstartoffset\fR is
262     non-zero. By calling \fBpcre_exec()\fR multiple times with appropriate
263     arguments, you can mimic Perl's /g option, and it is in this kind of
264     implementation where \\G can be useful.
265    
266     Note, however, that PCRE's interpretation of \\G, as the start of the current
267     match, is subtly different from Perl's, which defines it as the end of the
268     previous match. In Perl, these can be different when the previously matched
269     string was empty. Because PCRE does just one match at a time, it cannot
270     reproduce this behaviour.
271    
272     If all the alternatives of a pattern begin with \\G, the expression is anchored
273     to the starting match position, and the "anchored" flag is set in the compiled
274     regular expression.
275    
276     .SH CIRCUMFLEX AND DOLLAR
277     .rs
278     .sp
279     Outside a character class, in the default matching mode, the circumflex
280     character is an assertion which is true only if the current matching point is
281     at the start of the subject string. If the \fIstartoffset\fR argument of
282     \fBpcre_exec()\fR is non-zero, circumflex can never match if the PCRE_MULTILINE
283     option is unset. Inside a character class, circumflex has an entirely different
284     meaning (see below).
285    
286     Circumflex need not be the first character of the pattern if a number of
287     alternatives are involved, but it should be the first thing in each alternative
288     in which it appears if the pattern is ever to match that branch. If all
289     possible alternatives start with a circumflex, that is, if the pattern is
290     constrained to match only at the start of the subject, it is said to be an
291     "anchored" pattern. (There are also other constructs that can cause a pattern
292     to be anchored.)
293    
294     A dollar character is an assertion which is true only if the current matching
295     point is at the end of the subject string, or immediately before a newline
296     character that is the last character in the string (by default). Dollar need
297     not be the last character of the pattern if a number of alternatives are
298     involved, but it should be the last item in any branch in which it appears.
299     Dollar has no special meaning in a character class.
300    
301     The meaning of dollar can be changed so that it matches only at the very end of
302     the string, by setting the PCRE_DOLLAR_ENDONLY option at compile time. This
303     does not affect the \\Z assertion.
304    
305     The meanings of the circumflex and dollar characters are changed if the
306     PCRE_MULTILINE option is set. When this is the case, they match immediately
307     after and immediately before an internal newline character, respectively, in
308     addition to matching at the start and end of the subject string. For example,
309     the pattern /^abc$/ matches the subject string "def\\nabc" in multiline mode,
310     but not otherwise. Consequently, patterns that are anchored in single line mode
311     because all branches start with ^ are not anchored in multiline mode, and a
312     match for circumflex is possible when the \fIstartoffset\fR argument of
313     \fBpcre_exec()\fR is non-zero. The PCRE_DOLLAR_ENDONLY option is ignored if
314     PCRE_MULTILINE is set.
315    
316     Note that the sequences \\A, \\Z, and \\z can be used to match the start and
317     end of the subject in both modes, and if all branches of a pattern start with
318     \\A it is always anchored, whether PCRE_MULTILINE is set or not.
319    
320     .SH FULL STOP (PERIOD, DOT)
321     .rs
322     .sp
323     Outside a character class, a dot in the pattern matches any one character in
324     the subject, including a non-printing character, but not (by default) newline.
325     In UTF-8 mode, a dot matches any UTF-8 character, which might be more than one
326     byte long, except (by default) for newline. If the PCRE_DOTALL option is set,
327     dots match newlines as well. The handling of dot is entirely independent of the
328     handling of circumflex and dollar, the only relationship being that they both
329     involve newline characters. Dot has no special meaning in a character class.
330    
331     .SH MATCHING A SINGLE BYTE
332     .rs
333     .sp
334     Outside a character class, the escape sequence \\C matches any one byte, both
335     in and out of UTF-8 mode. Unlike a dot, it always matches a newline. The
336     feature is provided in Perl in order to match individual bytes in UTF-8 mode.
337     Because it breaks up UTF-8 characters into individual bytes, what remains in
338     the string may be a malformed UTF-8 string. For this reason it is best avoided.
339    
340     PCRE does not allow \\C to appear in lookbehind assertions (see below), because
341     in UTF-8 mode it makes it impossible to calculate the length of the lookbehind.
342    
343     .SH SQUARE BRACKETS
344     .rs
345     .sp
346     An opening square bracket introduces a character class, terminated by a closing
347     square bracket. A closing square bracket on its own is not special. If a
348     closing square bracket is required as a member of the class, it should be the
349     first data character in the class (after an initial circumflex, if present) or
350     escaped with a backslash.
351    
352     A character class matches a single character in the subject. In UTF-8 mode, the
353     character may occupy more than one byte. A matched character must be in the set
354     of characters defined by the class, unless the first character in the class
355     definition is a circumflex, in which case the subject character must not be in
356     the set defined by the class. If a circumflex is actually required as a member
357     of the class, ensure it is not the first character, or escape it with a
358     backslash.
359    
360     For example, the character class [aeiou] matches any lower case vowel, while
361     [^aeiou] matches any character that is not a lower case vowel. Note that a
362     circumflex is just a convenient notation for specifying the characters which
363     are in the class by enumerating those that are not. It is not an assertion: it
364     still consumes a character from the subject string, and fails if the current
365     pointer is at the end of the string.
366    
367     In UTF-8 mode, characters with values greater than 255 can be included in a
368     class as a literal string of bytes, or by using the \\x{ escaping mechanism.
369    
370     When caseless matching is set, any letters in a class represent both their
371     upper case and lower case versions, so for example, a caseless [aeiou] matches
372     "A" as well as "a", and a caseless [^aeiou] does not match "A", whereas a
373     caseful version would. PCRE does not support the concept of case for characters
374     with values greater than 255.
375    
376     The newline character is never treated in any special way in character classes,
377     whatever the setting of the PCRE_DOTALL or PCRE_MULTILINE options is. A class
378     such as [^a] will always match a newline.
379    
380     The minus (hyphen) character can be used to specify a range of characters in a
381     character class. For example, [d-m] matches any letter between d and m,
382     inclusive. If a minus character is required in a class, it must be escaped with
383     a backslash or appear in a position where it cannot be interpreted as
384     indicating a range, typically as the first or last character in the class.
385    
386     It is not possible to have the literal character "]" as the end character of a
387     range. A pattern such as [W-]46] is interpreted as a class of two characters
388     ("W" and "-") followed by a literal string "46]", so it would match "W46]" or
389     "-46]". However, if the "]" is escaped with a backslash it is interpreted as
390     the end of range, so [W-\\]46] is interpreted as a single class containing a
391     range followed by two separate characters. The octal or hexadecimal
392     representation of "]" can also be used to end a range.
393    
394     Ranges operate in the collating sequence of character values. They can also be
395     used for characters specified numerically, for example [\\000-\\037]. In UTF-8
396     mode, ranges can include characters whose values are greater than 255, for
397     example [\\x{100}-\\x{2ff}].
398    
399     If a range that includes letters is used when caseless matching is set, it
400     matches the letters in either case. For example, [W-c] is equivalent to
401     [][\\^_`wxyzabc], matched caselessly, and if character tables for the "fr"
402     locale are in use, [\\xc8-\\xcb] matches accented E characters in both cases.
403    
404     The character types \\d, \\D, \\s, \\S, \\w, and \\W may also appear in a
405     character class, and add the characters that they match to the class. For
406     example, [\\dABCDEF] matches any hexadecimal digit. A circumflex can
407     conveniently be used with the upper case character types to specify a more
408     restricted set of characters than the matching lower case type. For example,
409     the class [^\\W_] matches any letter or digit, but not underscore.
410    
411     All non-alphameric characters other than \\, -, ^ (at the start) and the
412     terminating ] are non-special in character classes, but it does no harm if they
413     are escaped.
414    
415     .SH POSIX CHARACTER CLASSES
416     .rs
417     .sp
418     Perl supports the POSIX notation for character classes, which uses names
419     enclosed by [: and :] within the enclosing square brackets. PCRE also supports
420     this notation. For example,
421    
422     [01[:alpha:]%]
423    
424     matches "0", "1", any alphabetic character, or "%". The supported class names
425     are
426    
427     alnum letters and digits
428     alpha letters
429     ascii character codes 0 - 127
430     blank space or tab only
431     cntrl control characters
432     digit decimal digits (same as \\d)
433     graph printing characters, excluding space
434     lower lower case letters
435     print printing characters, including space
436     punct printing characters, excluding letters and digits
437     space white space (not quite the same as \\s)
438     upper upper case letters
439     word "word" characters (same as \\w)
440     xdigit hexadecimal digits
441    
442     The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13), and
443     space (32). Notice that this list includes the VT character (code 11). This
444     makes "space" different to \\s, which does not include VT (for Perl
445     compatibility).
446    
447     The name "word" is a Perl extension, and "blank" is a GNU extension from Perl
448     5.8. Another Perl extension is negation, which is indicated by a ^ character
449     after the colon. For example,
450    
451     [12[:^digit:]]
452    
453     matches "1", "2", or any non-digit. PCRE (and Perl) also recognize the POSIX
454     syntax [.ch.] and [=ch=] where "ch" is a "collating element", but these are not
455     supported, and an error is given if they are encountered.
456    
457     In UTF-8 mode, characters with values greater than 255 do not match any of
458     the POSIX character classes.
459    
460     .SH VERTICAL BAR
461     .rs
462     .sp
463     Vertical bar characters are used to separate alternative patterns. For example,
464     the pattern
465    
466     gilbert|sullivan
467    
468     matches either "gilbert" or "sullivan". Any number of alternatives may appear,
469     and an empty alternative is permitted (matching the empty string).
470     The matching process tries each alternative in turn, from left to right,
471     and the first one that succeeds is used. If the alternatives are within a
472     subpattern (defined below), "succeeds" means matching the rest of the main
473     pattern as well as the alternative in the subpattern.
474    
475     .SH INTERNAL OPTION SETTING
476     .rs
477     .sp
478     The settings of the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and
479     PCRE_EXTENDED options can be changed from within the pattern by a sequence of
480     Perl option letters enclosed between "(?" and ")". The option letters are
481    
482     i for PCRE_CASELESS
483     m for PCRE_MULTILINE
484     s for PCRE_DOTALL
485     x for PCRE_EXTENDED
486    
487     For example, (?im) sets caseless, multiline matching. It is also possible to
488     unset these options by preceding the letter with a hyphen, and a combined
489     setting and unsetting such as (?im-sx), which sets PCRE_CASELESS and
490     PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED, is also
491     permitted. If a letter appears both before and after the hyphen, the option is
492     unset.
493    
494     When an option change occurs at top level (that is, not inside subpattern
495     parentheses), the change applies to the remainder of the pattern that follows.
496     If the change is placed right at the start of a pattern, PCRE extracts it into
497     the global options (and it will therefore show up in data extracted by the
498     \fBpcre_fullinfo()\fR function).
499    
500     An option change within a subpattern affects only that part of the current
501     pattern that follows it, so
502    
503     (a(?i)b)c
504    
505     matches abc and aBc and no other strings (assuming PCRE_CASELESS is not used).
506     By this means, options can be made to have different settings in different
507     parts of the pattern. Any changes made in one alternative do carry on
508     into subsequent branches within the same subpattern. For example,
509    
510     (a(?i)b|c)
511    
512     matches "ab", "aB", "c", and "C", even though when matching "C" the first
513     branch is abandoned before the option setting. This is because the effects of
514     option settings happen at compile time. There would be some very weird
515     behaviour otherwise.
516    
517     The PCRE-specific options PCRE_UNGREEDY and PCRE_EXTRA can be changed in the
518     same way as the Perl-compatible options by using the characters U and X
519     respectively. The (?X) flag setting is special in that it must always occur
520     earlier in the pattern than any of the additional features it turns on, even
521     when it is at top level. It is best put at the start.
522    
523     .SH SUBPATTERNS
524     .rs
525     .sp
526     Subpatterns are delimited by parentheses (round brackets), which can be nested.
527     Marking part of a pattern as a subpattern does two things:
528    
529     1. It localizes a set of alternatives. For example, the pattern
530    
531     cat(aract|erpillar|)
532    
533     matches one of the words "cat", "cataract", or "caterpillar". Without the
534     parentheses, it would match "cataract", "erpillar" or the empty string.
535    
536     2. It sets up the subpattern as a capturing subpattern (as defined above).
537     When the whole pattern matches, that portion of the subject string that matched
538     the subpattern is passed back to the caller via the \fIovector\fR argument of
539     \fBpcre_exec()\fR. Opening parentheses are counted from left to right (starting
540     from 1) to obtain the numbers of the capturing subpatterns.
541    
542     For example, if the string "the red king" is matched against the pattern
543    
544     the ((red|white) (king|queen))
545    
546     the captured substrings are "red king", "red", and "king", and are numbered 1,
547     2, and 3, respectively.
548    
549     The fact that plain parentheses fulfil two functions is not always helpful.
550     There are often times when a grouping subpattern is required without a
551     capturing requirement. If an opening parenthesis is followed by a question mark
552     and a colon, the subpattern does not do any capturing, and is not counted when
553     computing the number of any subsequent capturing subpatterns. For example, if
554     the string "the white queen" is matched against the pattern
555    
556     the ((?:red|white) (king|queen))
557    
558     the captured substrings are "white queen" and "queen", and are numbered 1 and
559     2. The maximum number of capturing subpatterns is 65535, and the maximum depth
560     of nesting of all subpatterns, both capturing and non-capturing, is 200.
561    
562     As a convenient shorthand, if any option settings are required at the start of
563     a non-capturing subpattern, the option letters may appear between the "?" and
564     the ":". Thus the two patterns
565    
566     (?i:saturday|sunday)
567     (?:(?i)saturday|sunday)
568    
569     match exactly the same set of strings. Because alternative branches are tried
570     from left to right, and options are not reset until the end of the subpattern
571     is reached, an option setting in one branch does affect subsequent branches, so
572     the above patterns match "SUNDAY" as well as "Saturday".
573    
574     .SH NAMED SUBPATTERNS
575     .rs
576     .sp
577     Identifying capturing parentheses by number is simple, but it can be very hard
578     to keep track of the numbers in complicated regular expressions. Furthermore,
579     if an expression is modified, the numbers may change. To help with the
580     difficulty, PCRE supports the naming of subpatterns, something that Perl does
581     not provide. The Python syntax (?P<name>...) is used. Names consist of
582     alphanumeric characters and underscores, and must be unique within a pattern.
583    
584     Named capturing parentheses are still allocated numbers as well as names. The
585     PCRE API provides function calls for extracting the name-to-number translation
586     table from a compiled pattern. For further details see the
587     .\" HREF
588     \fBpcreapi\fR
589     .\"
590     documentation.
591    
592     .SH REPETITION
593     .rs
594     .sp
595     Repetition is specified by quantifiers, which can follow any of the following
596     items:
597    
598     a literal data character
599     the . metacharacter
600     the \\C escape sequence
601     escapes such as \\d that match single characters
602     a character class
603     a back reference (see next section)
604     a parenthesized subpattern (unless it is an assertion)
605    
606     The general repetition quantifier specifies a minimum and maximum number of
607     permitted matches, by giving the two numbers in curly brackets (braces),
608     separated by a comma. The numbers must be less than 65536, and the first must
609     be less than or equal to the second. For example:
610    
611     z{2,4}
612    
613     matches "zz", "zzz", or "zzzz". A closing brace on its own is not a special
614     character. If the second number is omitted, but the comma is present, there is
615     no upper limit; if the second number and the comma are both omitted, the
616     quantifier specifies an exact number of required matches. Thus
617    
618     [aeiou]{3,}
619    
620     matches at least 3 successive vowels, but may match many more, while
621    
622     \\d{8}
623    
624     matches exactly 8 digits. An opening curly bracket that appears in a position
625     where a quantifier is not allowed, or one that does not match the syntax of a
626     quantifier, is taken as a literal character. For example, {,6} is not a
627     quantifier, but a literal string of four characters.
628    
629     In UTF-8 mode, quantifiers apply to UTF-8 characters rather than to individual
630     bytes. Thus, for example, \\x{100}{2} matches two UTF-8 characters, each of
631     which is represented by a two-byte sequence.
632    
633     The quantifier {0} is permitted, causing the expression to behave as if the
634     previous item and the quantifier were not present.
635    
636     For convenience (and historical compatibility) the three most common
637     quantifiers have single-character abbreviations:
638    
639     * is equivalent to {0,}
640     + is equivalent to {1,}
641     ? is equivalent to {0,1}
642    
643     It is possible to construct infinite loops by following a subpattern that can
644     match no characters with a quantifier that has no upper limit, for example:
645    
646     (a?)*
647    
648     Earlier versions of Perl and PCRE used to give an error at compile time for
649     such patterns. However, because there are cases where this can be useful, such
650     patterns are now accepted, but if any repetition of the subpattern does in fact
651     match no characters, the loop is forcibly broken.
652    
653     By default, the quantifiers are "greedy", that is, they match as much as
654     possible (up to the maximum number of permitted times), without causing the
655     rest of the pattern to fail. The classic example of where this gives problems
656     is in trying to match comments in C programs. These appear between the
657     sequences /* and */ and within the sequence, individual * and / characters may
658     appear. An attempt to match C comments by applying the pattern
659    
660     /\\*.*\\*/
661    
662     to the string
663    
664     /* first command */ not comment /* second comment */
665    
666     fails, because it matches the entire string owing to the greediness of the .*
667     item.
668    
669     However, if a quantifier is followed by a question mark, it ceases to be
670     greedy, and instead matches the minimum number of times possible, so the
671     pattern
672    
673     /\\*.*?\\*/
674    
675     does the right thing with the C comments. The meaning of the various
676     quantifiers is not otherwise changed, just the preferred number of matches.
677     Do not confuse this use of question mark with its use as a quantifier in its
678     own right. Because it has two uses, it can sometimes appear doubled, as in
679    
680     \\d??\\d
681    
682     which matches one digit by preference, but can match two if that is the only
683     way the rest of the pattern matches.
684    
685     If the PCRE_UNGREEDY option is set (an option which is not available in Perl),
686     the quantifiers are not greedy by default, but individual ones can be made
687     greedy by following them with a question mark. In other words, it inverts the
688     default behaviour.
689    
690     When a parenthesized subpattern is quantified with a minimum repeat count that
691     is greater than 1 or with a limited maximum, more store is required for the
692     compiled pattern, in proportion to the size of the minimum or maximum.
693    
694     If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equivalent
695     to Perl's /s) is set, thus allowing the . to match newlines, the pattern is
696     implicitly anchored, because whatever follows will be tried against every
697     character position in the subject string, so there is no point in retrying the
698     overall match at any position after the first. PCRE normally treats such a
699     pattern as though it were preceded by \\A.
700    
701     In cases where it is known that the subject string contains no newlines, it is
702     worth setting PCRE_DOTALL in order to obtain this optimization, or
703     alternatively using ^ to indicate anchoring explicitly.
704    
705     However, there is one situation where the optimization cannot be used. When .*
706     is inside capturing parentheses that are the subject of a backreference
707     elsewhere in the pattern, a match at the start may fail, and a later one
708     succeed. Consider, for example:
709    
710     (.*)abc\\1
711    
712     If the subject is "xyz123abc123" the match point is the fourth character. For
713     this reason, such a pattern is not implicitly anchored.
714    
715     When a capturing subpattern is repeated, the value captured is the substring
716     that matched the final iteration. For example, after
717    
718     (tweedle[dume]{3}\\s*)+
719    
720     has matched "tweedledum tweedledee" the value of the captured substring is
721     "tweedledee". However, if there are nested capturing subpatterns, the
722     corresponding captured values may have been set in previous iterations. For
723     example, after
724    
725     /(a|(b))+/
726    
727     matches "aba" the value of the second captured substring is "b".
728    
729     .SH ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS
730     .rs
731     .sp
732     With both maximizing and minimizing repetition, failure of what follows
733     normally causes the repeated item to be re-evaluated to see if a different
734     number of repeats allows the rest of the pattern to match. Sometimes it is
735     useful to prevent this, either to change the nature of the match, or to cause
736     it fail earlier than it otherwise might, when the author of the pattern knows
737     there is no point in carrying on.
738    
739     Consider, for example, the pattern \\d+foo when applied to the subject line
740    
741     123456bar
742    
743     After matching all 6 digits and then failing to match "foo", the normal
744     action of the matcher is to try again with only 5 digits matching the \\d+
745     item, and then with 4, and so on, before ultimately failing. "Atomic grouping"
746     (a term taken from Jeffrey Friedl's book) provides the means for specifying
747     that once a subpattern has matched, it is not to be re-evaluated in this way.
748    
749     If we use atomic grouping for the previous example, the matcher would give up
750     immediately on failing to match "foo" the first time. The notation is a kind of
751     special parenthesis, starting with (?> as in this example:
752    
753 nigel 73 (?>\\d+)foo
754 nigel 63
755     This kind of parenthesis "locks up" the part of the pattern it contains once
756     it has matched, and a failure further into the pattern is prevented from
757     backtracking into it. Backtracking past it to previous items, however, works as
758     normal.
759    
760     An alternative description is that a subpattern of this type matches the string
761     of characters that an identical standalone pattern would match, if anchored at
762     the current point in the subject string.
763    
764     Atomic grouping subpatterns are not capturing subpatterns. Simple cases such as
765     the above example can be thought of as a maximizing repeat that must swallow
766     everything it can. So, while both \\d+ and \\d+? are prepared to adjust the
767     number of digits they match in order to make the rest of the pattern match,
768     (?>\\d+) can only match an entire sequence of digits.
769    
770     Atomic groups in general can of course contain arbitrarily complicated
771     subpatterns, and can be nested. However, when the subpattern for an atomic
772     group is just a single repeated item, as in the example above, a simpler
773     notation, called a "possessive quantifier" can be used. This consists of an
774     additional + character following a quantifier. Using this notation, the
775     previous example can be rewritten as
776    
777     \\d++bar
778    
779     Possessive quantifiers are always greedy; the setting of the PCRE_UNGREEDY
780     option is ignored. They are a convenient notation for the simpler forms of
781     atomic group. However, there is no difference in the meaning or processing of a
782     possessive quantifier and the equivalent atomic group.
783    
784     The possessive quantifier syntax is an extension to the Perl syntax. It
785     originates in Sun's Java package.
786    
787     When a pattern contains an unlimited repeat inside a subpattern that can itself
788     be repeated an unlimited number of times, the use of an atomic group is the
789     only way to avoid some failing matches taking a very long time indeed. The
790     pattern
791    
792     (\\D+|<\\d+>)*[!?]
793    
794     matches an unlimited number of substrings that either consist of non-digits, or
795     digits enclosed in <>, followed by either ! or ?. When it matches, it runs
796     quickly. However, if it is applied to
797    
798     aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
799    
800     it takes a long time before reporting failure. This is because the string can
801     be divided between the two repeats in a large number of ways, and all have to
802     be tried. (The example used [!?] rather than a single character at the end,
803     because both PCRE and Perl have an optimization that allows for fast failure
804     when a single character is used. They remember the last single character that
805     is required for a match, and fail early if it is not present in the string.)
806     If the pattern is changed to
807    
808     ((?>\\D+)|<\\d+>)*[!?]
809    
810     sequences of non-digits cannot be broken, and failure happens quickly.
811    
812     .SH BACK REFERENCES
813     .rs
814     .sp
815     Outside a character class, a backslash followed by a digit greater than 0 (and
816     possibly further digits) is a back reference to a capturing subpattern earlier
817     (that is, to its left) in the pattern, provided there have been that many
818     previous capturing left parentheses.
819    
820     However, if the decimal number following the backslash is less than 10, it is
821     always taken as a back reference, and causes an error only if there are not
822     that many capturing left parentheses in the entire pattern. In other words, the
823     parentheses that are referenced need not be to the left of the reference for
824     numbers less than 10. See the section entitled "Backslash" above for further
825     details of the handling of digits following a backslash.
826    
827     A back reference matches whatever actually matched the capturing subpattern in
828     the current subject string, rather than anything matching the subpattern
829     itself (see
830     .\" HTML <a href="#subpatternsassubroutines">
831     .\" </a>
832     "Subpatterns as subroutines"
833     .\"
834     below for a way of doing that). So the pattern
835    
836     (sens|respons)e and \\1ibility
837    
838     matches "sense and sensibility" and "response and responsibility", but not
839     "sense and responsibility". If caseful matching is in force at the time of the
840     back reference, the case of letters is relevant. For example,
841    
842     ((?i)rah)\\s+\\1
843    
844     matches "rah rah" and "RAH RAH", but not "RAH rah", even though the original
845     capturing subpattern is matched caselessly.
846    
847     Back references to named subpatterns use the Python syntax (?P=name). We could
848     rewrite the above example as follows:
849    
850     (?<p1>(?i)rah)\\s+(?P=p1)
851    
852     There may be more than one back reference to the same subpattern. If a
853     subpattern has not actually been used in a particular match, any back
854     references to it always fail. For example, the pattern
855    
856     (a|(bc))\\2
857    
858     always fails if it starts to match "a" rather than "bc". Because there may be
859     many capturing parentheses in a pattern, all digits following the backslash are
860     taken as part of a potential back reference number. If the pattern continues
861     with a digit character, some delimiter must be used to terminate the back
862     reference. If the PCRE_EXTENDED option is set, this can be whitespace.
863     Otherwise an empty comment can be used.
864    
865     A back reference that occurs inside the parentheses to which it refers fails
866     when the subpattern is first used, so, for example, (a\\1) never matches.
867     However, such references can be useful inside repeated subpatterns. For
868     example, the pattern
869    
870     (a|b\\1)+
871    
872     matches any number of "a"s and also "aba", "ababbaa" etc. At each iteration of
873     the subpattern, the back reference matches the character string corresponding
874     to the previous iteration. In order for this to work, the pattern must be such
875     that the first iteration does not need to match the back reference. This can be
876     done using alternation, as in the example above, or by a quantifier with a
877     minimum of zero.
878    
879     .SH ASSERTIONS
880     .rs
881     .sp
882     An assertion is a test on the characters following or preceding the current
883     matching point that does not actually consume any characters. The simple
884     assertions coded as \\b, \\B, \\A, \\G, \\Z, \\z, ^ and $ are described above.
885     More complicated assertions are coded as subpatterns. There are two kinds:
886     those that look ahead of the current position in the subject string, and those
887     that look behind it.
888    
889     An assertion subpattern is matched in the normal way, except that it does not
890     cause the current matching position to be changed. Lookahead assertions start
891     with (?= for positive assertions and (?! for negative assertions. For example,
892    
893     \\w+(?=;)
894    
895     matches a word followed by a semicolon, but does not include the semicolon in
896     the match, and
897    
898     foo(?!bar)
899    
900     matches any occurrence of "foo" that is not followed by "bar". Note that the
901     apparently similar pattern
902    
903     (?!foo)bar
904    
905     does not find an occurrence of "bar" that is preceded by something other than
906     "foo"; it finds any occurrence of "bar" whatsoever, because the assertion
907     (?!foo) is always true when the next three characters are "bar". A
908     lookbehind assertion is needed to achieve this effect.
909    
910     If you want to force a matching failure at some point in a pattern, the most
911     convenient way to do it is with (?!) because an empty string always matches, so
912     an assertion that requires there not to be an empty string must always fail.
913    
914     Lookbehind assertions start with (?<= for positive assertions and (?<! for
915     negative assertions. For example,
916    
917     (?<!foo)bar
918    
919     does find an occurrence of "bar" that is not preceded by "foo". The contents of
920     a lookbehind assertion are restricted such that all the strings it matches must
921     have a fixed length. However, if there are several alternatives, they do not
922     all have to have the same fixed length. Thus
923    
924     (?<=bullock|donkey)
925    
926     is permitted, but
927    
928     (?<!dogs?|cats?)
929    
930     causes an error at compile time. Branches that match different length strings
931     are permitted only at the top level of a lookbehind assertion. This is an
932     extension compared with Perl (at least for 5.8), which requires all branches to
933     match the same length of string. An assertion such as
934    
935     (?<=ab(c|de))
936    
937     is not permitted, because its single top-level branch can match two different
938     lengths, but it is acceptable if rewritten to use two top-level branches:
939    
940     (?<=abc|abde)
941    
942     The implementation of lookbehind assertions is, for each alternative, to
943     temporarily move the current position back by the fixed width and then try to
944     match. If there are insufficient characters before the current position, the
945     match is deemed to fail.
946    
947     PCRE does not allow the \\C escape (which matches a single byte in UTF-8 mode)
948     to appear in lookbehind assertions, because it makes it impossible to calculate
949     the length of the lookbehind.
950    
951     Atomic groups can be used in conjunction with lookbehind assertions to specify
952     efficient matching at the end of the subject string. Consider a simple pattern
953     such as
954    
955     abcd$
956    
957     when applied to a long string that does not match. Because matching proceeds
958     from left to right, PCRE will look for each "a" in the subject and then see if
959     what follows matches the rest of the pattern. If the pattern is specified as
960    
961     ^.*abcd$
962    
963     the initial .* matches the entire string at first, but when this fails (because
964     there is no following "a"), it backtracks to match all but the last character,
965     then all but the last two characters, and so on. Once again the search for "a"
966     covers the entire string, from right to left, so we are no better off. However,
967     if the pattern is written as
968    
969     ^(?>.*)(?<=abcd)
970    
971     or, equivalently,
972    
973     ^.*+(?<=abcd)
974    
975     there can be no backtracking for the .* item; it can match only the entire
976     string. The subsequent lookbehind assertion does a single test on the last four
977     characters. If it fails, the match fails immediately. For long strings, this
978     approach makes a significant difference to the processing time.
979    
980     Several assertions (of any sort) may occur in succession. For example,
981    
982     (?<=\\d{3})(?<!999)foo
983    
984     matches "foo" preceded by three digits that are not "999". Notice that each of
985     the assertions is applied independently at the same point in the subject
986     string. First there is a check that the previous three characters are all
987     digits, and then there is a check that the same three characters are not "999".
988     This pattern does \fInot\fR match "foo" preceded by six characters, the first
989     of which are digits and the last three of which are not "999". For example, it
990     doesn't match "123abcfoo". A pattern to do that is
991    
992     (?<=\\d{3}...)(?<!999)foo
993    
994     This time the first assertion looks at the preceding six characters, checking
995     that the first three are digits, and then the second assertion checks that the
996     preceding three characters are not "999".
997    
998     Assertions can be nested in any combination. For example,
999    
1000     (?<=(?<!foo)bar)baz
1001    
1002     matches an occurrence of "baz" that is preceded by "bar" which in turn is not
1003     preceded by "foo", while
1004    
1005     (?<=\\d{3}(?!999)...)foo
1006    
1007     is another pattern which matches "foo" preceded by three digits and any three
1008     characters that are not "999".
1009    
1010     Assertion subpatterns are not capturing subpatterns, and may not be repeated,
1011     because it makes no sense to assert the same thing several times. If any kind
1012     of assertion contains capturing subpatterns within it, these are counted for
1013     the purposes of numbering the capturing subpatterns in the whole pattern.
1014     However, substring capturing is carried out only for positive assertions,
1015     because it does not make sense for negative assertions.
1016    
1017     .SH CONDITIONAL SUBPATTERNS
1018     .rs
1019     .sp
1020     It is possible to cause the matching process to obey a subpattern
1021     conditionally or to choose between two alternative subpatterns, depending on
1022     the result of an assertion, or whether a previous capturing subpattern matched
1023     or not. The two possible forms of conditional subpattern are
1024    
1025     (?(condition)yes-pattern)
1026     (?(condition)yes-pattern|no-pattern)
1027    
1028     If the condition is satisfied, the yes-pattern is used; otherwise the
1029     no-pattern (if present) is used. If there are more than two alternatives in the
1030     subpattern, a compile-time error occurs.
1031    
1032     There are three kinds of condition. If the text between the parentheses
1033     consists of a sequence of digits, the condition is satisfied if the capturing
1034     subpattern of that number has previously matched. The number must be greater
1035     than zero. Consider the following pattern, which contains non-significant white
1036     space to make it more readable (assume the PCRE_EXTENDED option) and to divide
1037     it into three parts for ease of discussion:
1038    
1039     ( \\( )? [^()]+ (?(1) \\) )
1040    
1041     The first part matches an optional opening parenthesis, and if that
1042     character is present, sets it as the first captured substring. The second part
1043     matches one or more characters that are not parentheses. The third part is a
1044     conditional subpattern that tests whether the first set of parentheses matched
1045     or not. If they did, that is, if subject started with an opening parenthesis,
1046     the condition is true, and so the yes-pattern is executed and a closing
1047     parenthesis is required. Otherwise, since no-pattern is not present, the
1048     subpattern matches nothing. In other words, this pattern matches a sequence of
1049     non-parentheses, optionally enclosed in parentheses.
1050    
1051     If the condition is the string (R), it is satisfied if a recursive call to the
1052     pattern or subpattern has been made. At "top level", the condition is false.
1053     This is a PCRE extension. Recursive patterns are described in the next section.
1054    
1055     If the condition is not a sequence of digits or (R), it must be an assertion.
1056     This may be a positive or negative lookahead or lookbehind assertion. Consider
1057     this pattern, again containing non-significant white space, and with the two
1058     alternatives on the second line:
1059    
1060     (?(?=[^a-z]*[a-z])
1061     \\d{2}-[a-z]{3}-\\d{2} | \\d{2}-\\d{2}-\\d{2} )
1062    
1063     The condition is a positive lookahead assertion that matches an optional
1064     sequence of non-letters followed by a letter. In other words, it tests for the
1065     presence of at least one letter in the subject. If a letter is found, the
1066     subject is matched against the first alternative; otherwise it is matched
1067     against the second. This pattern matches strings in one of the two forms
1068     dd-aaa-dd or dd-dd-dd, where aaa are letters and dd are digits.
1069    
1070     .SH COMMENTS
1071     .rs
1072     .sp
1073     The sequence (?# marks the start of a comment which continues up to the next
1074     closing parenthesis. Nested parentheses are not permitted. The characters
1075     that make up a comment play no part in the pattern matching at all.
1076    
1077     If the PCRE_EXTENDED option is set, an unescaped # character outside a
1078     character class introduces a comment that continues up to the next newline
1079     character in the pattern.
1080    
1081     .SH RECURSIVE PATTERNS
1082     .rs
1083     .sp
1084     Consider the problem of matching a string in parentheses, allowing for
1085     unlimited nested parentheses. Without the use of recursion, the best that can
1086     be done is to use a pattern that matches up to some fixed depth of nesting. It
1087     is not possible to handle an arbitrary nesting depth. Perl has provided an
1088     experimental facility that allows regular expressions to recurse (amongst other
1089     things). It does this by interpolating Perl code in the expression at run time,
1090     and the code can refer to the expression itself. A Perl pattern to solve the
1091     parentheses problem can be created like this:
1092    
1093     $re = qr{\\( (?: (?>[^()]+) | (?p{$re}) )* \\)}x;
1094    
1095     The (?p{...}) item interpolates Perl code at run time, and in this case refers
1096     recursively to the pattern in which it appears. Obviously, PCRE cannot support
1097     the interpolation of Perl code. Instead, it supports some special syntax for
1098     recursion of the entire pattern, and also for individual subpattern recursion.
1099    
1100     The special item that consists of (? followed by a number greater than zero and
1101     a closing parenthesis is a recursive call of the subpattern of the given
1102     number, provided that it occurs inside that subpattern. (If not, it is a
1103     "subroutine" call, which is described in the next section.) The special item
1104     (?R) is a recursive call of the entire regular expression.
1105    
1106     For example, this PCRE pattern solves the nested parentheses problem (assume
1107     the PCRE_EXTENDED option is set so that white space is ignored):
1108    
1109     \\( ( (?>[^()]+) | (?R) )* \\)
1110    
1111     First it matches an opening parenthesis. Then it matches any number of
1112     substrings which can either be a sequence of non-parentheses, or a recursive
1113     match of the pattern itself (that is a correctly parenthesized substring).
1114     Finally there is a closing parenthesis.
1115    
1116     If this were part of a larger pattern, you would not want to recurse the entire
1117     pattern, so instead you could use this:
1118    
1119     ( \\( ( (?>[^()]+) | (?1) )* \\) )
1120    
1121     We have put the pattern into parentheses, and caused the recursion to refer to
1122     them instead of the whole pattern. In a larger pattern, keeping track of
1123     parenthesis numbers can be tricky. It may be more convenient to use named
1124     parentheses instead. For this, PCRE uses (?P>name), which is an extension to
1125     the Python syntax that PCRE uses for named parentheses (Perl does not provide
1126     named parentheses). We could rewrite the above example as follows:
1127    
1128 nigel 73 (?P<pn> \\( ( (?>[^()]+) | (?P>pn) )* \\) )
1129 nigel 63
1130     This particular example pattern contains nested unlimited repeats, and so the
1131     use of atomic grouping for matching strings of non-parentheses is important
1132     when applying the pattern to strings that do not match. For example, when this
1133     pattern is applied to
1134    
1135     (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa()
1136    
1137     it yields "no match" quickly. However, if atomic grouping is not used,
1138     the match runs for a very long time indeed because there are so many different
1139     ways the + and * repeats can carve up the subject, and all have to be tested
1140     before failure can be reported.
1141    
1142     At the end of a match, the values set for any capturing subpatterns are those
1143     from the outermost level of the recursion at which the subpattern value is set.
1144     If you want to obtain intermediate values, a callout function can be used (see
1145     below and the
1146     .\" HREF
1147     \fBpcrecallout\fR
1148     .\"
1149     documentation). If the pattern above is matched against
1150    
1151     (ab(cd)ef)
1152    
1153     the value for the capturing parentheses is "ef", which is the last value taken
1154     on at the top level. If additional parentheses are added, giving
1155    
1156     \\( ( ( (?>[^()]+) | (?R) )* ) \\)
1157     ^ ^
1158     ^ ^
1159    
1160     the string they capture is "ab(cd)ef", the contents of the top level
1161     parentheses. If there are more than 15 capturing parentheses in a pattern, PCRE
1162     has to obtain extra memory to store data during a recursion, which it does by
1163     using \fBpcre_malloc\fR, freeing it via \fBpcre_free\fR afterwards. If no
1164     memory can be obtained, the match fails with the PCRE_ERROR_NOMEMORY error.
1165    
1166     Do not confuse the (?R) item with the condition (R), which tests for recursion.
1167     Consider this pattern, which matches text in angle brackets, allowing for
1168     arbitrary nesting. Only digits are allowed in nested brackets (that is, when
1169     recursing), whereas any characters are permitted at the outer level.
1170    
1171     < (?: (?(R) \\d++ | [^<>]*+) | (?R)) * >
1172    
1173     In this pattern, (?(R) is the start of a conditional subpattern, with two
1174     different alternatives for the recursive and non-recursive cases. The (?R) item
1175     is the actual recursive call.
1176    
1177     .\" HTML <a name="subpatternsassubroutines"></a>
1178     .SH SUBPATTERNS AS SUBROUTINES
1179     .rs
1180     .sp
1181     If the syntax for a recursive subpattern reference (either by number or by
1182     name) is used outside the parentheses to which it refers, it operates like a
1183     subroutine in a programming language. An earlier example pointed out that the
1184     pattern
1185    
1186     (sens|respons)e and \\1ibility
1187    
1188     matches "sense and sensibility" and "response and responsibility", but not
1189     "sense and responsibility". If instead the pattern
1190    
1191     (sens|respons)e and (?1)ibility
1192    
1193     is used, it does match "sense and responsibility" as well as the other two
1194     strings. Such references must, however, follow the subpattern to which they
1195     refer.
1196    
1197     .SH CALLOUTS
1198     .rs
1199     .sp
1200     Perl has a feature whereby using the sequence (?{...}) causes arbitrary Perl
1201     code to be obeyed in the middle of matching a regular expression. This makes it
1202     possible, amongst other things, to extract different substrings that match the
1203     same pair of parentheses when there is a repetition.
1204    
1205     PCRE provides a similar feature, but of course it cannot obey arbitrary Perl
1206     code. The feature is called "callout". The caller of PCRE provides an external
1207     function by putting its entry point in the global variable \fIpcre_callout\fR.
1208     By default, this variable contains NULL, which disables all calling out.
1209    
1210     Within a regular expression, (?C) indicates the points at which the external
1211     function is to be called. If you want to identify different callout points, you
1212     can put a number less than 256 after the letter C. The default value is zero.
1213     For example, this pattern has two callout points:
1214    
1215     (?C1)\dabc(?C2)def
1216    
1217     During matching, when PCRE reaches a callout point (and \fIpcre_callout\fR is
1218     set), the external function is called. It is provided with the number of the
1219     callout, and, optionally, one item of data originally supplied by the caller of
1220     \fBpcre_exec()\fR. The callout function may cause matching to backtrack, or to
1221     fail altogether. A complete description of the interface to the callout
1222     function is given in the
1223     .\" HREF
1224     \fBpcrecallout\fR
1225     .\"
1226     documentation.
1227    
1228     .in 0
1229     Last updated: 03 February 2003
1230     .br
1231     Copyright (c) 1997-2003 University of Cambridge.

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12