This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Revert part of #31591
[perl5.git] / pod / perlre.pod
CommitLineData
a0d0e21e 1=head1 NAME
d74e8afc 2X<regular expression> X<regex> X<regexp>
a0d0e21e
LW
3
4perlre - Perl regular expressions
5
6=head1 DESCRIPTION
7
5d458dd8 8This page describes the syntax of regular expressions in Perl.
91e0c79e 9
cc46d5f2 10If you haven't used regular expressions before, a quick-start
91e0c79e
MJD
11introduction is available in L<perlrequick>, and a longer tutorial
12introduction is available in L<perlretut>.
13
14For reference on how regular expressions are used in matching
15operations, plus various examples of the same, see discussions of
16C<m//>, C<s///>, C<qr//> and C<??> in L<perlop/"Regexp Quote-Like
17Operators">.
cb1a09d0 18
0d017f4d
WL
19
20=head2 Modifiers
21
19799a22 22Matching operations can have various modifiers. Modifiers
5a964f20 23that relate to the interpretation of the regular expression inside
19799a22 24are listed below. Modifiers that alter the way a regular expression
5d458dd8 25is used by Perl are detailed in L<perlop/"Regexp Quote-Like Operators"> and
1e66bd83 26L<perlop/"Gory details of parsing quoted constructs">.
a0d0e21e 27
55497cff
PP
28=over 4
29
54310121 30=item m
d74e8afc 31X</m> X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
55497cff
PP
32
33Treat string as multiple lines. That is, change "^" and "$" from matching
14218588 34the start or end of the string to matching the start or end of any
7f761169 35line anywhere within the string.
55497cff 36
54310121 37=item s
d74e8afc
ITB
38X</s> X<regex, single-line> X<regexp, single-line>
39X<regular expression, single-line>
55497cff
PP
40
41Treat string as single line. That is, change "." to match any character
19799a22 42whatsoever, even a newline, which normally it would not match.
55497cff 43
f02c194e 44Used together, as /ms, they let the "." match any character whatsoever,
fb55449c 45while still allowing "^" and "$" to match, respectively, just after
19799a22 46and just before newlines within the string.
7b8d334a 47
87e95b7f
YO
48=item i
49X</i> X<regex, case-insensitive> X<regexp, case-insensitive>
50X<regular expression, case-insensitive>
51
52Do case-insensitive pattern matching.
53
54If C<use locale> is in effect, the case map is taken from the current
55locale. See L<perllocale>.
56
54310121 57=item x
d74e8afc 58X</x>
55497cff
PP
59
60Extend your pattern's legibility by permitting whitespace and comments.
61
87e95b7f
YO
62=item p
63X</p> X<regex, preserve> X<regexp, preserve>
64
65Preserve the string matched such that ${^PREMATCH}, {$^MATCH}, and
66${^POSTMATCH} are available for use after matching.
67
55497cff 68=back
a0d0e21e
LW
69
70These are usually written as "the C</x> modifier", even though the delimiter
14218588 71in question might not really be a slash. Any of these
a0d0e21e 72modifiers may also be embedded within the regular expression itself using
14218588 73the C<(?...)> construct. See below.
a0d0e21e 74
4633a7c4 75The C</x> modifier itself needs a little more explanation. It tells
55497cff
PP
76the regular expression parser to ignore whitespace that is neither
77backslashed nor within a character class. You can use this to break up
4633a7c4 78your regular expression into (slightly) more readable parts. The C<#>
54310121 79character is also treated as a metacharacter introducing a comment,
55497cff 80just as in ordinary Perl code. This also means that if you want real
14218588 81whitespace or C<#> characters in the pattern (outside a character
f9a3ff1a
RGS
82class, where they are unaffected by C</x>), then you'll either have to
83escape them (using backslashes or C<\Q...\E>) or encode them using octal
8933a740
RGS
84or hex escapes. Taken together, these features go a long way towards
85making Perl's regular expressions more readable. Note that you have to
86be careful not to include the pattern delimiter in the comment--perl has
87no way of knowing you did not intend to close the pattern early. See
88the C-comment deletion code in L<perlop>. Also note that anything inside
1031e5db 89a C<\Q...\E> stays unaffected by C</x>.
d74e8afc 90X</x>
a0d0e21e
LW
91
92=head2 Regular Expressions
93
04838cea
RGS
94=head3 Metacharacters
95
0d017f4d 96The patterns used in Perl pattern matching evolved from the ones supplied in
14218588 97the Version 8 regex routines. (The routines are derived
19799a22
GS
98(distantly) from Henry Spencer's freely redistributable reimplementation
99of the V8 routines.) See L<Version 8 Regular Expressions> for
100details.
a0d0e21e
LW
101
102In particular the following metacharacters have their standard I<egrep>-ish
103meanings:
d74e8afc
ITB
104X<metacharacter>
105X<\> X<^> X<.> X<$> X<|> X<(> X<()> X<[> X<[]>
106
a0d0e21e 107
54310121 108 \ Quote the next metacharacter
a0d0e21e
LW
109 ^ Match the beginning of the line
110 . Match any character (except newline)
c07a80fd 111 $ Match the end of the line (or before newline at the end)
a0d0e21e
LW
112 | Alternation
113 () Grouping
114 [] Character class
115
14218588
GS
116By default, the "^" character is guaranteed to match only the
117beginning of the string, the "$" character only the end (or before the
118newline at the end), and Perl does certain optimizations with the
a0d0e21e
LW
119assumption that the string contains only one line. Embedded newlines
120will not be matched by "^" or "$". You may, however, wish to treat a
4a6725af 121string as a multi-line buffer, such that the "^" will match after any
0d520e8e
YO
122newline within the string (except if the newline is the last character in
123the string), and "$" will match before any newline. At the
a0d0e21e
LW
124cost of a little more overhead, you can do this by using the /m modifier
125on the pattern match operator. (Older programs did this by setting C<$*>,
f02c194e 126but this practice has been removed in perl 5.9.)
d74e8afc 127X<^> X<$> X</m>
a0d0e21e 128
14218588 129To simplify multi-line substitutions, the "." character never matches a
55497cff 130newline unless you use the C</s> modifier, which in effect tells Perl to pretend
f02c194e 131the string is a single line--even if it isn't.
d74e8afc 132X<.> X</s>
a0d0e21e 133
04838cea
RGS
134=head3 Quantifiers
135
a0d0e21e 136The following standard quantifiers are recognized:
d74e8afc 137X<metacharacter> X<quantifier> X<*> X<+> X<?> X<{n}> X<{n,}> X<{n,m}>
a0d0e21e
LW
138
139 * Match 0 or more times
140 + Match 1 or more times
141 ? Match 1 or 0 times
142 {n} Match exactly n times
143 {n,} Match at least n times
144 {n,m} Match at least n but not more than m times
145
146(If a curly bracket occurs in any other context, it is treated
b975c076 147as a regular character. In particular, the lower bound
527e91da
BB
148is not optional.) The "*" quantifier is equivalent to C<{0,}>, the "+"
149quantifier to C<{1,}>, and the "?" quantifier to C<{0,1}>. n and m are limited
9c79236d
GS
150to integral values less than a preset limit defined when perl is built.
151This is usually 32766 on the most common platforms. The actual limit can
152be seen in the error message generated by code such as this:
153
820475bd 154 $_ **= $_ , / {$_} / for 2 .. 42;
a0d0e21e 155
54310121
PP
156By default, a quantified subpattern is "greedy", that is, it will match as
157many times as possible (given a particular starting location) while still
158allowing the rest of the pattern to match. If you want it to match the
159minimum number of times possible, follow the quantifier with a "?". Note
160that the meanings don't change, just the "greediness":
0d017f4d 161X<metacharacter> X<greedy> X<greediness>
d74e8afc 162X<?> X<*?> X<+?> X<??> X<{n}?> X<{n,}?> X<{n,m}?>
a0d0e21e 163
0d017f4d
WL
164 *? Match 0 or more times, not greedily
165 +? Match 1 or more times, not greedily
166 ?? Match 0 or 1 time, not greedily
167 {n}? Match exactly n times, not greedily
168 {n,}? Match at least n times, not greedily
169 {n,m}? Match at least n but not more than m times, not greedily
a0d0e21e 170
b9b4dddf
YO
171By default, when a quantified subpattern does not allow the rest of the
172overall pattern to match, Perl will backtrack. However, this behaviour is
0d017f4d 173sometimes undesirable. Thus Perl provides the "possessive" quantifier form
b9b4dddf
YO
174as well.
175
0d017f4d
WL
176 *+ Match 0 or more times and give nothing back
177 ++ Match 1 or more times and give nothing back
178 ?+ Match 0 or 1 time and give nothing back
b9b4dddf 179 {n}+ Match exactly n times and give nothing back (redundant)
04838cea
RGS
180 {n,}+ Match at least n times and give nothing back
181 {n,m}+ Match at least n but not more than m times and give nothing back
b9b4dddf
YO
182
183For instance,
184
185 'aaaa' =~ /a++a/
186
187will never match, as the C<a++> will gobble up all the C<a>'s in the
188string and won't leave any for the remaining part of the pattern. This
189feature can be extremely useful to give perl hints about where it
190shouldn't backtrack. For instance, the typical "match a double-quoted
191string" problem can be most efficiently performed when written as:
192
193 /"(?:[^"\\]++|\\.)*+"/
194
0d017f4d 195as we know that if the final quote does not match, backtracking will not
b9b4dddf
YO
196help. See the independent subexpression C<< (?>...) >> for more details;
197possessive quantifiers are just syntactic sugar for that construct. For
198instance the above example could also be written as follows:
199
200 /"(?>(?:(?>[^"\\]+)|\\.)*)"/
201
04838cea
RGS
202=head3 Escape sequences
203
5f05dabc 204Because patterns are processed as double quoted strings, the following
a0d0e21e 205also work:
0d017f4d 206X<\t> X<\n> X<\r> X<\f> X<\e> X<\a> X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q>
d74e8afc 207X<\0> X<\c> X<\N> X<\x>
a0d0e21e 208
0f36ee90
PP
209 \t tab (HT, TAB)
210 \n newline (LF, NL)
211 \r return (CR)
212 \f form feed (FF)
213 \a alarm (bell) (BEL)
214 \e escape (think troff) (ESC)
0d017f4d
WL
215 \033 octal char (example: ESC)
216 \x1B hex char (example: ESC)
217 \x{263a} wide hex char (example: Unicode SMILEY)
218 \cK control char (example: VT)
4a2d328f 219 \N{name} named char
cb1a09d0
AD
220 \l lowercase next char (think vi)
221 \u uppercase next char (think vi)
222 \L lowercase till \E (think vi)
223 \U uppercase till \E (think vi)
224 \E end case modification (think vi)
5a964f20 225 \Q quote (disable) pattern metacharacters till \E
a0d0e21e 226
a034a98d 227If C<use locale> is in effect, the case map used by C<\l>, C<\L>, C<\u>
423cee85 228and C<\U> is taken from the current locale. See L<perllocale>. For
4a2d328f 229documentation of C<\N{name}>, see L<charnames>.
a034a98d 230
1d2dff63
GS
231You cannot include a literal C<$> or C<@> within a C<\Q> sequence.
232An unescaped C<$> or C<@> interpolates the corresponding variable,
233while escaping will cause the literal string C<\$> to be matched.
234You'll need to write something like C<m/\Quser\E\@\Qhost/>.
235
e1d1eefb 236=head3 Character Classes and other Special Escapes
04838cea 237
a0d0e21e 238In addition, Perl defines the following:
d74e8afc 239X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\X> X<\p> X<\P> X<\C>
f7819f85 240X<\g> X<\k> X<\N> X<\K> X<\v> X<\V> X<\h> X<\H>
0d017f4d 241X<word> X<whitespace> X<character class> X<backreference>
a0d0e21e 242
81714fb9
YO
243 \w Match a "word" character (alphanumeric plus "_")
244 \W Match a non-"word" character
245 \s Match a whitespace character
246 \S Match a non-whitespace character
247 \d Match a digit character
248 \D Match a non-digit character
249 \pP Match P, named property. Use \p{Prop} for longer names.
250 \PP Match non-P
251 \X Match eXtended Unicode "combining character sequence",
252 equivalent to (?:\PM\pM*)
253 \C Match a single C char (octet) even under Unicode.
254 NOTE: breaks up characters into their UTF-8 bytes,
255 so you may end up with malformed pieces of UTF-8.
256 Unsupported in lookbehind.
5d458dd8 257 \1 Backreference to a specific group.
c74340f9 258 '1' may actually be any positive integer.
2bf803e2
YO
259 \g1 Backreference to a specific or previous group,
260 \g{-1} number may be negative indicating a previous buffer and may
261 optionally be wrapped in curly brackets for safer parsing.
1f1031fe 262 \g{name} Named backreference
81714fb9 263 \k<name> Named backreference
38a44b82 264 \N{name} Named Unicode character, or Unicode escape
81714fb9
YO
265 \x12 Hexadecimal escape sequence
266 \x{1234} Long hexadecimal escape sequence
ee9b8eae 267 \K Keep the stuff left of the \K, don't include it in $&
e1d1eefb
YO
268 \v Vertical whitespace
269 \V Not vertical whitespace
270 \h Horizontal whitespace
271 \H Not horizontal whitespace
2ddf2931 272 \R Linebreak
a0d0e21e 273
08ce8fc6
JH
274A C<\w> matches a single alphanumeric character (an alphabetic
275character, or a decimal digit) or C<_>, not a whole word. Use C<\w+>
276to match a string of Perl-identifier characters (which isn't the same
277as matching an English word). If C<use locale> is in effect, the list
278of alphabetic characters generated by C<\w> is taken from the current
279locale. See L<perllocale>. You may use C<\w>, C<\W>, C<\s>, C<\S>,
0d017f4d
WL
280C<\d>, and C<\D> within character classes, but they aren't usable
281as either end of a range. If any of them precedes or follows a "-",
282the "-" is understood literally. If Unicode is in effect, C<\s> matches
c62285ac 283also "\x{85}", "\x{2028}", and "\x{2029}". See L<perlunicode> for more
0d017f4d
WL
284details about C<\pP>, C<\PP>, C<\X> and the possibility of defining
285your own C<\p> and C<\P> properties, and L<perluniintro> about Unicode
286in general.
d74e8afc 287X<\w> X<\W> X<word>
a0d0e21e 288
e1d1eefb
YO
289C<\R> will atomically match a linebreak, including the network line-ending
290"\x0D\x0A". Specifically, X<\R> is exactly equivelent to
291
292 (?>\x0D\x0A?|[\x0A-\x0C\x85\x{2028}\x{2029}])
293
294B<Note:> C<\R> has no special meaning inside of a character class;
295use C<\v> instead (vertical whitespace).
296X<\R>
297
b8c5462f 298The POSIX character class syntax
d74e8afc 299X<character class>
b8c5462f 300
820475bd 301 [:class:]
b8c5462f 302
0d017f4d 303is also available. Note that the C<[> and C<]> brackets are I<literal>;
5496314a
SP
304they must always be used within a character class expression.
305
306 # this is correct:
307 $string =~ /[[:alpha:]]/;
308
309 # this is not, and will generate a warning:
310 $string =~ /[:alpha:]/;
311
312The available classes and their backslash equivalents (if available) are
313as follows:
d74e8afc
ITB
314X<character class>
315X<alpha> X<alnum> X<ascii> X<blank> X<cntrl> X<digit> X<graph>
316X<lower> X<print> X<punct> X<space> X<upper> X<word> X<xdigit>
b8c5462f
JH
317
318 alpha
319 alnum
320 ascii
aaa51d5e 321 blank [1]
b8c5462f
JH
322 cntrl
323 digit \d
324 graph
325 lower
326 print
327 punct
aaa51d5e 328 space \s [2]
b8c5462f 329 upper
aaa51d5e 330 word \w [3]
b8c5462f
JH
331 xdigit
332
07698885
RGS
333=over
334
335=item [1]
336
b432a672 337A GNU extension equivalent to C<[ \t]>, "all horizontal whitespace".
07698885
RGS
338
339=item [2]
340
341Not exactly equivalent to C<\s> since the C<[[:space:]]> includes
0d017f4d 342also the (very rare) "vertical tabulator", "\cK" or chr(11) in ASCII.
07698885
RGS
343
344=item [3]
345
08ce8fc6 346A Perl extension, see above.
07698885
RGS
347
348=back
aaa51d5e 349
26b44a0a 350For example use C<[:upper:]> to match all the uppercase characters.
aaa51d5e
JF
351Note that the C<[]> are part of the C<[::]> construct, not part of the
352whole character class. For example:
b8c5462f 353
820475bd 354 [01[:alpha:]%]
b8c5462f 355
0d017f4d 356matches zero, one, any alphabetic character, and the percent sign.
b8c5462f 357
72ff2908
JH
358The following equivalences to Unicode \p{} constructs and equivalent
359backslash character classes (if available), will hold:
d74e8afc 360X<character class> X<\p> X<\p{}>
72ff2908 361
5496314a 362 [[:...:]] \p{...} backslash
b8c5462f
JH
363
364 alpha IsAlpha
365 alnum IsAlnum
366 ascii IsASCII
0d017f4d 367 blank
b8c5462f 368 cntrl IsCntrl
3bec3564 369 digit IsDigit \d
b8c5462f
JH
370 graph IsGraph
371 lower IsLower
372 print IsPrint
373 punct IsPunct
374 space IsSpace
3bec3564 375 IsSpacePerl \s
b8c5462f
JH
376 upper IsUpper
377 word IsWord
378 xdigit IsXDigit
379
5496314a 380For example C<[[:lower:]]> and C<\p{IsLower}> are equivalent.
b8c5462f
JH
381
382If the C<utf8> pragma is not used but the C<locale> pragma is, the
aaa51d5e 383classes correlate with the usual isalpha(3) interface (except for
b432a672 384"word" and "blank").
b8c5462f
JH
385
386The assumedly non-obviously named classes are:
387
388=over 4
389
390=item cntrl
d74e8afc 391X<cntrl>
b8c5462f 392
820475bd
GS
393Any control character. Usually characters that don't produce output as
394such but instead control the terminal somehow: for example newline and
395backspace are control characters. All characters with ord() less than
0d017f4d 39632 are usually classified as control characters (assuming ASCII,
7be5a6cf
JF
397the ISO Latin character sets, and Unicode), as is the character with
398the ord() value of 127 (C<DEL>).
b8c5462f
JH
399
400=item graph
d74e8afc 401X<graph>
b8c5462f 402
f1cbbd6e 403Any alphanumeric or punctuation (special) character.
b8c5462f
JH
404
405=item print
d74e8afc 406X<print>
b8c5462f 407
f79b3095 408Any alphanumeric or punctuation (special) character or the space character.
b8c5462f
JH
409
410=item punct
d74e8afc 411X<punct>
b8c5462f 412
f1cbbd6e 413Any punctuation (special) character.
b8c5462f
JH
414
415=item xdigit
d74e8afc 416X<xdigit>
b8c5462f 417
593df60c 418Any hexadecimal digit. Though this may feel silly ([0-9A-Fa-f] would
820475bd 419work just fine) it is included for completeness.
b8c5462f 420
b8c5462f
JH
421=back
422
423You can negate the [::] character classes by prefixing the class name
424with a '^'. This is a Perl extension. For example:
d74e8afc 425X<character class, negation>
b8c5462f 426
5496314a 427 POSIX traditional Unicode
93733859 428
5496314a
SP
429 [[:^digit:]] \D \P{IsDigit}
430 [[:^space:]] \S \P{IsSpace}
431 [[:^word:]] \W \P{IsWord}
b8c5462f 432
54c18d04
MK
433Perl respects the POSIX standard in that POSIX character classes are
434only supported within a character class. The POSIX character classes
435[.cc.] and [=cc=] are recognized but B<not> supported and trying to
436use them will cause an error.
b8c5462f 437
04838cea
RGS
438=head3 Assertions
439
a0d0e21e 440Perl defines the following zero-width assertions:
d74e8afc
ITB
441X<zero-width assertion> X<assertion> X<regex, zero-width assertion>
442X<regexp, zero-width assertion>
443X<regular expression, zero-width assertion>
444X<\b> X<\B> X<\A> X<\Z> X<\z> X<\G>
a0d0e21e
LW
445
446 \b Match a word boundary
0d017f4d 447 \B Match except at a word boundary
b85d18e9
IZ
448 \A Match only at beginning of string
449 \Z Match only at end of string, or before newline at the end
450 \z Match only at end of string
9da458fc
IZ
451 \G Match only at pos() (e.g. at the end-of-match position
452 of prior m//g)
a0d0e21e 453
14218588 454A word boundary (C<\b>) is a spot between two characters
19799a22
GS
455that has a C<\w> on one side of it and a C<\W> on the other side
456of it (in either order), counting the imaginary characters off the
457beginning and end of the string as matching a C<\W>. (Within
458character classes C<\b> represents backspace rather than a word
459boundary, just as it normally does in any double-quoted string.)
460The C<\A> and C<\Z> are just like "^" and "$", except that they
461won't match multiple times when the C</m> modifier is used, while
462"^" and "$" will match at every internal line boundary. To match
463the actual end of the string and not ignore an optional trailing
464newline, use C<\z>.
d74e8afc 465X<\b> X<\A> X<\Z> X<\z> X</m>
19799a22
GS
466
467The C<\G> assertion can be used to chain global matches (using
468C<m//g>), as described in L<perlop/"Regexp Quote-Like Operators">.
469It is also useful when writing C<lex>-like scanners, when you have
470several patterns that you want to match against consequent substrings
471of your string, see the previous reference. The actual location
472where C<\G> will match can also be influenced by using C<pos()> as
58e23c8d
YO
473an lvalue: see L<perlfunc/pos>. Note that the rule for zero-length
474matches is modified somewhat, in that contents to the left of C<\G> is
475not counted when determining the length of the match. Thus the following
476will not match forever:
d74e8afc 477X<\G>
c47ff5f1 478
58e23c8d
YO
479 $str = 'ABC';
480 pos($str) = 1;
481 while (/.\G/g) {
482 print $&;
483 }
484
485It will print 'A' and then terminate, as it considers the match to
486be zero-width, and thus will not match at the same position twice in a
487row.
488
489It is worth noting that C<\G> improperly used can result in an infinite
490loop. Take care when using patterns that include C<\G> in an alternation.
491
04838cea
RGS
492=head3 Capture buffers
493
0d017f4d
WL
494The bracketing construct C<( ... )> creates capture buffers. To refer
495to the current contents of a buffer later on, within the same pattern,
496use \1 for the first, \2 for the second, and so on.
497Outside the match use "$" instead of "\". (The
81714fb9 498\<digit> notation works in certain circumstances outside
14218588
GS
499the match. See the warning below about \1 vs $1 for details.)
500Referring back to another part of the match is called a
501I<backreference>.
d74e8afc
ITB
502X<regex, capture buffer> X<regexp, capture buffer>
503X<regular expression, capture buffer> X<backreference>
14218588
GS
504
505There is no limit to the number of captured substrings that you may
506use. However Perl also uses \10, \11, etc. as aliases for \010,
fb55449c
JH
507\011, etc. (Recall that 0 means octal, so \011 is the character at
508number 9 in your coded character set; which would be the 10th character,
81714fb9
YO
509a horizontal tab under ASCII.) Perl resolves this
510ambiguity by interpreting \10 as a backreference only if at least 10
511left parentheses have opened before it. Likewise \11 is a
512backreference only if at least 11 left parentheses have opened
513before it. And so on. \1 through \9 are always interpreted as
5624f11d 514backreferences.
c74340f9 515
1f1031fe 516X<\g{1}> X<\g{-1}> X<\g{name}> X<relative backreference> X<named backreference>
2bf803e2 517In order to provide a safer and easier way to construct patterns using
0d017f4d 518backreferences, Perl 5.10 provides the C<\g{N}> notation. The curly
2bf803e2
YO
519brackets are optional, however omitting them is less safe as the meaning
520of the pattern can be changed by text (such as digits) following it.
521When N is a positive integer the C<\g{N}> notation is exactly equivalent
522to using normal backreferences. When N is a negative integer then it is
523a relative backreference referring to the previous N'th capturing group.
1f1031fe
YO
524When the bracket form is used and N is not an integer, it is treated as a
525reference to a named buffer.
2bf803e2
YO
526
527Thus C<\g{-1}> refers to the last buffer, C<\g{-2}> refers to the
528buffer before that. For example:
5624f11d
YO
529
530 /
531 (Y) # buffer 1
532 ( # buffer 2
533 (X) # buffer 3
2bf803e2
YO
534 \g{-1} # backref to buffer 3
535 \g{-3} # backref to buffer 1
5624f11d
YO
536 )
537 /x
538
2bf803e2 539and would match the same as C</(Y) ( (X) \3 \1 )/x>.
14218588 540
81714fb9 541Additionally, as of Perl 5.10 you may use named capture buffers and named
1f1031fe 542backreferences. The notation is C<< (?<name>...) >> to declare and C<< \k<name> >>
0d017f4d
WL
543to reference. You may also use apostrophes instead of angle brackets to delimit the
544name; and you may use the bracketed C<< \g{name} >> backreference syntax.
545It's possible to refer to a named capture buffer by absolute and relative number as well.
546Outside the pattern, a named capture buffer is available via the C<%+> hash.
547When different buffers within the same pattern have the same name, C<$+{name}>
548and C<< \k<name> >> refer to the leftmost defined group. (Thus it's possible
549to do things with named capture buffers that would otherwise require C<(??{})>
550code to accomplish.)
551X<named capture buffer> X<regular expression, named capture buffer>
552X<%+> X<$+{name}> X<\k{name}>
81714fb9 553
14218588 554Examples:
a0d0e21e
LW
555
556 s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words
557
81714fb9
YO
558 /(.)\1/ # find first doubled char
559 and print "'$1' is the first doubled character\n";
560
561 /(?<char>.)\k<char>/ # ... a different way
562 and print "'$+{char}' is the first doubled character\n";
563
0d017f4d 564 /(?'char'.)\1/ # ... mix and match
81714fb9 565 and print "'$1' is the first doubled character\n";
c47ff5f1 566
14218588 567 if (/Time: (..):(..):(..)/) { # parse out values
a0d0e21e
LW
568 $hours = $1;
569 $minutes = $2;
570 $seconds = $3;
571 }
c47ff5f1 572
14218588
GS
573Several special variables also refer back to portions of the previous
574match. C<$+> returns whatever the last bracket match matched.
575C<$&> returns the entire matched string. (At one point C<$0> did
576also, but now it returns the name of the program.) C<$`> returns
77ea4f6d
JV
577everything before the matched string. C<$'> returns everything
578after the matched string. And C<$^N> contains whatever was matched by
579the most-recently closed group (submatch). C<$^N> can be used in
580extended patterns (see below), for example to assign a submatch to a
81714fb9 581variable.
d74e8afc 582X<$+> X<$^N> X<$&> X<$`> X<$'>
14218588 583
665e98b9 584The numbered match variables ($1, $2, $3, etc.) and the related punctuation
77ea4f6d 585set (C<$+>, C<$&>, C<$`>, C<$'>, and C<$^N>) are all dynamically scoped
14218588
GS
586until the end of the enclosing block or until the next successful
587match, whichever comes first. (See L<perlsyn/"Compound Statements">.)
d74e8afc
ITB
588X<$+> X<$^N> X<$&> X<$`> X<$'>
589X<$1> X<$2> X<$3> X<$4> X<$5> X<$6> X<$7> X<$8> X<$9>
590
14218588 591
0d017f4d 592B<NOTE>: Failed matches in Perl do not reset the match variables,
5146ce24 593which makes it easier to write code that tests for a series of more
665e98b9
JH
594specific cases and remembers the best match.
595
14218588
GS
596B<WARNING>: Once Perl sees that you need one of C<$&>, C<$`>, or
597C<$'> anywhere in the program, it has to provide them for every
598pattern match. This may substantially slow your program. Perl
599uses the same mechanism to produce $1, $2, etc, so you also pay a
600price for each pattern that contains capturing parentheses. (To
601avoid this cost while retaining the grouping behaviour, use the
602extended regular expression C<(?: ... )> instead.) But if you never
603use C<$&>, C<$`> or C<$'>, then patterns I<without> capturing
604parentheses will not be penalized. So avoid C<$&>, C<$'>, and C<$`>
605if you can, but if you can't (and some algorithms really appreciate
606them), once you've used them once, use them at will, because you've
607already paid the price. As of 5.005, C<$&> is not so costly as the
608other two.
d74e8afc 609X<$&> X<$`> X<$'>
68dc0745 610
cde0cee5
YO
611As a workaround for this problem, Perl 5.10 introduces C<${^PREMATCH}>,
612C<${^MATCH}> and C<${^POSTMATCH}>, which are equivalent to C<$`>, C<$&>
613and C<$'>, B<except> that they are only guaranteed to be defined after a
87e95b7f 614successful match that was executed with the C</p> (preserve) modifier.
cde0cee5
YO
615The use of these variables incurs no global performance penalty, unlike
616their punctuation char equivalents, however at the trade-off that you
617have to tell perl when you want to use them.
87e95b7f 618X</p> X<p modifier>
cde0cee5 619
19799a22
GS
620Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
621C<\w>, C<\n>. Unlike some other regular expression languages, there
622are no backslashed symbols that aren't alphanumeric. So anything
c47ff5f1 623that looks like \\, \(, \), \<, \>, \{, or \} is always
19799a22
GS
624interpreted as a literal character, not a metacharacter. This was
625once used in a common idiom to disable or quote the special meanings
626of regular expression metacharacters in a string that you want to
36bbe248 627use for a pattern. Simply quote all non-"word" characters:
a0d0e21e
LW
628
629 $pattern =~ s/(\W)/\\$1/g;
630
f1cbbd6e 631(If C<use locale> is set, then this depends on the current locale.)
14218588
GS
632Today it is more common to use the quotemeta() function or the C<\Q>
633metaquoting escape sequence to disable all metacharacters' special
634meanings like this:
a0d0e21e
LW
635
636 /$unquoted\Q$quoted\E$unquoted/
637
9da458fc
IZ
638Beware that if you put literal backslashes (those not inside
639interpolated variables) between C<\Q> and C<\E>, double-quotish
640backslash interpolation may lead to confusing results. If you
641I<need> to use literal backslashes within C<\Q...\E>,
642consult L<perlop/"Gory details of parsing quoted constructs">.
643
19799a22
GS
644=head2 Extended Patterns
645
14218588
GS
646Perl also defines a consistent extension syntax for features not
647found in standard tools like B<awk> and B<lex>. The syntax is a
648pair of parentheses with a question mark as the first thing within
649the parentheses. The character after the question mark indicates
650the extension.
19799a22 651
14218588
GS
652The stability of these extensions varies widely. Some have been
653part of the core language for many years. Others are experimental
654and may change without warning or be completely removed. Check
655the documentation on an individual feature to verify its current
656status.
19799a22 657
14218588
GS
658A question mark was chosen for this and for the minimal-matching
659construct because 1) question marks are rare in older regular
660expressions, and 2) whenever you see one, you should stop and
661"question" exactly what is going on. That's psychology...
a0d0e21e
LW
662
663=over 10
664
cc6b7395 665=item C<(?#text)>
d74e8afc 666X<(?#)>
a0d0e21e 667
14218588 668A comment. The text is ignored. If the C</x> modifier enables
19799a22 669whitespace formatting, a simple C<#> will suffice. Note that Perl closes
259138e3
GS
670the comment as soon as it sees a C<)>, so there is no way to put a literal
671C<)> in the comment.
a0d0e21e 672
f7819f85 673=item C<(?pimsx-imsx)>
d74e8afc 674X<(?)>
19799a22 675
0b6d1084
JH
676One or more embedded pattern-match modifiers, to be turned on (or
677turned off, if preceded by C<->) for the remainder of the pattern or
678the remainder of the enclosing pattern group (if any). This is
679particularly useful for dynamic patterns, such as those read in from a
0d017f4d
WL
680configuration file, taken from an argument, or specified in a table
681somewhere. Consider the case where some patterns want to be case
682sensitive and some do not: The case insensitive ones merely need to
683include C<(?i)> at the front of the pattern. For example:
19799a22
GS
684
685 $pattern = "foobar";
5d458dd8 686 if ( /$pattern/i ) { }
19799a22
GS
687
688 # more flexible:
689
690 $pattern = "(?i)foobar";
5d458dd8 691 if ( /$pattern/ ) { }
19799a22 692
0b6d1084 693These modifiers are restored at the end of the enclosing group. For example,
19799a22
GS
694
695 ( (?i) blah ) \s+ \1
696
0d017f4d
WL
697will match C<blah> in any case, some spaces, and an exact (I<including the case>!)
698repetition of the previous word, assuming the C</x> modifier, and no C</i>
699modifier outside this group.
19799a22 700
5530442b 701Note that the C<p> modifier is special in that it can only be enabled,
cde0cee5 702not disabled, and that its presence anywhere in a pattern has a global
5530442b 703effect. Thus C<(?-p)> and C<(?-p:...)> are meaningless and will warn
cde0cee5
YO
704when executed under C<use warnings>.
705
5a964f20 706=item C<(?:pattern)>
d74e8afc 707X<(?:)>
a0d0e21e 708
ca9dfc88
IZ
709=item C<(?imsx-imsx:pattern)>
710
5a964f20
TC
711This is for clustering, not capturing; it groups subexpressions like
712"()", but doesn't make backreferences as "()" does. So
a0d0e21e 713
5a964f20 714 @fields = split(/\b(?:a|b|c)\b/)
a0d0e21e
LW
715
716is like
717
5a964f20 718 @fields = split(/\b(a|b|c)\b/)
a0d0e21e 719
19799a22
GS
720but doesn't spit out extra fields. It's also cheaper not to capture
721characters if you don't need to.
a0d0e21e 722
19799a22 723Any letters between C<?> and C<:> act as flags modifiers as with
5d458dd8 724C<(?imsx-imsx)>. For example,
ca9dfc88
IZ
725
726 /(?s-i:more.*than).*million/i
727
14218588 728is equivalent to the more verbose
ca9dfc88
IZ
729
730 /(?:(?s-i)more.*than).*million/i
731
594d7033
YO
732=item C<(?|pattern)>
733X<(?|)> X<Branch reset>
734
735This is the "branch reset" pattern, which has the special property
736that the capture buffers are numbered from the same starting point
693596a8 737in each alternation branch. It is available starting from perl 5.10.
4deaaa80 738
693596a8
RGS
739Capture buffers are numbered from left to right, but inside this
740construct the numbering is restarted for each branch.
4deaaa80
PJ
741
742The numbering within each branch will be as normal, and any buffers
743following this construct will be numbered as though the construct
744contained only one branch, that being the one with the most capture
745buffers in it.
746
747This construct will be useful when you want to capture one of a
748number of alternative matches.
749
750Consider the following pattern. The numbers underneath show in
751which buffer the captured content will be stored.
594d7033
YO
752
753
754 # before ---------------branch-reset----------- after
755 / ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
756 # 1 2 2 3 2 3 4
757
ee9b8eae
YO
758=item Look-Around Assertions
759X<look-around assertion> X<lookaround assertion> X<look-around> X<lookaround>
760
761Look-around assertions are zero width patterns which match a specific
762pattern without including it in C<$&>. Positive assertions match when
763their subpattern matches, negative assertions match when their subpattern
764fails. Look-behind matches text up to the current match position,
765look-ahead matches text following the current match position.
766
767=over 4
768
5a964f20 769=item C<(?=pattern)>
d74e8afc 770X<(?=)> X<look-ahead, positive> X<lookahead, positive>
a0d0e21e 771
19799a22 772A zero-width positive look-ahead assertion. For example, C</\w+(?=\t)/>
a0d0e21e
LW
773matches a word followed by a tab, without including the tab in C<$&>.
774
5a964f20 775=item C<(?!pattern)>
d74e8afc 776X<(?!)> X<look-ahead, negative> X<lookahead, negative>
a0d0e21e 777
19799a22 778A zero-width negative look-ahead assertion. For example C</foo(?!bar)/>
a0d0e21e 779matches any occurrence of "foo" that isn't followed by "bar". Note
19799a22
GS
780however that look-ahead and look-behind are NOT the same thing. You cannot
781use this for look-behind.
7b8d334a 782
5a964f20 783If you are looking for a "bar" that isn't preceded by a "foo", C</(?!foo)bar/>
7b8d334a
GS
784will not do what you want. That's because the C<(?!foo)> is just saying that
785the next thing cannot be "foo"--and it's not, it's a "bar", so "foobar" will
786match. You would have to do something like C</(?!foo)...bar/> for that. We
787say "like" because there's the case of your "bar" not having three characters
788before it. You could cover that this way: C</(?:(?!foo)...|^.{0,2})bar/>.
789Sometimes it's still easier just to say:
a0d0e21e 790
a3cb178b 791 if (/bar/ && $` !~ /foo$/)
a0d0e21e 792
19799a22 793For look-behind see below.
c277df42 794
ee9b8eae
YO
795=item C<(?<=pattern)> C<\K>
796X<(?<=)> X<look-behind, positive> X<lookbehind, positive> X<\K>
c277df42 797
c47ff5f1 798A zero-width positive look-behind assertion. For example, C</(?<=\t)\w+/>
19799a22
GS
799matches a word that follows a tab, without including the tab in C<$&>.
800Works only for fixed-width look-behind.
c277df42 801
ee9b8eae
YO
802There is a special form of this construct, called C<\K>, which causes the
803regex engine to "keep" everything it had matched prior to the C<\K> and
804not include it in C<$&>. This effectively provides variable length
805look-behind. The use of C<\K> inside of another look-around assertion
806is allowed, but the behaviour is currently not well defined.
807
c62285ac 808For various reasons C<\K> may be significantly more efficient than the
ee9b8eae
YO
809equivalent C<< (?<=...) >> construct, and it is especially useful in
810situations where you want to efficiently remove something following
811something else in a string. For instance
812
813 s/(foo)bar/$1/g;
814
815can be rewritten as the much more efficient
816
817 s/foo\Kbar//g;
818
5a964f20 819=item C<(?<!pattern)>
d74e8afc 820X<(?<!)> X<look-behind, negative> X<lookbehind, negative>
c277df42 821
19799a22
GS
822A zero-width negative look-behind assertion. For example C</(?<!bar)foo/>
823matches any occurrence of "foo" that does not follow "bar". Works
824only for fixed-width look-behind.
c277df42 825
ee9b8eae
YO
826=back
827
81714fb9
YO
828=item C<(?'NAME'pattern)>
829
830=item C<< (?<NAME>pattern) >>
831X<< (?<NAME>) >> X<(?'NAME')> X<named capture> X<capture>
832
833A named capture buffer. Identical in every respect to normal capturing
0d017f4d 834parentheses C<()> but for the additional fact that C<%+> may be used after
c62285ac 835a successful match to refer to a named buffer. See C<perlvar> for more
81714fb9
YO
836details on the C<%+> hash.
837
838If multiple distinct capture buffers have the same name then the
839$+{NAME} will refer to the leftmost defined buffer in the match.
840
0d017f4d 841The forms C<(?'NAME'pattern)> and C<< (?<NAME>pattern) >> are equivalent.
81714fb9
YO
842
843B<NOTE:> While the notation of this construct is the same as the similar
0d017f4d 844function in .NET regexes, the behavior is not. In Perl the buffers are
81714fb9
YO
845numbered sequentially regardless of being named or not. Thus in the
846pattern
847
848 /(x)(?<foo>y)(z)/
849
850$+{foo} will be the same as $2, and $3 will contain 'z' instead of
851the opposite which is what a .NET regex hacker might expect.
852
1f1031fe
YO
853Currently NAME is restricted to simple identifiers only.
854In other words, it must match C</^[_A-Za-z][_A-Za-z0-9]*\z/> or
855its Unicode extension (see L<utf8>),
856though it isn't extended by the locale (see L<perllocale>).
81714fb9 857
1f1031fe 858B<NOTE:> In order to make things easier for programmers with experience
0d017f4d
WL
859with the Python or PCRE regex engines, the pattern C<< (?PE<lt>NAMEE<gt>pattern) >>
860may be used instead of C<< (?<NAME>pattern) >>; however this form does not
1f1031fe
YO
861support the use of single quotes as a delimiter for the name. This is
862only available in Perl 5.10 or later.
81714fb9 863
1f1031fe
YO
864=item C<< \k<NAME> >>
865
866=item C<< \k'NAME' >>
81714fb9
YO
867
868Named backreference. Similar to numeric backreferences, except that
869the group is designated by name and not number. If multiple groups
870have the same name then it refers to the leftmost defined group in
871the current match.
872
0d017f4d 873It is an error to refer to a name not defined by a C<< (?<NAME>) >>
81714fb9
YO
874earlier in the pattern.
875
876Both forms are equivalent.
877
1f1031fe 878B<NOTE:> In order to make things easier for programmers with experience
0d017f4d
WL
879with the Python or PCRE regex engines, the pattern C<< (?P=NAME) >>
880may be used instead of C<< \k<NAME> >> in Perl 5.10 or later.
1f1031fe 881
cc6b7395 882=item C<(?{ code })>
d74e8afc 883X<(?{})> X<regex, code in> X<regexp, code in> X<regular expression, code in>
c277df42 884
19799a22 885B<WARNING>: This extended regular expression feature is considered
b9b4dddf
YO
886experimental, and may be changed without notice. Code executed that
887has side effects may not perform identically from version to version
888due to the effect of future optimisations in the regex engine.
c277df42 889
cc46d5f2 890This zero-width assertion evaluates any embedded Perl code. It
19799a22
GS
891always succeeds, and its C<code> is not interpolated. Currently,
892the rules to determine where the C<code> ends are somewhat convoluted.
893
77ea4f6d
JV
894This feature can be used together with the special variable C<$^N> to
895capture the results of submatches in variables without having to keep
896track of the number of nested parentheses. For example:
897
898 $_ = "The brown fox jumps over the lazy dog";
899 /the (\S+)(?{ $color = $^N }) (\S+)(?{ $animal = $^N })/i;
900 print "color = $color, animal = $animal\n";
901
754091cb
RGS
902Inside the C<(?{...})> block, C<$_> refers to the string the regular
903expression is matching against. You can also use C<pos()> to know what is
fa11829f 904the current position of matching within this string.
754091cb 905
19799a22
GS
906The C<code> is properly scoped in the following sense: If the assertion
907is backtracked (compare L<"Backtracking">), all changes introduced after
908C<local>ization are undone, so that
b9ac3b5b
GS
909
910 $_ = 'a' x 8;
5d458dd8 911 m<
b9ac3b5b
GS
912 (?{ $cnt = 0 }) # Initialize $cnt.
913 (
5d458dd8 914 a
b9ac3b5b
GS
915 (?{
916 local $cnt = $cnt + 1; # Update $cnt, backtracking-safe.
917 })
5d458dd8 918 )*
b9ac3b5b
GS
919 aaaa
920 (?{ $res = $cnt }) # On success copy to non-localized
921 # location.
922 >x;
923
0d017f4d 924will set C<$res = 4>. Note that after the match, C<$cnt> returns to the globally
14218588 925introduced value, because the scopes that restrict C<local> operators
b9ac3b5b
GS
926are unwound.
927
19799a22
GS
928This assertion may be used as a C<(?(condition)yes-pattern|no-pattern)>
929switch. If I<not> used in this way, the result of evaluation of
930C<code> is put into the special variable C<$^R>. This happens
931immediately, so C<$^R> can be used from other C<(?{ code })> assertions
932inside the same regular expression.
b9ac3b5b 933
19799a22
GS
934The assignment to C<$^R> above is properly localized, so the old
935value of C<$^R> is restored if the assertion is backtracked; compare
936L<"Backtracking">.
b9ac3b5b 937
61528107
SP
938Due to an unfortunate implementation issue, the Perl code contained in these
939blocks is treated as a compile time closure that can have seemingly bizarre
6bda09f9 940consequences when used with lexically scoped variables inside of subroutines
61528107
SP
941or loops. There are various workarounds for this, including simply using
942global variables instead. If you are using this construct and strange results
6bda09f9
YO
943occur then check for the use of lexically scoped variables.
944
19799a22
GS
945For reasons of security, this construct is forbidden if the regular
946expression involves run-time interpolation of variables, unless the
947perilous C<use re 'eval'> pragma has been used (see L<re>), or the
948variables contain results of C<qr//> operator (see
5d458dd8 949L<perlop/"qr/STRING/imosx">).
871b0233 950
0d017f4d 951This restriction is due to the wide-spread and remarkably convenient
19799a22 952custom of using run-time determined strings as patterns. For example:
871b0233
IZ
953
954 $re = <>;
955 chomp $re;
956 $string =~ /$re/;
957
14218588
GS
958Before Perl knew how to execute interpolated code within a pattern,
959this operation was completely safe from a security point of view,
960although it could raise an exception from an illegal pattern. If
961you turn on the C<use re 'eval'>, though, it is no longer secure,
962so you should only do so if you are also using taint checking.
963Better yet, use the carefully constrained evaluation within a Safe
cc46d5f2 964compartment. See L<perlsec> for details about both these mechanisms.
871b0233 965
0d017f4d 966Because Perl's regex engine is currently not re-entrant, interpolated
8988a1bb
DD
967code may not invoke the regex engine either directly with C<m//> or C<s///>),
968or indirectly with functions such as C<split>.
969
14455d6c 970=item C<(??{ code })>
d74e8afc
ITB
971X<(??{})>
972X<regex, postponed> X<regexp, postponed> X<regular expression, postponed>
0f5d15d6 973
19799a22 974B<WARNING>: This extended regular expression feature is considered
b9b4dddf
YO
975experimental, and may be changed without notice. Code executed that
976has side effects may not perform identically from version to version
977due to the effect of future optimisations in the regex engine.
0f5d15d6 978
19799a22
GS
979This is a "postponed" regular subexpression. The C<code> is evaluated
980at run time, at the moment this subexpression may match. The result
981of evaluation is considered as a regular expression and matched as
61528107 982if it were inserted instead of this construct. Note that this means
6bda09f9
YO
983that the contents of capture buffers defined inside an eval'ed pattern
984are not available outside of the pattern, and vice versa, there is no
985way for the inner pattern to refer to a capture buffer defined outside.
986Thus,
987
988 ('a' x 100)=~/(??{'(.)' x 100})/
989
81714fb9 990B<will> match, it will B<not> set $1.
0f5d15d6 991
428594d9 992The C<code> is not interpolated. As before, the rules to determine
19799a22
GS
993where the C<code> ends are currently somewhat convoluted.
994
995The following pattern matches a parenthesized group:
0f5d15d6
IZ
996
997 $re = qr{
998 \(
999 (?:
1000 (?> [^()]+ ) # Non-parens without backtracking
1001 |
14455d6c 1002 (??{ $re }) # Group with matching parens
0f5d15d6
IZ
1003 )*
1004 \)
1005 }x;
1006
6bda09f9
YO
1007See also C<(?PARNO)> for a different, more efficient way to accomplish
1008the same task.
1009
5d458dd8 1010Because perl's regex engine is not currently re-entrant, delayed
8988a1bb
DD
1011code may not invoke the regex engine either directly with C<m//> or C<s///>),
1012or indirectly with functions such as C<split>.
1013
5d458dd8
YO
1014Recursing deeper than 50 times without consuming any input string will
1015result in a fatal error. The maximum depth is compiled into perl, so
6bda09f9
YO
1016changing it requires a custom build.
1017
542fa716
YO
1018=item C<(?PARNO)> C<(?-PARNO)> C<(?+PARNO)> C<(?R)> C<(?0)>
1019X<(?PARNO)> X<(?1)> X<(?R)> X<(?0)> X<(?-1)> X<(?+1)> X<(?-PARNO)> X<(?+PARNO)>
6bda09f9 1020X<regex, recursive> X<regexp, recursive> X<regular expression, recursive>
542fa716 1021X<regex, relative recursion>
6bda09f9 1022
81714fb9
YO
1023Similar to C<(??{ code })> except it does not involve compiling any code,
1024instead it treats the contents of a capture buffer as an independent
61528107 1025pattern that must match at the current position. Capture buffers
81714fb9 1026contained by the pattern will have the value as determined by the
6bda09f9
YO
1027outermost recursion.
1028
894be9b7
YO
1029PARNO is a sequence of digits (not starting with 0) whose value reflects
1030the paren-number of the capture buffer to recurse to. C<(?R)> recurses to
1031the beginning of the whole pattern. C<(?0)> is an alternate syntax for
542fa716
YO
1032C<(?R)>. If PARNO is preceded by a plus or minus sign then it is assumed
1033to be relative, with negative numbers indicating preceding capture buffers
1034and positive ones following. Thus C<(?-1)> refers to the most recently
1035declared buffer, and C<(?+1)> indicates the next buffer to be declared.
c74340f9
YO
1036Note that the counting for relative recursion differs from that of
1037relative backreferences, in that with recursion unclosed buffers B<are>
1038included.
6bda09f9 1039
81714fb9 1040The following pattern matches a function foo() which may contain
f145b7e9 1041balanced parentheses as the argument.
6bda09f9
YO
1042
1043 $re = qr{ ( # paren group 1 (full function)
81714fb9 1044 foo
6bda09f9
YO
1045 ( # paren group 2 (parens)
1046 \(
1047 ( # paren group 3 (contents of parens)
1048 (?:
1049 (?> [^()]+ ) # Non-parens without backtracking
1050 |
1051 (?2) # Recurse to start of paren group 2
1052 )*
1053 )
1054 \)
1055 )
1056 )
1057 }x;
1058
1059If the pattern was used as follows
1060
1061 'foo(bar(baz)+baz(bop))'=~/$re/
1062 and print "\$1 = $1\n",
1063 "\$2 = $2\n",
1064 "\$3 = $3\n";
1065
1066the output produced should be the following:
1067
1068 $1 = foo(bar(baz)+baz(bop))
1069 $2 = (bar(baz)+baz(bop))
81714fb9 1070 $3 = bar(baz)+baz(bop)
6bda09f9 1071
81714fb9 1072If there is no corresponding capture buffer defined, then it is a
61528107 1073fatal error. Recursing deeper than 50 times without consuming any input
81714fb9 1074string will also result in a fatal error. The maximum depth is compiled
6bda09f9
YO
1075into perl, so changing it requires a custom build.
1076
542fa716
YO
1077The following shows how using negative indexing can make it
1078easier to embed recursive patterns inside of a C<qr//> construct
1079for later use:
1080
1081 my $parens = qr/(\((?:[^()]++|(?-1))*+\))/;
1082 if (/foo $parens \s+ + \s+ bar $parens/x) {
1083 # do something here...
1084 }
1085
81714fb9 1086B<Note> that this pattern does not behave the same way as the equivalent
0d017f4d 1087PCRE or Python construct of the same form. In Perl you can backtrack into
6bda09f9 1088a recursed group, in PCRE and Python the recursed into group is treated
542fa716
YO
1089as atomic. Also, modifiers are resolved at compile time, so constructs
1090like (?i:(?1)) or (?:(?i)(?1)) do not affect how the sub-pattern will
1091be processed.
6bda09f9 1092
894be9b7
YO
1093=item C<(?&NAME)>
1094X<(?&NAME)>
1095
0d017f4d
WL
1096Recurse to a named subpattern. Identical to C<(?PARNO)> except that the
1097parenthesis to recurse to is determined by name. If multiple parentheses have
894be9b7
YO
1098the same name, then it recurses to the leftmost.
1099
1100It is an error to refer to a name that is not declared somewhere in the
1101pattern.
1102
1f1031fe
YO
1103B<NOTE:> In order to make things easier for programmers with experience
1104with the Python or PCRE regex engines the pattern C<< (?P>NAME) >>
0d017f4d 1105may be used instead of C<< (?&NAME) >> in Perl 5.10 or later.
1f1031fe 1106
e2e6a0f1
YO
1107=item C<(?(condition)yes-pattern|no-pattern)>
1108X<(?()>
286f584a 1109
e2e6a0f1 1110=item C<(?(condition)yes-pattern)>
286f584a 1111
e2e6a0f1
YO
1112Conditional expression. C<(condition)> should be either an integer in
1113parentheses (which is valid if the corresponding pair of parentheses
1114matched), a look-ahead/look-behind/evaluate zero-width assertion, a
1115name in angle brackets or single quotes (which is valid if a buffer
1116with the given name matched), or the special symbol (R) (true when
1117evaluated inside of recursion or eval). Additionally the R may be
1118followed by a number, (which will be true when evaluated when recursing
1119inside of the appropriate group), or by C<&NAME>, in which case it will
1120be true only when evaluated during recursion in the named group.
1121
1122Here's a summary of the possible predicates:
1123
1124=over 4
1125
1126=item (1) (2) ...
1127
1128Checks if the numbered capturing buffer has matched something.
1129
1130=item (<NAME>) ('NAME')
1131
1132Checks if a buffer with the given name has matched something.
1133
1134=item (?{ CODE })
1135
1136Treats the code block as the condition.
1137
1138=item (R)
1139
1140Checks if the expression has been evaluated inside of recursion.
1141
1142=item (R1) (R2) ...
1143
1144Checks if the expression has been evaluated while executing directly
1145inside of the n-th capture group. This check is the regex equivalent of
1146
1147 if ((caller(0))[3] eq 'subname') { ... }
1148
1149In other words, it does not check the full recursion stack.
1150
1151=item (R&NAME)
1152
1153Similar to C<(R1)>, this predicate checks to see if we're executing
1154directly inside of the leftmost group with a given name (this is the same
1155logic used by C<(?&NAME)> to disambiguate). It does not check the full
1156stack, but only the name of the innermost active recursion.
1157
1158=item (DEFINE)
1159
1160In this case, the yes-pattern is never directly executed, and no
1161no-pattern is allowed. Similar in spirit to C<(?{0})> but more efficient.
1162See below for details.
1163
1164=back
1165
1166For example:
1167
1168 m{ ( \( )?
1169 [^()]+
1170 (?(1) \) )
1171 }x
1172
1173matches a chunk of non-parentheses, possibly included in parentheses
1174themselves.
1175
1176A special form is the C<(DEFINE)> predicate, which never executes directly
1177its yes-pattern, and does not allow a no-pattern. This allows to define
1178subpatterns which will be executed only by using the recursion mechanism.
1179This way, you can define a set of regular expression rules that can be
1180bundled into any pattern you choose.
1181
1182It is recommended that for this usage you put the DEFINE block at the
1183end of the pattern, and that you name any subpatterns defined within it.
1184
1185Also, it's worth noting that patterns defined this way probably will
1186not be as efficient, as the optimiser is not very clever about
1187handling them.
1188
1189An example of how this might be used is as follows:
1190
2bf803e2 1191 /(?<NAME>(?&NAME_PAT))(?<ADDR>(?&ADDRESS_PAT))
e2e6a0f1 1192 (?(DEFINE)
2bf803e2
YO
1193 (?<NAME_PAT>....)
1194 (?<ADRESS_PAT>....)
e2e6a0f1
YO
1195 )/x
1196
1197Note that capture buffers matched inside of recursion are not accessible
0d017f4d 1198after the recursion returns, so the extra layer of capturing buffers is
e2e6a0f1
YO
1199necessary. Thus C<$+{NAME_PAT}> would not be defined even though
1200C<$+{NAME}> would be.
286f584a 1201
c47ff5f1 1202=item C<< (?>pattern) >>
6bda09f9 1203X<backtrack> X<backtracking> X<atomic> X<possessive>
5a964f20 1204
19799a22
GS
1205An "independent" subexpression, one which matches the substring
1206that a I<standalone> C<pattern> would match if anchored at the given
9da458fc 1207position, and it matches I<nothing other than this substring>. This
19799a22
GS
1208construct is useful for optimizations of what would otherwise be
1209"eternal" matches, because it will not backtrack (see L<"Backtracking">).
9da458fc
IZ
1210It may also be useful in places where the "grab all you can, and do not
1211give anything back" semantic is desirable.
19799a22 1212
c47ff5f1 1213For example: C<< ^(?>a*)ab >> will never match, since C<< (?>a*) >>
19799a22
GS
1214(anchored at the beginning of string, as above) will match I<all>
1215characters C<a> at the beginning of string, leaving no C<a> for
1216C<ab> to match. In contrast, C<a*ab> will match the same as C<a+b>,
1217since the match of the subgroup C<a*> is influenced by the following
1218group C<ab> (see L<"Backtracking">). In particular, C<a*> inside
1219C<a*ab> will match fewer characters than a standalone C<a*>, since
1220this makes the tail match.
1221
c47ff5f1 1222An effect similar to C<< (?>pattern) >> may be achieved by writing
19799a22
GS
1223C<(?=(pattern))\1>. This matches the same substring as a standalone
1224C<a+>, and the following C<\1> eats the matched string; it therefore
c47ff5f1 1225makes a zero-length assertion into an analogue of C<< (?>...) >>.
19799a22
GS
1226(The difference between these two constructs is that the second one
1227uses a capturing group, thus shifting ordinals of backreferences
1228in the rest of a regular expression.)
1229
1230Consider this pattern:
c277df42 1231
871b0233 1232 m{ \(
e2e6a0f1
YO
1233 (
1234 [^()]+ # x+
1235 |
871b0233
IZ
1236 \( [^()]* \)
1237 )+
e2e6a0f1 1238 \)
871b0233 1239 }x
5a964f20 1240
19799a22
GS
1241That will efficiently match a nonempty group with matching parentheses
1242two levels deep or less. However, if there is no such group, it
1243will take virtually forever on a long string. That's because there
1244are so many different ways to split a long string into several
1245substrings. This is what C<(.+)+> is doing, and C<(.+)+> is similar
1246to a subpattern of the above pattern. Consider how the pattern
1247above detects no-match on C<((()aaaaaaaaaaaaaaaaaa> in several
1248seconds, but that each extra letter doubles this time. This
1249exponential performance will make it appear that your program has
14218588 1250hung. However, a tiny change to this pattern
5a964f20 1251
e2e6a0f1
YO
1252 m{ \(
1253 (
1254 (?> [^()]+ ) # change x+ above to (?> x+ )
1255 |
871b0233
IZ
1256 \( [^()]* \)
1257 )+
e2e6a0f1 1258 \)
871b0233 1259 }x
c277df42 1260
c47ff5f1 1261which uses C<< (?>...) >> matches exactly when the one above does (verifying
5a964f20
TC
1262this yourself would be a productive exercise), but finishes in a fourth
1263the time when used on a similar string with 1000000 C<a>s. Be aware,
1264however, that this pattern currently triggers a warning message under
9f1b1f2d 1265the C<use warnings> pragma or B<-w> switch saying it
6bab786b 1266C<"matches null string many times in regex">.
c277df42 1267
c47ff5f1 1268On simple groups, such as the pattern C<< (?> [^()]+ ) >>, a comparable
19799a22 1269effect may be achieved by negative look-ahead, as in C<[^()]+ (?! [^()] )>.
c277df42
IZ
1270This was only 4 times slower on a string with 1000000 C<a>s.
1271
9da458fc
IZ
1272The "grab all you can, and do not give anything back" semantic is desirable
1273in many situations where on the first sight a simple C<()*> looks like
1274the correct solution. Suppose we parse text with comments being delimited
1275by C<#> followed by some optional (horizontal) whitespace. Contrary to
4375e838 1276its appearance, C<#[ \t]*> I<is not> the correct subexpression to match
9da458fc
IZ
1277the comment delimiter, because it may "give up" some whitespace if
1278the remainder of the pattern can be made to match that way. The correct
1279answer is either one of these:
1280
1281 (?>#[ \t]*)
1282 #[ \t]*(?![ \t])
1283
1284For example, to grab non-empty comments into $1, one should use either
1285one of these:
1286
1287 / (?> \# [ \t]* ) ( .+ ) /x;
1288 / \# [ \t]* ( [^ \t] .* ) /x;
1289
1290Which one you pick depends on which of these expressions better reflects
1291the above specification of comments.
1292
6bda09f9
YO
1293In some literature this construct is called "atomic matching" or
1294"possessive matching".
1295
b9b4dddf
YO
1296Possessive quantifiers are equivalent to putting the item they are applied
1297to inside of one of these constructs. The following equivalences apply:
1298
1299 Quantifier Form Bracketing Form
1300 --------------- ---------------
1301 PAT*+ (?>PAT*)
1302 PAT++ (?>PAT+)
1303 PAT?+ (?>PAT?)
1304 PAT{min,max}+ (?>PAT{min,max})
1305
e2e6a0f1
YO
1306=back
1307
1308=head2 Special Backtracking Control Verbs
1309
1310B<WARNING:> These patterns are experimental and subject to change or
0d017f4d 1311removal in a future version of Perl. Their usage in production code should
e2e6a0f1
YO
1312be noted to avoid problems during upgrades.
1313
1314These special patterns are generally of the form C<(*VERB:ARG)>. Unless
1315otherwise stated the ARG argument is optional; in some cases, it is
1316forbidden.
1317
1318Any pattern containing a special backtracking verb that allows an argument
1319has the special behaviour that when executed it sets the current packages'
5d458dd8
YO
1320C<$REGERROR> and C<$REGMARK> variables. When doing so the following
1321rules apply:
e2e6a0f1 1322
5d458dd8
YO
1323On failure, the C<$REGERROR> variable will be set to the ARG value of the
1324verb pattern, if the verb was involved in the failure of the match. If the
1325ARG part of the pattern was omitted, then C<$REGERROR> will be set to the
1326name of the last C<(*MARK:NAME)> pattern executed, or to TRUE if there was
1327none. Also, the C<$REGMARK> variable will be set to FALSE.
e2e6a0f1 1328
5d458dd8
YO
1329On a successful match, the C<$REGERROR> variable will be set to FALSE, and
1330the C<$REGMARK> variable will be set to the name of the last
1331C<(*MARK:NAME)> pattern executed. See the explanation for the
1332C<(*MARK:NAME)> verb below for more details.
e2e6a0f1 1333
5d458dd8
YO
1334B<NOTE:> C<$REGERROR> and C<$REGMARK> are not magic variables like C<$1>
1335and most other regex related variables. They are not local to a scope, nor
1336readonly, but instead are volatile package variables similar to C<$AUTOLOAD>.
1337Use C<local> to localize changes to them to a specific scope if necessary.
e2e6a0f1
YO
1338
1339If a pattern does not contain a special backtracking verb that allows an
5d458dd8 1340argument, then C<$REGERROR> and C<$REGMARK> are not touched at all.
e2e6a0f1
YO
1341
1342=over 4
1343
1344=item Verbs that take an argument
1345
1346=over 4
1347
5d458dd8 1348=item C<(*PRUNE)> C<(*PRUNE:NAME)>
f7819f85 1349X<(*PRUNE)> X<(*PRUNE:NAME)>
54612592 1350
5d458dd8
YO
1351This zero-width pattern prunes the backtracking tree at the current point
1352when backtracked into on failure. Consider the pattern C<A (*PRUNE) B>,
1353where A and B are complex patterns. Until the C<(*PRUNE)> verb is reached,
1354A may backtrack as necessary to match. Once it is reached, matching
1355continues in B, which may also backtrack as necessary; however, should B
1356not match, then no further backtracking will take place, and the pattern
1357will fail outright at the current starting position.
54612592
YO
1358
1359The following example counts all the possible matching strings in a
1360pattern (without actually matching any of them).
1361
e2e6a0f1 1362 'aaab' =~ /a+b?(?{print "$&\n"; $count++})(*FAIL)/;
54612592
YO
1363 print "Count=$count\n";
1364
1365which produces:
1366
1367 aaab
1368 aaa
1369 aa
1370 a
1371 aab
1372 aa
1373 a
1374 ab
1375 a
1376 Count=9
1377
5d458dd8 1378If we add a C<(*PRUNE)> before the count like the following
54612592 1379
5d458dd8 1380 'aaab' =~ /a+b?(*PRUNE)(?{print "$&\n"; $count++})(*FAIL)/;
54612592
YO
1381 print "Count=$count\n";
1382
1383we prevent backtracking and find the count of the longest matching
1384at each matching startpoint like so:
1385
1386 aaab
1387 aab
1388 ab
1389 Count=3
1390
5d458dd8 1391Any number of C<(*PRUNE)> assertions may be used in a pattern.
54612592 1392
5d458dd8
YO
1393See also C<< (?>pattern) >> and possessive quantifiers for other ways to
1394control backtracking. In some cases, the use of C<(*PRUNE)> can be
1395replaced with a C<< (?>pattern) >> with no functional difference; however,
1396C<(*PRUNE)> can be used to handle cases that cannot be expressed using a
1397C<< (?>pattern) >> alone.
54612592 1398
e2e6a0f1 1399
5d458dd8
YO
1400=item C<(*SKIP)> C<(*SKIP:NAME)>
1401X<(*SKIP)>
e2e6a0f1 1402
5d458dd8 1403This zero-width pattern is similar to C<(*PRUNE)>, except that on
e2e6a0f1 1404failure it also signifies that whatever text that was matched leading up
5d458dd8
YO
1405to the C<(*SKIP)> pattern being executed cannot be part of I<any> match
1406of this pattern. This effectively means that the regex engine "skips" forward
1407to this position on failure and tries to match again, (assuming that
1408there is sufficient room to match).
1409
1410The name of the C<(*SKIP:NAME)> pattern has special significance. If a
1411C<(*MARK:NAME)> was encountered while matching, then it is that position
1412which is used as the "skip point". If no C<(*MARK)> of that name was
1413encountered, then the C<(*SKIP)> operator has no effect. When used
1414without a name the "skip point" is where the match point was when
1415executing the (*SKIP) pattern.
1416
1417Compare the following to the examples in C<(*PRUNE)>, note the string
24b23f37
YO
1418is twice as long:
1419
5d458dd8 1420 'aaabaaab' =~ /a+b?(*SKIP)(?{print "$&\n"; $count++})(*FAIL)/;
24b23f37
YO
1421 print "Count=$count\n";
1422
1423outputs
1424
1425 aaab
1426 aaab
1427 Count=2
1428
5d458dd8 1429Once the 'aaab' at the start of the string has matched, and the C<(*SKIP)>
e2e6a0f1 1430executed, the next startpoint will be where the cursor was when the
5d458dd8
YO
1431C<(*SKIP)> was executed.
1432
5d458dd8
YO
1433=item C<(*MARK:NAME)> C<(*:NAME)>
1434X<(*MARK)> C<(*MARK:NAME)> C<(*:NAME)>
1435
1436This zero-width pattern can be used to mark the point reached in a string
1437when a certain part of the pattern has been successfully matched. This
1438mark may be given a name. A later C<(*SKIP)> pattern will then skip
1439forward to that point if backtracked into on failure. Any number of
1440C<(*MARK)> patterns are allowed, and the NAME portion is optional and may
1441be duplicated.
1442
1443In addition to interacting with the C<(*SKIP)> pattern, C<(*MARK:NAME)>
1444can be used to "label" a pattern branch, so that after matching, the
1445program can determine which branches of the pattern were involved in the
1446match.
1447
1448When a match is successful, the C<$REGMARK> variable will be set to the
1449name of the most recently executed C<(*MARK:NAME)> that was involved
1450in the match.
1451
1452This can be used to determine which branch of a pattern was matched
c62285ac 1453without using a separate capture buffer for each branch, which in turn
5d458dd8
YO
1454can result in a performance improvement, as perl cannot optimize
1455C</(?:(x)|(y)|(z))/> as efficiently as something like
1456C</(?:x(*MARK:x)|y(*MARK:y)|z(*MARK:z))/>.
1457
1458When a match has failed, and unless another verb has been involved in
1459failing the match and has provided its own name to use, the C<$REGERROR>
1460variable will be set to the name of the most recently executed
1461C<(*MARK:NAME)>.
1462
1463See C<(*SKIP)> for more details.
1464
b62d2d15
YO
1465As a shortcut C<(*MARK:NAME)> can be written C<(*:NAME)>.
1466
5d458dd8
YO
1467=item C<(*THEN)> C<(*THEN:NAME)>
1468
1469This is similar to the "cut group" operator C<::> from Perl6. Like
1470C<(*PRUNE)>, this verb always matches, and when backtracked into on
1471failure, it causes the regex engine to try the next alternation in the
1472innermost enclosing group (capturing or otherwise).
1473
1474Its name comes from the observation that this operation combined with the
1475alternation operator (C<|>) can be used to create what is essentially a
1476pattern-based if/then/else block:
1477
1478 ( COND (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ )
1479
1480Note that if this operator is used and NOT inside of an alternation then
1481it acts exactly like the C<(*PRUNE)> operator.
1482
1483 / A (*PRUNE) B /
1484
1485is the same as
1486
1487 / A (*THEN) B /
1488
1489but
1490
1491 / ( A (*THEN) B | C (*THEN) D ) /
1492
1493is not the same as
1494
1495 / ( A (*PRUNE) B | C (*PRUNE) D ) /
1496
1497as after matching the A but failing on the B the C<(*THEN)> verb will
1498backtrack and try C; but the C<(*PRUNE)> verb will simply fail.
24b23f37 1499
e2e6a0f1
YO
1500=item C<(*COMMIT)>
1501X<(*COMMIT)>
24b23f37 1502
5d458dd8
YO
1503This is the Perl6 "commit pattern" C<< <commit> >> or C<:::>. It's a
1504zero-width pattern similar to C<(*SKIP)>, except that when backtracked
1505into on failure it causes the match to fail outright. No further attempts
1506to find a valid match by advancing the start pointer will occur again.
1507For example,
24b23f37 1508
e2e6a0f1 1509 'aaabaaab' =~ /a+b?(*COMMIT)(?{print "$&\n"; $count++})(*FAIL)/;
24b23f37
YO
1510 print "Count=$count\n";
1511
1512outputs
1513
1514 aaab
1515 Count=1
1516
e2e6a0f1
YO
1517In other words, once the C<(*COMMIT)> has been entered, and if the pattern
1518does not match, the regex engine will not try any further matching on the
1519rest of the string.
c277df42 1520
e2e6a0f1 1521=back
9af228c6 1522
e2e6a0f1 1523=item Verbs without an argument
9af228c6
YO
1524
1525=over 4
1526
e2e6a0f1
YO
1527=item C<(*FAIL)> C<(*F)>
1528X<(*FAIL)> X<(*F)>
9af228c6 1529
e2e6a0f1
YO
1530This pattern matches nothing and always fails. It can be used to force the
1531engine to backtrack. It is equivalent to C<(?!)>, but easier to read. In
1532fact, C<(?!)> gets optimised into C<(*FAIL)> internally.
9af228c6 1533
e2e6a0f1 1534It is probably useful only when combined with C<(?{})> or C<(??{})>.
9af228c6 1535
e2e6a0f1
YO
1536=item C<(*ACCEPT)>
1537X<(*ACCEPT)>
9af228c6 1538
e2e6a0f1
YO
1539B<WARNING:> This feature is highly experimental. It is not recommended
1540for production code.
9af228c6 1541
e2e6a0f1
YO
1542This pattern matches nothing and causes the end of successful matching at
1543the point at which the C<(*ACCEPT)> pattern was encountered, regardless of
1544whether there is actually more to match in the string. When inside of a
0d017f4d 1545nested pattern, such as recursion, or in a subpattern dynamically generated
e2e6a0f1 1546via C<(??{})>, only the innermost pattern is ended immediately.
9af228c6 1547
e2e6a0f1
YO
1548If the C<(*ACCEPT)> is inside of capturing buffers then the buffers are
1549marked as ended at the point at which the C<(*ACCEPT)> was encountered.
1550For instance:
9af228c6 1551
e2e6a0f1 1552 'AB' =~ /(A (A|B(*ACCEPT)|C) D)(E)/x;
9af228c6 1553
e2e6a0f1 1554will match, and C<$1> will be C<AB> and C<$2> will be C<B>, C<$3> will not
0d017f4d 1555be set. If another branch in the inner parentheses were matched, such as in the
e2e6a0f1 1556string 'ACDE', then the C<D> and C<E> would have to be matched as well.
9af228c6
YO
1557
1558=back
c277df42 1559
a0d0e21e
LW
1560=back
1561
c07a80fd 1562=head2 Backtracking
d74e8afc 1563X<backtrack> X<backtracking>
c07a80fd 1564
35a734be
IZ
1565NOTE: This section presents an abstract approximation of regular
1566expression behavior. For a more rigorous (and complicated) view of
1567the rules involved in selecting a match among possible alternatives,
0d017f4d 1568see L<Combining RE Pieces>.
35a734be 1569
c277df42 1570A fundamental feature of regular expression matching involves the
5a964f20 1571notion called I<backtracking>, which is currently used (when needed)
0d017f4d 1572by all regular non-possessive expression quantifiers, namely C<*>, C<*?>, C<+>,
9da458fc
IZ
1573C<+?>, C<{n,m}>, and C<{n,m}?>. Backtracking is often optimized
1574internally, but the general principle outlined here is valid.
c07a80fd
PP
1575
1576For a regular expression to match, the I<entire> regular expression must
1577match, not just part of it. So if the beginning of a pattern containing a
1578quantifier succeeds in a way that causes later parts in the pattern to
1579fail, the matching engine backs up and recalculates the beginning
1580part--that's why it's called backtracking.
1581
1582Here is an example of backtracking: Let's say you want to find the
1583word following "foo" in the string "Food is on the foo table.":
1584
1585 $_ = "Food is on the foo table.";
1586 if ( /\b(foo)\s+(\w+)/i ) {
1587 print "$2 follows $1.\n";
1588 }
1589
1590When the match runs, the first part of the regular expression (C<\b(foo)>)
1591finds a possible match right at the beginning of the string, and loads up
1592$1 with "Foo". However, as soon as the matching engine sees that there's
1593no whitespace following the "Foo" that it had saved in $1, it realizes its
68dc0745 1594mistake and starts over again one character after where it had the
c07a80fd
PP
1595tentative match. This time it goes all the way until the next occurrence
1596of "foo". The complete regular expression matches this time, and you get
1597the expected output of "table follows foo."
1598
1599Sometimes minimal matching can help a lot. Imagine you'd like to match
1600everything between "foo" and "bar". Initially, you write something
1601like this:
1602
1603 $_ = "The food is under the bar in the barn.";
1604 if ( /foo(.*)bar/ ) {
1605 print "got <$1>\n";
1606 }
1607
1608Which perhaps unexpectedly yields:
1609
1610 got <d is under the bar in the >
1611
1612That's because C<.*> was greedy, so you get everything between the
14218588 1613I<first> "foo" and the I<last> "bar". Here it's more effective
c07a80fd
PP
1614to use minimal matching to make sure you get the text between a "foo"
1615and the first "bar" thereafter.
1616
1617 if ( /foo(.*?)bar/ ) { print "got <$1>\n" }
1618 got <d is under the >
1619
0d017f4d 1620Here's another example. Let's say you'd like to match a number at the end
b6e13d97 1621of a string, and you also want to keep the preceding part of the match.
c07a80fd
PP
1622So you write this:
1623
1624 $_ = "I have 2 numbers: 53147";
1625 if ( /(.*)(\d*)/ ) { # Wrong!
1626 print "Beginning is <$1>, number is <$2>.\n";
1627 }
1628
1629That won't work at all, because C<.*> was greedy and gobbled up the
1630whole string. As C<\d*> can match on an empty string the complete
1631regular expression matched successfully.
1632
8e1088bc 1633 Beginning is <I have 2 numbers: 53147>, number is <>.
c07a80fd
PP
1634
1635Here are some variants, most of which don't work:
1636
1637 $_ = "I have 2 numbers: 53147";
1638 @pats = qw{
1639 (.*)(\d*)
1640 (.*)(\d+)
1641 (.*?)(\d*)
1642 (.*?)(\d+)
1643 (.*)(\d+)$
1644 (.*?)(\d+)$
1645 (.*)\b(\d+)$
1646 (.*\D)(\d+)$
1647 };
1648
1649 for $pat (@pats) {
1650 printf "%-12s ", $pat;
1651 if ( /$pat/ ) {
1652 print "<$1> <$2>\n";
1653 } else {
1654 print "FAIL\n";
1655 }
1656 }
1657
1658That will print out:
1659
1660 (.*)(\d*) <I have 2 numbers: 53147> <>
1661 (.*)(\d+) <I have 2 numbers: 5314> <7>
1662 (.*?)(\d*) <> <>
1663 (.*?)(\d+) <I have > <2>
1664 (.*)(\d+)$ <I have 2 numbers: 5314> <7>
1665 (.*?)(\d+)$ <I have 2 numbers: > <53147>
1666 (.*)\b(\d+)$ <I have 2 numbers: > <53147>
1667 (.*\D)(\d+)$ <I have 2 numbers: > <53147>
1668
1669As you see, this can be a bit tricky. It's important to realize that a
1670regular expression is merely a set of assertions that gives a definition
1671of success. There may be 0, 1, or several different ways that the
1672definition might succeed against a particular string. And if there are
5a964f20
TC
1673multiple ways it might succeed, you need to understand backtracking to
1674know which variety of success you will achieve.
c07a80fd 1675
19799a22 1676When using look-ahead assertions and negations, this can all get even
8b19b778 1677trickier. Imagine you'd like to find a sequence of non-digits not
c07a80fd
PP
1678followed by "123". You might try to write that as
1679
871b0233
IZ
1680 $_ = "ABC123";
1681 if ( /^\D*(?!123)/ ) { # Wrong!
1682 print "Yup, no 123 in $_\n";
1683 }
c07a80fd
PP
1684
1685But that isn't going to match; at least, not the way you're hoping. It
1686claims that there is no 123 in the string. Here's a clearer picture of
9b9391b2 1687why that pattern matches, contrary to popular expectations:
c07a80fd 1688
4358a253
SS
1689 $x = 'ABC123';
1690 $y = 'ABC445';
c07a80fd 1691
4358a253
SS
1692 print "1: got $1\n" if $x =~ /^(ABC)(?!123)/;
1693 print "2: got $1\n" if $y =~ /^(ABC)(?!123)/;
c07a80fd 1694
4358a253
SS
1695 print "3: got $1\n" if $x =~ /^(\D*)(?!123)/;
1696 print "4: got $1\n" if $y =~ /^(\D*)(?!123)/;
c07a80fd
PP
1697
1698This prints
1699
1700 2: got ABC
1701 3: got AB
1702 4: got ABC
1703
5f05dabc 1704You might have expected test 3 to fail because it seems to a more
c07a80fd
PP
1705general purpose version of test 1. The important difference between
1706them is that test 3 contains a quantifier (C<\D*>) and so can use
1707backtracking, whereas test 1 will not. What's happening is
1708that you've asked "Is it true that at the start of $x, following 0 or more
5f05dabc 1709non-digits, you have something that's not 123?" If the pattern matcher had
c07a80fd 1710let C<\D*> expand to "ABC", this would have caused the whole pattern to
54310121 1711fail.
14218588 1712
c07a80fd 1713The search engine will initially match C<\D*> with "ABC". Then it will
14218588 1714try to match C<(?!123> with "123", which fails. But because
c07a80fd
PP
1715a quantifier (C<\D*>) has been used in the regular expression, the
1716search engine can backtrack and retry the match differently
54310121 1717in the hope of matching the complete regular expression.
c07a80fd 1718
5a964f20
TC
1719The pattern really, I<really> wants to succeed, so it uses the
1720standard pattern back-off-and-retry and lets C<\D*> expand to just "AB" this
c07a80fd 1721time. Now there's indeed something following "AB" that is not
14218588 1722"123". It's "C123", which suffices.
c07a80fd 1723
14218588
GS
1724We can deal with this by using both an assertion and a negation.
1725We'll say that the first part in $1 must be followed both by a digit
1726and by something that's not "123". Remember that the look-aheads
1727are zero-width expressions--they only look, but don't consume any
1728of the string in their match. So rewriting this way produces what
c07a80fd
PP
1729you'd expect; that is, case 5 will fail, but case 6 succeeds:
1730
4358a253
SS
1731 print "5: got $1\n" if $x =~ /^(\D*)(?=\d)(?!123)/;
1732 print "6: got $1\n" if $y =~ /^(\D*)(?=\d)(?!123)/;
c07a80fd
PP
1733
1734 6: got ABC
1735
5a964f20 1736In other words, the two zero-width assertions next to each other work as though
19799a22 1737they're ANDed together, just as you'd use any built-in assertions: C</^$/>
c07a80fd
PP
1738matches only if you're at the beginning of the line AND the end of the
1739line simultaneously. The deeper underlying truth is that juxtaposition in
1740regular expressions always means AND, except when you write an explicit OR
1741using the vertical bar. C</ab/> means match "a" AND (then) match "b",
1742although the attempted matches are made at different positions because "a"
1743is not a zero-width assertion, but a one-width assertion.
1744
0d017f4d 1745B<WARNING>: Particularly complicated regular expressions can take
14218588 1746exponential time to solve because of the immense number of possible
0d017f4d 1747ways they can use backtracking to try for a match. For example, without
9da458fc
IZ
1748internal optimizations done by the regular expression engine, this will
1749take a painfully long time to run:
c07a80fd 1750
e1901655
IZ
1751 'aaaaaaaaaaaa' =~ /((a{0,5}){0,5})*[c]/
1752
1753And if you used C<*>'s in the internal groups instead of limiting them
1754to 0 through 5 matches, then it would take forever--or until you ran
1755out of stack space. Moreover, these internal optimizations are not
1756always applicable. For example, if you put C<{0,5}> instead of C<*>
1757on the external group, no current optimization is applicable, and the
1758match takes a long time to finish.
c07a80fd 1759
9da458fc
IZ
1760A powerful tool for optimizing such beasts is what is known as an
1761"independent group",
c47ff5f1 1762which does not backtrack (see L<C<< (?>pattern) >>>). Note also that
9da458fc 1763zero-length look-ahead/look-behind assertions will not backtrack to make
5d458dd8 1764the tail match, since they are in "logical" context: only
14218588 1765whether they match is considered relevant. For an example
9da458fc 1766where side-effects of look-ahead I<might> have influenced the
c47ff5f1 1767following match, see L<C<< (?>pattern) >>>.
c277df42 1768
a0d0e21e 1769=head2 Version 8 Regular Expressions
d74e8afc 1770X<regular expression, version 8> X<regex, version 8> X<regexp, version 8>
a0d0e21e 1771
5a964f20 1772In case you're not familiar with the "regular" Version 8 regex
a0d0e21e
LW
1773routines, here are the pattern-matching rules not described above.
1774
54310121 1775Any single character matches itself, unless it is a I<metacharacter>
a0d0e21e 1776with a special meaning described here or above. You can cause
5a964f20 1777characters that normally function as metacharacters to be interpreted
5f05dabc 1778literally by prefixing them with a "\" (e.g., "\." matches a ".", not any
0d017f4d
WL
1779character; "\\" matches a "\"). This escape mechanism is also required
1780for the character used as the pattern delimiter.
1781
1782A series of characters matches that series of characters in the target
1783string, so the pattern C<blurfl> would match "blurfl" in the target
1784string.
a0d0e21e
LW
1785
1786You can specify a character class, by enclosing a list of characters
5d458dd8 1787in C<[]>, which will match any character from the list. If the
a0d0e21e 1788first character after the "[" is "^", the class matches any character not
14218588 1789in the list. Within a list, the "-" character specifies a
5a964f20 1790range, so that C<a-z> represents all characters between "a" and "z",
8a4f6ac2
GS
1791inclusive. If you want either "-" or "]" itself to be a member of a
1792class, put it at the start of the list (possibly after a "^"), or
1793escape it with a backslash. "-" is also taken literally when it is
1794at the end of the list, just before the closing "]". (The
84850974
DD
1795following all specify the same class of three characters: C<[-az]>,
1796C<[az-]>, and C<[a\-z]>. All are different from C<[a-z]>, which
5d458dd8
YO
1797specifies a class containing twenty-six characters, even on EBCDIC-based
1798character sets.) Also, if you try to use the character
1799classes C<\w>, C<\W>, C<\s>, C<\S>, C<\d>, or C<\D> as endpoints of
1800a range, the "-" is understood literally.
a0d0e21e 1801
8ada0baa
JH
1802Note also that the whole range idea is rather unportable between
1803character sets--and even within character sets they may cause results
1804you probably didn't expect. A sound principle is to use only ranges
0d017f4d 1805that begin from and end at either alphabetics of equal case ([a-e],
8ada0baa
JH
1806[A-E]), or digits ([0-9]). Anything else is unsafe. If in doubt,
1807spell out the character sets in full.
1808
54310121 1809Characters may be specified using a metacharacter syntax much like that
a0d0e21e
LW
1810used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return,
1811"\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string
5d458dd8
YO
1812of octal digits, matches the character whose coded character set value
1813is I<nnn>. Similarly, \xI<nn>, where I<nn> are hexadecimal digits,
1814matches the character whose numeric value is I<nn>. The expression \cI<x>
1815matches the character control-I<x>. Finally, the "." metacharacter
fb55449c 1816matches any character except "\n" (unless you use C</s>).
a0d0e21e
LW
1817
1818You can specify a series of alternatives for a pattern using "|" to
1819separate them, so that C<fee|fie|foe> will match any of "fee", "fie",
5a964f20 1820or "foe" in the target string (as would C<f(e|i|o)e>). The
a0d0e21e
LW
1821first alternative includes everything from the last pattern delimiter
1822("(", "[", or the beginning of the pattern) up to the first "|", and
1823the last alternative contains everything from the last "|" to the next
14218588
GS
1824pattern delimiter. That's why it's common practice to include
1825alternatives in parentheses: to minimize confusion about where they
a3cb178b
GS
1826start and end.
1827
5a964f20 1828Alternatives are tried from left to right, so the first
a3cb178b
GS
1829alternative found for which the entire expression matches, is the one that
1830is chosen. This means that alternatives are not necessarily greedy. For
628afcb5 1831example: when matching C<foo|foot> against "barefoot", only the "foo"
a3cb178b
GS
1832part will match, as that is the first alternative tried, and it successfully
1833matches the target string. (This might not seem important, but it is
1834important when you are capturing matched text using parentheses.)
1835
5a964f20 1836Also remember that "|" is interpreted as a literal within square brackets,
a3cb178b 1837so if you write C<[fee|fie|foe]> you're really only matching C<[feio|]>.
a0d0e21e 1838
14218588
GS
1839Within a pattern, you may designate subpatterns for later reference
1840by enclosing them in parentheses, and you may refer back to the
1841I<n>th subpattern later in the pattern using the metacharacter
1842\I<n>. Subpatterns are numbered based on the left to right order
1843of their opening parenthesis. A backreference matches whatever
1844actually matched the subpattern in the string being examined, not
1845the rules for that subpattern. Therefore, C<(0|0x)\d*\s\1\d*> will
1846match "0x1234 0x4321", but not "0x1234 01234", because subpattern
18471 matched "0x", even though the rule C<0|0x> could potentially match
1848the leading 0 in the second number.
cb1a09d0 1849
0d017f4d 1850=head2 Warning on \1 Instead of $1
cb1a09d0 1851
5a964f20 1852Some people get too used to writing things like:
cb1a09d0
AD
1853
1854 $pattern =~ s/(\W)/\\\1/g;
1855
1856This is grandfathered for the RHS of a substitute to avoid shocking the
1857B<sed> addicts, but it's a dirty habit to get into. That's because in
d1be9408 1858PerlThink, the righthand side of an C<s///> is a double-quoted string. C<\1> in
cb1a09d0
AD
1859the usual double-quoted string means a control-A. The customary Unix
1860meaning of C<\1> is kludged in for C<s///>. However, if you get into the habit
1861of doing that, you get yourself into trouble if you then add an C</e>
1862modifier.
1863
5a964f20 1864 s/(\d+)/ \1 + 1 /eg; # causes warning under -w
cb1a09d0
AD
1865
1866Or if you try to do
1867
1868 s/(\d+)/\1000/;
1869
1870You can't disambiguate that by saying C<\{1}000>, whereas you can fix it with
14218588 1871C<${1}000>. The operation of interpolation should not be confused
cb1a09d0
AD
1872with the operation of matching a backreference. Certainly they mean two
1873different things on the I<left> side of the C<s///>.
9fa51da4 1874
0d017f4d 1875=head2 Repeated Patterns Matching a Zero-length Substring
c84d73f1 1876
19799a22 1877B<WARNING>: Difficult material (and prose) ahead. This section needs a rewrite.
c84d73f1
IZ
1878
1879Regular expressions provide a terse and powerful programming language. As
1880with most other power tools, power comes together with the ability
1881to wreak havoc.
1882
1883A common abuse of this power stems from the ability to make infinite
628afcb5 1884loops using regular expressions, with something as innocuous as:
c84d73f1
IZ
1885
1886 'foo' =~ m{ ( o? )* }x;
1887
0d017f4d 1888The C<o?> matches at the beginning of C<'foo'>, and since the position
c84d73f1 1889in the string is not moved by the match, C<o?> would match again and again
527e91da 1890because of the C<*> quantifier. Another common way to create a similar cycle
c84d73f1
IZ
1891is with the looping modifier C<//g>:
1892
1893 @matches = ( 'foo' =~ m{ o? }xg );
1894
1895or
1896
1897 print "match: <$&>\n" while 'foo' =~ m{ o? }xg;
1898
1899or the loop implied by split().
1900
1901However, long experience has shown that many programming tasks may
14218588
GS
1902be significantly simplified by using repeated subexpressions that
1903may match zero-length substrings. Here's a simple example being:
c84d73f1
IZ
1904
1905 @chars = split //, $string; # // is not magic in split
1906 ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /
1907
9da458fc 1908Thus Perl allows such constructs, by I<forcefully breaking
c84d73f1 1909the infinite loop>. The rules for this are different for lower-level
527e91da 1910loops given by the greedy quantifiers C<*+{}>, and for higher-level
c84d73f1
IZ
1911ones like the C</g> modifier or split() operator.
1912
19799a22
GS
1913The lower-level loops are I<interrupted> (that is, the loop is
1914broken) when Perl detects that a repeated expression matched a
1915zero-length substring. Thus
c84d73f1
IZ
1916
1917 m{ (?: NON_ZERO_LENGTH | ZERO_LENGTH )* }x;
1918
5d458dd8 1919is made equivalent to
c84d73f1 1920
5d458dd8
YO
1921 m{ (?: NON_ZERO_LENGTH )*
1922 |
1923 (?: ZERO_LENGTH )?
c84d73f1
IZ
1924 }x;
1925
1926The higher level-loops preserve an additional state between iterations:
5d458dd8 1927whether the last match was zero-length. To break the loop, the following
c84d73f1 1928match after a zero-length match is prohibited to have a length of zero.
5d458dd8 1929This prohibition interacts with backtracking (see L<"Backtracking">),
c84d73f1
IZ
1930and so the I<second best> match is chosen if the I<best> match is of
1931zero length.
1932
19799a22 1933For example:
c84d73f1
IZ
1934
1935 $_ = 'bar';
1936 s/\w??/<$&>/g;
1937
20fb949f 1938results in C<< <><b><><a><><r><> >>. At each position of the string the best
5d458dd8 1939match given by non-greedy C<??> is the zero-length match, and the I<second
c84d73f1
IZ
1940best> match is what is matched by C<\w>. Thus zero-length matches
1941alternate with one-character-long matches.
1942
5d458dd8 1943Similarly, for repeated C<m/()/g> the second-best match is the match at the
c84d73f1
IZ
1944position one notch further in the string.
1945
19799a22 1946The additional state of being I<matched with zero-length> is associated with
c84d73f1 1947the matched string, and is reset by each assignment to pos().
9da458fc
IZ
1948Zero-length matches at the end of the previous match are ignored
1949during C<split>.
c84d73f1 1950
0d017f4d 1951=head2 Combining RE Pieces
35a734be
IZ
1952
1953Each of the elementary pieces of regular expressions which were described
1954before (such as C<ab> or C<\Z>) could match at most one substring
1955at the given position of the input string. However, in a typical regular
1956expression these elementary pieces are combined into more complicated
1957patterns using combining operators C<ST>, C<S|T>, C<S*> etc
1958(in these examples C<S> and C<T> are regular subexpressions).
1959
1960Such combinations can include alternatives, leading to a problem of choice:
1961if we match a regular expression C<a|ab> against C<"abc">, will it match
1962substring C<"a"> or C<"ab">? One way to describe which substring is
1963actually matched is the concept of backtracking (see L<"Backtracking">).
1964However, this description is too low-level and makes you think
1965in terms of a particular implementation.
1966
1967Another description starts with notions of "better"/"worse". All the
1968substrings which may be matched by the given regular expression can be
1969sorted from the "best" match to the "worst" match, and it is the "best"
1970match which is chosen. This substitutes the question of "what is chosen?"
1971by the question of "which matches are better, and which are worse?".
1972
1973Again, for elementary pieces there is no such question, since at most
1974one match at a given position is possible. This section describes the
1975notion of better/worse for combining operators. In the description
1976below C<S> and C<T> are regular subexpressions.
1977
13a2d996 1978=over 4
35a734be
IZ
1979
1980=item C<ST>
1981
1982Consider two possible matches, C<AB> and C<A'B'>, C<A> and C<A'> are
1983substrings which can be matched by C<S>, C<B> and C<B'> are substrings
5d458dd8 1984which can be matched by C<T>.
35a734be
IZ
1985
1986If C<A> is better match for C<S> than C<A'>, C<AB> is a better
1987match than C<A'B'>.
1988
1989If C<A> and C<A'> coincide: C<AB> is a better match than C<AB'> if
1990C<B> is better match for C<T> than C<B'>.
1991
1992=item C<S|T>
1993
1994When C<S> can match, it is a better match than when only C<T> can match.
1995
1996Ordering of two matches for C<S> is the same as for C<S>. Similar for
1997two matches for C<T>.
1998
1999=item C<S{REPEAT_COUNT}>
2000
2001Matches as C<SSS...S> (repeated as many times as necessary).
2002
2003=item C<S{min,max}>
2004
2005Matches as C<S{max}|S{max-1}|...|S{min+1}|S{min}>.
2006
2007=item C<S{min,max}?>
2008
2009Matches as C<S{min}|S{min+1}|...|S{max-1}|S{max}>.
2010
2011=item C<S?>, C<S*>, C<S+>
2012
2013Same as C<S{0,1}>, C<S{0,BIG_NUMBER}>, C<S{1,BIG_NUMBER}> respectively.
2014
2015=item C<S??>, C<S*?>, C<S+?>
2016
2017Same as C<S{0,1}?>, C<S{0,BIG_NUMBER}?>, C<S{1,BIG_NUMBER}?> respectively.
2018
c47ff5f1 2019=item C<< (?>S) >>
35a734be
IZ
2020
2021Matches the best match for C<S> and only that.
2022
2023=item C<(?=S)>, C<(?<=S)>
2024
2025Only the best match for C<S> is considered. (This is important only if
2026C<S> has capturing parentheses, and backreferences are used somewhere
2027else in the whole regular expression.)
2028
2029=item C<(?!S)>, C<(?<!S)>
2030
2031For this grouping operator there is no need to describe the ordering, since
2032only whether or not C<S> can match is important.
2033
6bda09f9 2034=item C<(??{ EXPR })>, C<(?PARNO)>
35a734be
IZ
2035
2036The ordering is the same as for the regular expression which is
6bda09f9 2037the result of EXPR, or the pattern contained by capture buffer PARNO.
35a734be
IZ
2038
2039=item C<(?(condition)yes-pattern|no-pattern)>
2040
2041Recall that which of C<yes-pattern> or C<no-pattern> actually matches is
2042already determined. The ordering of the matches is the same as for the
2043chosen subexpression.
2044
2045=back
2046
2047The above recipes describe the ordering of matches I<at a given position>.
2048One more rule is needed to understand how a match is determined for the
2049whole regular expression: a match at an earlier position is always better
2050than a match at a later position.
2051
0d017f4d 2052=head2 Creating Custom RE Engines
c84d73f1
IZ
2053
2054Overloaded constants (see L<overload>) provide a simple way to extend
2055the functionality of the RE engine.
2056
2057Suppose that we want to enable a new RE escape-sequence C<\Y|> which
0d017f4d 2058matches at a boundary between whitespace characters and non-whitespace
c84d73f1
IZ
2059characters. Note that C<(?=\S)(?<!\S)|(?!\S)(?<=\S)> matches exactly
2060at these positions, so we want to have each C<\Y|> in the place of the
2061more complicated version. We can create a module C<customre> to do
2062this:
2063
2064 package customre;
2065 use overload;
2066
2067 sub import {
2068 shift;
2069 die "No argument to customre::import allowed" if @_;
2070 overload::constant 'qr' => \&convert;
2071 }
2072
2073 sub invalid { die "/$_[0]/: invalid escape '\\$_[1]'"}
2074
580a9fe1
RGS
2075 # We must also take care of not escaping the legitimate \\Y|
2076 # sequence, hence the presence of '\\' in the conversion rules.
5d458dd8 2077 my %rules = ( '\\' => '\\\\',
c84d73f1
IZ
2078 'Y|' => qr/(?=\S)(?<!\S)|(?!\S)(?<=\S)/ );
2079 sub convert {
2080 my $re = shift;
5d458dd8 2081 $re =~ s{
c84d73f1
IZ
2082 \\ ( \\ | Y . )
2083 }
5d458dd8 2084 { $rules{$1} or invalid($re,$1) }sgex;
c84d73f1
IZ
2085 return $re;
2086 }
2087
2088Now C<use customre> enables the new escape in constant regular
2089expressions, i.e., those without any runtime variable interpolations.
2090As documented in L<overload>, this conversion will work only over
2091literal parts of regular expressions. For C<\Y|$re\Y|> the variable
2092part of this regular expression needs to be converted explicitly
2093(but only if the special meaning of C<\Y|> should be enabled inside $re):
2094
2095 use customre;
2096 $re = <>;
2097 chomp $re;
2098 $re = customre::convert $re;
2099 /\Y|$re\Y|/;
2100
1f1031fe
YO
2101=head1 PCRE/Python Support
2102
2103As of Perl 5.10 Perl supports several Python/PCRE specific extensions
2104to the regex syntax. While Perl programmers are encouraged to use the
2105Perl specific syntax, the following are legal in Perl 5.10:
2106
2107=over 4
2108
ee9b8eae 2109=item C<< (?PE<lt>NAMEE<gt>pattern) >>
1f1031fe
YO
2110
2111Define a named capture buffer. Equivalent to C<< (?<NAME>pattern) >>.
2112
2113=item C<< (?P=NAME) >>
2114
2115Backreference to a named capture buffer. Equivalent to C<< \g{NAME} >>.
2116
2117=item C<< (?P>NAME) >>
2118
2119Subroutine call to a named capture buffer. Equivalent to C<< (?&NAME) >>.
2120
ee9b8eae 2121=back
1f1031fe 2122
19799a22
GS
2123=head1 BUGS
2124
9da458fc
IZ
2125This document varies from difficult to understand to completely
2126and utterly opaque. The wandering prose riddled with jargon is
2127hard to fathom in several places.
2128
2129This document needs a rewrite that separates the tutorial content
2130from the reference content.
19799a22
GS
2131
2132=head1 SEE ALSO
9fa51da4 2133
91e0c79e
MJD
2134L<perlrequick>.
2135
2136L<perlretut>.
2137
9b599b2a
GS
2138L<perlop/"Regexp Quote-Like Operators">.
2139
1e66bd83
PP
2140L<perlop/"Gory details of parsing quoted constructs">.
2141
14218588
GS
2142L<perlfaq6>.
2143
9b599b2a
GS
2144L<perlfunc/pos>.
2145
2146L<perllocale>.
2147
fb55449c
JH
2148L<perlebcdic>.
2149
14218588
GS
2150I<Mastering Regular Expressions> by Jeffrey Friedl, published
2151by O'Reilly and Associates.