This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Pod correction.
[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
c6ae04d3
KW
10If you haven't used regular expressions before, a tutorial introduction
11is available in L<perlretut>. If you know just a little about them,
12a quick-start introduction is available in L<perlrequick>.
13
c57a3350
KW
14Except for L</The Basics> section, this page assumes you are familiar
15with regular expression basics, like what is a "pattern", what does it
16look like, and how it is basically used. For a reference on how they
17are used, plus various examples of the same, see discussions of C<m//>,
18C<s///>, C<qr//> and C<"??"> in L<perlop/"Regexp Quote-Like Operators">.
cb1a09d0 19
67cdf558
KW
20New in v5.22, L<C<use re 'strict'>|re/'strict' mode> applies stricter
21rules than otherwise when compiling regular expression patterns. It can
22find things that, while legal, may not be what you intended.
0d017f4d 23
c57a3350
KW
24=head2 The Basics
25X<regular expression, version 8> X<regex, version 8> X<regexp, version 8>
26
27Regular expressions are strings with the very particular syntax and
28meaning described in this document and auxiliary documents referred to
29by this one. The strings are called "patterns". Patterns are used to
30determine if some other string, called the "target", has (or doesn't
31have) the characteristics specified by the pattern. We call this
32"matching" the target string against the pattern. Usually the match is
33done by having the target be the first operand, and the pattern be the
34second operand, of one of the two binary operators C<=~> and C<!~>,
35listed in L<perlop/Binding Operators>; and the pattern will have been
36converted from an ordinary string by one of the operators in
37L<perlop/"Regexp Quote-Like Operators">, like so:
38
39 $foo =~ m/abc/
40
41This evaluates to true if and only if the string in the variable C<$foo>
42contains somewhere in it, the sequence of characters "a", "b", then "c".
43(The C<=~ m>, or match operator, is described in
44L<perlop/m/PATTERN/msixpodualngc>.)
45
46Patterns that aren't already stored in some variable must be delimitted,
47at both ends, by delimitter characters. These are often, as in the
48example above, forward slashes, and the typical way a pattern is written
49in documentation is with those slashes. In most cases, the delimitter
50is the same character, fore and aft, but there are a few cases where a
51character looks like it has a mirror-image mate, where the opening
52version is the beginning delimiter, and the closing one is the ending
53delimiter, like
54
55 $foo =~ m<abc>
56
57Most times, the pattern is evaluated in double-quotish context, but it
58is possible to choose delimiters to force single-quotish, like
59
60 $foo =~ m'abc'
61
62If the pattern contains its delimiter within it, that delimiter must be
63escaped. Prefixing it with a backslash (I<e.g.>, C<"/foo\/bar/">)
64serves this purpose.
65
66Any single character in a pattern matches that same character in the
67target string, unless the character is a I<metacharacter> with a special
68meaning described in this document. A sequence of non-metacharacters
69matches the same sequence in the target string, as we saw above with
70C<m/abc/>.
71
04c2d19c 72Only a few characters (all of them being ASCII punctuation characters)
c57a3350
KW
73are metacharacters. The most commonly used one is a dot C<".">, which
74normally matches almost any character (including a dot itself).
75
76You can cause characters that normally function as metacharacters to be
77interpreted literally by prefixing them with a C<"\">, just like the
78pattern's delimiter must be escaped if it also occurs within the
79pattern. Thus, C<"\."> matches just a literal dot, C<"."> instead of
80its normal meaning. This means that the backslash is also a
81metacharacter, so C<"\\"> matches a single C<"\">. And a sequence that
82contains an escaped metacharacter matches the same sequence (but without
83the escape) in the target string. So, the pattern C</blur\\fl/> would
84match any target string that contains the sequence C<"blur\fl">.
85
86The metacharacter C<"|"> is used to match one thing or another. Thus
87
88 $foo =~ m/this|that/
89
90is TRUE if and only if C<$foo> contains either the sequence C<"this"> or
91the sequence C<"that">. Like all metacharacters, prefixing the C<"|">
92with a backslash makes it match the plain punctuation character; in its
93case, the VERTICAL LINE.
94
95 $foo =~ m/this\|that/
96
97is TRUE if and only if C<$foo> contains the sequence C<"this|that">.
98
99You aren't limited to just a single C<"|">.
100
101 $foo =~ m/fee|fie|foe|fum/
102
103is TRUE if and only if C<$foo> contains any of those 4 sequences from
104the children's story "Jack and the Beanstalk".
105
106As you can see, the C<"|"> binds less tightly than a sequence of
107ordinary characters. We can override this by using the grouping
108metacharacters, the parentheses C<"("> and C<")">.
109
110 $foo =~ m/th(is|at) thing/
111
112is TRUE if and only if C<$foo> contains either the sequence S<C<"this
113thing">> or the sequence S<C<"that thing">>. The portions of the string
114that match the portions of the pattern enclosed in parentheses are
115normally made available separately for use later in the pattern,
116substitution, or program. This is called "capturing", and it can get
117complicated. See L</Capture groups>.
118
119The first alternative includes everything from the last pattern
120delimiter (C<"(">, C<"(?:"> (described later), I<etc>. or the beginning
121of the pattern) up to the first C<"|">, and the last alternative
122contains everything from the last C<"|"> to the next closing pattern
123delimiter. That's why it's common practice to include alternatives in
124parentheses: to minimize confusion about where they start and end.
125
126Alternatives are tried from left to right, so the first
127alternative found for which the entire expression matches, is the one that
128is chosen. This means that alternatives are not necessarily greedy. For
129example: when matching C<foo|foot> against C<"barefoot">, only the C<"foo">
130part will match, as that is the first alternative tried, and it successfully
131matches the target string. (This might not seem important, but it is
132important when you are capturing matched text using parentheses.)
133
134Besides taking away the special meaning of a metacharacter, a prefixed
135backslash changes some letter and digit characters away from matching
136just themselves to instead have special meaning. These are called
137"escape sequences", and all such are described in L<perlrebackslash>. A
138backslash sequence (of a letter or digit) that doesn't currently have
139special meaning to Perl will raise a warning if warnings are enabled,
140as those are reserved for potential future use.
141
142One such sequence is C<\b>, which matches a boundary of some sort.
143C<\b{wb}> and a few others give specialized types of boundaries.
144(They are all described in detail starting at
145L<perlrebackslash/\b{}, \b, \B{}, \B>.) Note that these don't match
146characters, but the zero-width spaces between characters. They are an
147example of a L<zero-width assertion|/Assertions>. Consider again,
148
149 $foo =~ m/fee|fie|foe|fum/
150
151It evaluates to TRUE if, besides those 4 words, any of the sequences
152"feed", "field", "Defoe", "fume", and many others are in C<$foo>. By
153judicious use of C<\b> (or better (because it is designed to handle
154natural language) C<\b{wb}>), we can make sure that only the Giant's
155words are matched:
156
157 $foo =~ m/\b(fee|fie|foe|fum)\b/
158 $foo =~ m/\b{wb}(fee|fie|foe|fum)\b{wb}/
159
160The final example shows that the characters C<"{"> and C<"}"> are
161metacharacters.
162
163Another use for escape sequences is to specify characters that cannot
164(or which you prefer not to) be written literally. These are described
165in detail in L<perlrebackslash/Character Escapes>, but the next three
166paragraphs briefly describe some of them.
167
168Various control characters can be written in C language style: C<"\n">
169matches a newline, C<"\t"> a tab, C<"\r"> a carriage return, C<"\f"> a
170form feed, I<etc>.
171
172More generally, C<\I<nnn>>, where I<nnn> is a string of three octal
173digits, matches the character whose native code point is I<nnn>. You
174can easily run into trouble if you don't have exactly three digits. So
175always use three, or since Perl 5.14, you can use C<\o{...}> to specify
176any number of octal digits.
177
178Similarly, C<\xI<nn>>, where I<nn> are hexadecimal digits, matches the
179character whose native ordinal is I<nn>. Again, not using exactly two
180digits is a recipe for disaster, but you can use C<\x{...}> to specify
181any number of hex digits.
182
183Besides being a metacharacter, the C<"."> is an example of a "character
184class", something that can match any single character of a given set of
185them. In its case, the set is just about all possible characters. Perl
186predefines several character classes besides the C<".">; there is a
187separate reference page about just these, L<perlrecharclass>.
188
189You can define your own custom character classes, by putting into your
190pattern in the appropriate place(s), a list of all the characters you
191want in the set. You do this by enclosing the list within C<[]> bracket
192characters. These are called "bracketed character classes" when we are
193being precise, but often the word "bracketed" is dropped. (Dropping it
194usually doesn't cause confusion.) This means that the C<"["> character
195is another metacharacter. It doesn't match anything just by itelf; it
196is used only to tell Perl that what follows it is a bracketed character
197class. If you want to match a literal left square bracket, you must
198escape it, like C<"\[">. The matching C<"]"> is also a metacharacter;
199again it doesn't match anything by itself, but just marks the end of
200your custom class to Perl. It is an example of a "sometimes
201metacharacter". It isn't a metacharacter if there is no corresponding
202C<"[">, and matches its literal self:
203
204 print "]" =~ /]/; # prints 1
205
206The list of characters within the character class gives the set of
207characters matched by the class. C<"[abc]"> matches a single "a" or "b"
208or "c". But if the first character after the C<"["> is C<"^">, the
209class matches any character not in the list. Within a list, the C<"-">
210character specifies a range of characters, so that C<a-z> represents all
211characters between "a" and "z", inclusive. If you want either C<"-"> or
212C<"]"> itself to be a member of a class, put it at the start of the list
213(possibly after a C<"^">), or escape it with a backslash. C<"-"> is
214also taken literally when it is at the end of the list, just before the
215closing C<"]">. (The following all specify the same class of three
216characters: C<[-az]>, C<[az-]>, and C<[a\-z]>. All are different from
217C<[a-z]>, which specifies a class containing twenty-six characters, even
218on EBCDIC-based character sets.)
219
220There is lots more to bracketed character classes; full details are in
221L<perlrecharclass/Bracketed Character Classes>.
222
223=head3 Metacharacters
224X<metacharacter>
225X<\> X<^> X<.> X<$> X<|> X<(> X<()> X<[> X<[]>
226
227L</The Basics> introduced some of the metacharacters. This section
228gives them all. Most of them have the same meaning as in the I<egrep>
229command.
230
231Only the C<"\"> is always a metacharacter. The others are metacharacters
232just sometimes. The following tables lists all of them, summarizes
233their use, and gives the contexts where they are metacharacters.
234Outside those contexts or if prefixed by a C<"\">, they match their
235corresponding punctuation character. In some cases, their meaning
236varies depending on various pattern modifiers that alter the default
237behaviors. See L</Modifiers>.
238
239
240 PURPOSE WHERE
241 \ Escape the next character Always, except when
242 escaped by another \
243 ^ Match the beginning of the string Not in []
244 (or line, if /m is used)
245 ^ Complement the [] class At the beginning of []
246 . Match any single character except newline Not in []
247 (under /s, includes newline)
248 $ Match the end of the string Not in [], but can
249 (or before newline at the end of the mean interpolate a
250 string; or before any newline if /m is scalar
251 used)
252 | Alternation Not in []
253 () Grouping Not in []
254 [ Start Bracketed Character class Not in []
255 ] End Bracketed Character class Only in [], and
256 not first
257 * Matches the preceding element 0 or more Not in []
258 times
259 + Matches the preceding element 1 or more Not in []
260 times
261 ? Matches the preceding element 0 or 1 Not in []
262 times
263 { Starts a sequence that gives number(s) Not in []
264 of times the preceding element can be
265 matched
266 { when following certain escape sequences
267 starts a modifier to the meaning of the
268 sequence
269 } End sequence started by {
270 - Indicates a range Only in [] interior
271
272Notice that most of the metacharacters lose their special meaning when
273they occur in a bracketed character class, except C<"^"> has a different
274meaning when it is at the beginning of such a class. And C<"-"> and C<"]">
275are metacharacters only at restricted positions within bracketed
276character classes; while C<"}"> is a metacharacter only when closing a
277special construct started by C<"{">.
278
279In double-quotish context, as is usually the case, you need to be
280careful about C<"$"> and the non-metacharacter C<"@">. Those could
281interpolate variables, which may or may not be what you intended.
282
283These rules were designed for compactness of expression, rather than
284legibility and maintainability. The L</E<sol>x and E<sol>xx> pattern
285modifiers allow you to insert white space to improve readability. And
286use of S<C<L<re 'strict'|re/'strict' mode>>> adds extra checking to
287catch some typos that might silently compile into something unintended.
288
289By default, the C<"^"> character is guaranteed to match only the
290beginning of the string, the C<"$"> character only the end (or before the
291newline at the end), and Perl does certain optimizations with the
292assumption that the string contains only one line. Embedded newlines
293will not be matched by C<"^"> or C<"$">. You may, however, wish to treat a
294string as a multi-line buffer, such that the C<"^"> will match after any
295newline within the string (except if the newline is the last character in
296the string), and C<"$"> will match before any newline. At the
297cost of a little more overhead, you can do this by using the
298L</C<E<sol>m>> modifier on the pattern match operator. (Older programs
299did this by setting C<$*>, but this option was removed in perl 5.10.)
300X<^> X<$> X</m>
301
302To simplify multi-line substitutions, the C<"."> character never matches a
303newline unless you use the L<C<E<sol>s>|/s> modifier, which in effect tells
304Perl to pretend the string is a single line--even if it isn't.
305X<.> X</s>
306
0d017f4d
WL
307=head2 Modifiers
308
4cb6b395
KW
309=head3 Overview
310
3644e48f
KW
311The default behavior for matching can be changed, using various
312modifiers. Modifiers that relate to the interpretation of the pattern
313are listed just below. Modifiers that alter the way a pattern is used
314by Perl are detailed in L<perlop/"Regexp Quote-Like Operators"> and
1e66bd83 315L<perlop/"Gory details of parsing quoted constructs">.
a0d0e21e 316
55497cff
PP
317=over 4
318
7711f978 319=item B<C<m>>
d74e8afc 320X</m> X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
55497cff 321
3644e48f 322Treat the string being matched against as multiple lines. That is, change C<"^"> and C<"$"> from matching
1ca12bda
RS
323the start of the string's first line and the end of its last line to
324matching the start and end of each line within the string.
55497cff 325
7711f978 326=item B<C<s>>
d74e8afc
ITB
327X</s> X<regex, single-line> X<regexp, single-line>
328X<regular expression, single-line>
55497cff 329
7711f978 330Treat the string as single line. That is, change C<"."> to match any character
19799a22 331whatsoever, even a newline, which normally it would not match.
55497cff 332
7711f978
KW
333Used together, as C</ms>, they let the C<"."> match any character whatsoever,
334while still allowing C<"^"> and C<"$"> to match, respectively, just after
19799a22 335and just before newlines within the string.
7b8d334a 336
7711f978 337=item B<C<i>>
87e95b7f
YO
338X</i> X<regex, case-insensitive> X<regexp, case-insensitive>
339X<regular expression, case-insensitive>
340
7711f978
KW
341Do case-insensitive pattern matching. For example, "A" will match "a"
342under C</i>.
87e95b7f 343
5027a30b
KW
344If locale matching rules are in effect, the case map is taken from the
345current
17580e7a 346locale for code points less than 255, and from Unicode rules for larger
ed7efc79 347code points. However, matches that would cross the Unicode
7711f978
KW
348rules/non-Unicode rules boundary (ords 255/256) will not succeed, unless
349the locale is a UTF-8 one. See L<perllocale>.
ed7efc79 350
7711f978
KW
351There are a number of Unicode characters that match a sequence of
352multiple characters under C</i>. For example,
353C<LATIN SMALL LIGATURE FI> should match the sequence C<fi>. Perl is not
ed7efc79
KW
354currently able to do this when the multiple characters are in the pattern and
355are split between groupings, or when one or more are quantified. Thus
356
357 "\N{LATIN SMALL LIGATURE FI}" =~ /fi/i; # Matches
358 "\N{LATIN SMALL LIGATURE FI}" =~ /[fi][fi]/i; # Doesn't match!
359 "\N{LATIN SMALL LIGATURE FI}" =~ /fi*/i; # Doesn't match!
360
361 # The below doesn't match, and it isn't clear what $1 and $2 would
362 # be even if it did!!
363 "\N{LATIN SMALL LIGATURE FI}" =~ /(f)(i)/i; # Doesn't match!
364
9d53c457
KW
365Perl doesn't match multiple characters in a bracketed
366character class unless the character that maps to them is explicitly
367mentioned, and it doesn't match them at all if the character class is
368inverted, which otherwise could be highly confusing. See
369L<perlrecharclass/Bracketed Character Classes>, and
1f59b283
KW
370L<perlrecharclass/Negation>.
371
77c8f263 372=item B<C<x>> and B<C<xx>>
d74e8afc 373X</x>
55497cff
PP
374
375Extend your pattern's legibility by permitting whitespace and comments.
77c8f263 376Details in L</E<sol>x and E<sol>xx>
55497cff 377
7711f978 378=item B<C<p>>
87e95b7f
YO
379X</p> X<regex, preserve> X<regexp, preserve>
380
7711f978
KW
381Preserve the string matched such that C<${^PREMATCH}>, C<${^MATCH}>, and
382C<${^POSTMATCH}> are available for use after matching.
87e95b7f 383
13b0f67d 384In Perl 5.20 and higher this is ignored. Due to a new copy-on-write
7711f978 385mechanism, C<${^PREMATCH}>, C<${^MATCH}>, and C<${^POSTMATCH}> will be available
13b0f67d
DM
386after the match regardless of the modifier.
387
7711f978 388=item B<C<a>>, B<C<d>>, B<C<l>>, and B<C<u>>
b6fa137b
FC
389X</a> X</d> X</l> X</u>
390
850b7ec9 391These modifiers, all new in 5.14, affect which character-set rules
57fbbe96 392(Unicode, I<etc>.) are used, as described below in
ed7efc79 393L</Character set modifiers>.
b6fa137b 394
7711f978 395=item B<C<n>>
33be4c61
MH
396X</n> X<regex, non-capture> X<regexp, non-capture>
397X<regular expression, non-capture>
398
399Prevent the grouping metacharacters C<()> from capturing. This modifier,
57fbbe96 400new in 5.22, will stop C<$1>, C<$2>, I<etc>... from being filled in.
33be4c61
MH
401
402 "hello" =~ /(hi|hello)/; # $1 is "hello"
403 "hello" =~ /(hi|hello)/n; # $1 is undef
404
25941dca 405This is equivalent to putting C<?:> at the beginning of every capturing group:
33be4c61
MH
406
407 "hello" =~ /(?:hi|hello)/; # $1 is undef
408
409C</n> can be negated on a per-group basis. Alternatively, named captures
410may still be used.
411
412 "hello" =~ /(?-n:(hi|hello))/n; # $1 is "hello"
bdafd784
KW
413 "hello" =~ /(?<greet>hi|hello)/n; # $1 is "hello", $+{greet} is
414 # "hello"
33be4c61 415
7cf040c1
RS
416=item Other Modifiers
417
418There are a number of flags that can be found at the end of regular
419expression constructs that are I<not> generic regular expression flags, but
420apply to the operation being performed, like matching or substitution (C<m//>
421or C<s///> respectively).
422
423Flags described further in
424L<perlretut/"Using regular expressions in Perl"> are:
425
426 c - keep the current position during repeated matching
427 g - globally match the pattern repeatedly in the string
428
429Substitution-specific modifiers described in
33be4c61 430L<perlop/"s/PATTERN/REPLACEMENT/msixpodualngcer"> are:
171e7319 431
7cf040c1
RS
432 e - evaluate the right-hand side as an expression
433 ee - evaluate the right side as a string then eval the result
434 o - pretend to optimize your code, but actually introduce bugs
435 r - perform non-destructive substitution and return the new value
171e7319 436
55497cff 437=back
a0d0e21e 438
516074bb 439Regular expression modifiers are usually written in documentation
57fbbe96 440as I<e.g.>, "the C</x> modifier", even though the delimiter
4cb6b395 441in question might not really be a slash. The modifiers C</imnsxadlup>
ab7bb42d 442may also be embedded within the regular expression itself using
ed7efc79 443the C<(?...)> construct, see L</Extended Patterns> below.
b6fa137b 444
4cb6b395
KW
445=head3 Details on some modifiers
446
447Some of the modifiers require more explanation than given in the
448L</Overview> above.
449
77c8f263 450=head4 C</x> and C</xx>
ed7efc79 451
77c8f263 452A single C</x> tells
7b059540 453the regular expression parser to ignore most whitespace that is neither
7c688e65 454backslashed nor within a bracketed character class. You can use this to
2ab07670 455break up your regular expression into more readable parts.
7711f978 456Also, the C<"#"> character is treated as a metacharacter introducing a
7c688e65
KW
457comment that runs up to the pattern's closing delimiter, or to the end
458of the current line if the pattern extends onto the next line. Hence,
459this is very much like an ordinary Perl code comment. (You can include
460the closing delimiter within the comment only if you precede it with a
461backslash, so be careful!)
462
463Use of C</x> means that if you want real
7711f978 464whitespace or C<"#"> characters in the pattern (outside a bracketed character
7c688e65 465class, which is unaffected by C</x>), then you'll either have to
7b059540 466escape them (using backslashes or C<\Q...\E>) or encode them using octal,
7c688e65 467hex, or C<\N{}> escapes.
8be3c4ca
KW
468It is ineffective to try to continue a comment onto the next line by
469escaping the C<\n> with a backslash or C<\Q>.
7c688e65
KW
470
471You can use L</(?#text)> to create a comment that ends earlier than the
472end of the current line, but C<text> also can't contain the closing
473delimiter unless escaped with a backslash.
474
57fbbe96 475A common pitfall is to forget that C<"#"> characters begin a comment under
2ab07670
KW
476C</x> and are not matched literally. Just keep that in mind when trying
477to puzzle out why a particular C</x> pattern isn't working as expected.
478
57fbbe96 479Starting in Perl v5.26, if the modifier has a second C<"x"> within it,
77c8f263
KW
480it does everything that a single C</x> does, but additionally
481non-backslashed SPACE and TAB characters within bracketed character
482classes are also generally ignored, and hence can be added to make the
483classes more readable.
484
485 / [d-e g-i 3-7]/xx
486 /[ ! @ " # $ % ^ & * () = ? <> ' ]/xx
487
488may be easier to grasp than the squashed equivalents
489
490 /[d-eg-i3-7]/
491 /[!@"#$%^&*()=?<>']/
492
7c688e65
KW
493Taken together, these features go a long way towards
494making Perl's regular expressions more readable. Here's an example:
495
496 # Delete (most) C comments.
497 $program =~ s {
498 /\* # Match the opening delimiter.
499 .*? # Match a minimal number of characters.
500 \*/ # Match the closing delimiter.
501 } []gsx;
502
503Note that anything inside
7651b971 504a C<\Q...\E> stays unaffected by C</x>. And note that C</x> doesn't affect
0b928c2f 505space interpretation within a single multi-character construct. For
7651b971 506example in C<\x{...}>, regardless of the C</x> modifier, there can be no
9bb1f947 507spaces. Same for a L<quantifier|/Quantifiers> such as C<{3}> or
b7f36610 508C<{5,}>. Similarly, C<(?:...)> can't have a space between the C<"(">,
7711f978 509C<"?">, and C<":">. Within any delimiters for such a
f9e949fd
KW
510construct, allowed spaces are not affected by C</x>, and depend on the
511construct. For example, C<\x{...}> can't have spaces because hexadecimal
512numbers don't have spaces in them. But, Unicode properties can have spaces, so
0b928c2f 513in C<\p{...}> there can be spaces that follow the Unicode rules, for which see
9bb1f947 514L<perluniprops/Properties accessible through \p{} and \P{}>.
d74e8afc 515X</x>
a0d0e21e 516
8373491a
KW
517The set of characters that are deemed whitespace are those that Unicode
518calls "Pattern White Space", namely:
519
520 U+0009 CHARACTER TABULATION
521 U+000A LINE FEED
522 U+000B LINE TABULATION
523 U+000C FORM FEED
524 U+000D CARRIAGE RETURN
525 U+0020 SPACE
526 U+0085 NEXT LINE
527 U+200E LEFT-TO-RIGHT MARK
528 U+200F RIGHT-TO-LEFT MARK
529 U+2028 LINE SEPARATOR
530 U+2029 PARAGRAPH SEPARATOR
531
4cb6b395 532=head4 Character set modifiers
ed7efc79
KW
533
534C</d>, C</u>, C</a>, and C</l>, available starting in 5.14, are called
850b7ec9 535the character set modifiers; they affect the character set rules
ed7efc79
KW
536used for the regular expression.
537
808432af
KW
538The C</d>, C</u>, and C</l> modifiers are not likely to be of much use
539to you, and so you need not worry about them very much. They exist for
540Perl's internal use, so that complex regular expression data structures
541can be automatically serialized and later exactly reconstituted,
542including all their nuances. But, since Perl can't keep a secret, and
543there may be rare instances where they are useful, they are documented
544here.
ed7efc79 545
808432af
KW
546The C</a> modifier, on the other hand, may be useful. Its purpose is to
547allow code that is to work mostly on ASCII data to not have to concern
548itself with Unicode.
ca9560b2 549
808432af
KW
550Briefly, C</l> sets the character set to that of whatever B<L>ocale is in
551effect at the time of the execution of the pattern match.
ca9560b2 552
808432af
KW
553C</u> sets the character set to B<U>nicode.
554
555C</a> also sets the character set to Unicode, BUT adds several
556restrictions for B<A>SCII-safe matching.
557
558C</d> is the old, problematic, pre-5.14 B<D>efault character set
559behavior. Its only use is to force that old behavior.
560
561At any given time, exactly one of these modifiers is in effect. Their
562existence allows Perl to keep the originally compiled behavior of a
563regular expression, regardless of what rules are in effect when it is
564actually executed. And if it is interpolated into a larger regex, the
565original's rules continue to apply to it, and only it.
566
567The C</l> and C</u> modifiers are automatically selected for
568regular expressions compiled within the scope of various pragmas,
569and we recommend that in general, you use those pragmas instead of
570specifying these modifiers explicitly. For one thing, the modifiers
571affect only pattern matching, and do not extend to even any replacement
7711f978 572done, whereas using the pragmas gives consistent results for all
808432af
KW
573appropriate operations within their scopes. For example,
574
575 s/foo/\Ubar/il
576
577will match "foo" using the locale's rules for case-insensitive matching,
578but the C</l> does not affect how the C<\U> operates. Most likely you
579want both of them to use locale rules. To do this, instead compile the
580regular expression within the scope of C<use locale>. This both
ce4fe27b
KW
581implicitly adds the C</l>, and applies locale rules to the C<\U>. The
582lesson is to C<use locale>, and not C</l> explicitly.
808432af
KW
583
584Similarly, it would be better to use C<use feature 'unicode_strings'>
585instead of,
586
587 s/foo/\Lbar/iu
588
589to get Unicode rules, as the C<\L> in the former (but not necessarily
590the latter) would also use Unicode rules.
591
592More detail on each of the modifiers follows. Most likely you don't
593need to know this detail for C</l>, C</u>, and C</d>, and can skip ahead
594to L<E<sol>a|/E<sol>a (and E<sol>aa)>.
ca9560b2 595
ed7efc79
KW
596=head4 /l
597
598means to use the current locale's rules (see L<perllocale>) when pattern
599matching. For example, C<\w> will match the "word" characters of that
600locale, and C<"/i"> case-insensitive matching will match according to
601the locale's case folding rules. The locale used will be the one in
602effect at the time of execution of the pattern match. This may not be
603the same as the compilation-time locale, and can differ from one match
604to another if there is an intervening call of the
b6fa137b 605L<setlocale() function|perllocale/The setlocale function>.
ed7efc79 606
7711f978
KW
607Prior to v5.20, Perl did not support multi-byte locales. Starting then,
608UTF-8 locales are supported. No other multi byte locales are ever
609likely to be supported. However, in all locales, one can have code
610points above 255 and these will always be treated as Unicode no matter
611what locale is in effect.
31f05a37 612
ed7efc79 613Under Unicode rules, there are a few case-insensitive matches that cross
31f05a37
KW
614the 255/256 boundary. Except for UTF-8 locales in Perls v5.20 and
615later, these are disallowed under C</l>. For example, 0xFF (on ASCII
616platforms) does not caselessly match the character at 0x178, C<LATIN
617CAPITAL LETTER Y WITH DIAERESIS>, because 0xFF may not be C<LATIN SMALL
618LETTER Y WITH DIAERESIS> in the current locale, and Perl has no way of
619knowing if that character even exists in the locale, much less what code
620point it is.
621
622In a UTF-8 locale in v5.20 and later, the only visible difference
623between locale and non-locale in regular expressions should be tainting
624(see L<perlsec>).
ed7efc79
KW
625
626This modifier may be specified to be the default by C<use locale>, but
627see L</Which character set modifier is in effect?>.
b6fa137b
FC
628X</l>
629
ed7efc79
KW
630=head4 /u
631
632means to use Unicode rules when pattern matching. On ASCII platforms,
633this means that the code points between 128 and 255 take on their
808432af
KW
634Latin-1 (ISO-8859-1) meanings (which are the same as Unicode's).
635(Otherwise Perl considers their meanings to be undefined.) Thus,
636under this modifier, the ASCII platform effectively becomes a Unicode
637platform; and hence, for example, C<\w> will match any of the more than
638100_000 word characters in Unicode.
ed7efc79
KW
639
640Unlike most locales, which are specific to a language and country pair,
516074bb
KW
641Unicode classifies all the characters that are letters I<somewhere> in
642the world as
ed7efc79
KW
643C<\w>. For example, your locale might not think that C<LATIN SMALL
644LETTER ETH> is a letter (unless you happen to speak Icelandic), but
645Unicode does. Similarly, all the characters that are decimal digits
646somewhere in the world will match C<\d>; this is hundreds, not 10,
647possible matches. And some of those digits look like some of the 10
648ASCII digits, but mean a different number, so a human could easily think
649a number is a different quantity than it really is. For example,
650C<BENGALI DIGIT FOUR> (U+09EA) looks very much like an
651C<ASCII DIGIT EIGHT> (U+0038). And, C<\d+>, may match strings of digits
652that are a mixture from different writing systems, creating a security
67592e11 653issue. L<Unicode::UCD/num()> can be used to sort
516074bb
KW
654this out. Or the C</a> modifier can be used to force C<\d> to match
655just the ASCII 0 through 9.
ed7efc79 656
516074bb
KW
657Also, under this modifier, case-insensitive matching works on the full
658set of Unicode
ed7efc79
KW
659characters. The C<KELVIN SIGN>, for example matches the letters "k" and
660"K"; and C<LATIN SMALL LIGATURE FF> matches the sequence "ff", which,
661if you're not prepared, might make it look like a hexadecimal constant,
662presenting another potential security issue. See
663L<http://unicode.org/reports/tr36> for a detailed discussion of Unicode
664security issues.
665
ed7efc79 666This modifier may be specified to be the default by C<use feature
66cbab2c
KW
667'unicode_strings>, C<use locale ':not_characters'>, or
668C<L<use 5.012|perlfunc/use VERSION>> (or higher),
808432af 669but see L</Which character set modifier is in effect?>.
b6fa137b
FC
670X</u>
671
ed7efc79
KW
672=head4 /d
673
674This modifier means to use the "Default" native rules of the platform
675except when there is cause to use Unicode rules instead, as follows:
676
677=over 4
678
679=item 1
680
681the target string is encoded in UTF-8; or
682
683=item 2
684
685the pattern is encoded in UTF-8; or
686
687=item 3
688
689the pattern explicitly mentions a code point that is above 255 (say by
690C<\x{100}>); or
691
692=item 4
b6fa137b 693
ed7efc79
KW
694the pattern uses a Unicode name (C<\N{...}>); or
695
696=item 5
697
ce4fe27b 698the pattern uses a Unicode property (C<\p{...}> or C<\P{...}>); or
9d1a5160
KW
699
700=item 6
701
64935bc6
KW
702the pattern uses a Unicode break (C<\b{...}> or C<\B{...}>); or
703
704=item 7
705
9d1a5160 706the pattern uses L</C<(?[ ])>>
ed7efc79
KW
707
708=back
709
710Another mnemonic for this modifier is "Depends", as the rules actually
711used depend on various things, and as a result you can get unexpected
808432af
KW
712results. See L<perlunicode/The "Unicode Bug">. The Unicode Bug has
713become rather infamous, leading to yet another (printable) name for this
714modifier, "Dodgy".
ed7efc79 715
4b9734bf
KW
716Unless the pattern or string are encoded in UTF-8, only ASCII characters
717can match positively.
ed7efc79
KW
718
719Here are some examples of how that works on an ASCII platform:
720
721 $str = "\xDF"; # $str is not in UTF-8 format.
722 $str =~ /^\w/; # No match, as $str isn't in UTF-8 format.
723 $str .= "\x{0e0b}"; # Now $str is in UTF-8 format.
724 $str =~ /^\w/; # Match! $str is now in UTF-8 format.
725 chop $str;
726 $str =~ /^\w/; # Still a match! $str remains in UTF-8 format.
727
808432af
KW
728This modifier is automatically selected by default when none of the
729others are, so yet another name for it is "Default".
730
731Because of the unexpected behaviors associated with this modifier, you
7711f978
KW
732probably should only explicitly use it to maintain weird backward
733compatibilities.
808432af
KW
734
735=head4 /a (and /aa)
736
3644e48f
KW
737This modifier stands for ASCII-restrict (or ASCII-safe). This modifier
738may be doubled-up to increase its effect.
808432af
KW
739
740When it appears singly, it causes the sequences C<\d>, C<\s>, C<\w>, and
741the Posix character classes to match only in the ASCII range. They thus
742revert to their pre-5.6, pre-Unicode meanings. Under C</a>, C<\d>
743always means precisely the digits C<"0"> to C<"9">; C<\s> means the five
779cf272
KW
744characters C<[ \f\n\r\t]>, and starting in Perl v5.18, the vertical tab;
745C<\w> means the 63 characters
808432af
KW
746C<[A-Za-z0-9_]>; and likewise, all the Posix classes such as
747C<[[:print:]]> match only the appropriate ASCII-range characters.
748
749This modifier is useful for people who only incidentally use Unicode,
750and who do not wish to be burdened with its complexities and security
751concerns.
752
753With C</a>, one can write C<\d> with confidence that it will only match
754ASCII characters, and should the need arise to match beyond ASCII, you
755can instead use C<\p{Digit}> (or C<\p{Word}> for C<\w>). There are
756similar C<\p{...}> constructs that can match beyond ASCII both white
757space (see L<perlrecharclass/Whitespace>), and Posix classes (see
758L<perlrecharclass/POSIX Character Classes>). Thus, this modifier
759doesn't mean you can't use Unicode, it means that to get Unicode
760matching you must explicitly use a construct (C<\p{}>, C<\P{}>) that
761signals Unicode.
762
763As you would expect, this modifier causes, for example, C<\D> to mean
764the same thing as C<[^0-9]>; in fact, all non-ASCII characters match
765C<\D>, C<\S>, and C<\W>. C<\b> still means to match at the boundary
766between C<\w> and C<\W>, using the C</a> definitions of them (similarly
767for C<\B>).
768
769Otherwise, C</a> behaves like the C</u> modifier, in that
850b7ec9 770case-insensitive matching uses Unicode rules; for example, "k" will
808432af
KW
771match the Unicode C<\N{KELVIN SIGN}> under C</i> matching, and code
772points in the Latin1 range, above ASCII will have Unicode rules when it
773comes to case-insensitive matching.
774
775To forbid ASCII/non-ASCII matches (like "k" with C<\N{KELVIN SIGN}>),
7711f978 776specify the C<"a"> twice, for example C</aai> or C</aia>. (The first
57fbbe96 777occurrence of C<"a"> restricts the C<\d>, I<etc>., and the second occurrence
808432af
KW
778adds the C</i> restrictions.) But, note that code points outside the
779ASCII range will use Unicode rules for C</i> matching, so the modifier
780doesn't really restrict things to just ASCII; it just forbids the
781intermixing of ASCII and non-ASCII.
782
783To summarize, this modifier provides protection for applications that
784don't wish to be exposed to all of Unicode. Specifying it twice
785gives added protection.
786
787This modifier may be specified to be the default by C<use re '/a'>
788or C<use re '/aa'>. If you do so, you may actually have occasion to use
31dc26d6 789the C</u> modifier explicitly if there are a few regular expressions
808432af
KW
790where you do want full Unicode rules (but even here, it's best if
791everything were under feature C<"unicode_strings">, along with the
792C<use re '/aa'>). Also see L</Which character set modifier is in
793effect?>.
794X</a>
795X</aa>
796
ed7efc79
KW
797=head4 Which character set modifier is in effect?
798
799Which of these modifiers is in effect at any given point in a regular
808432af
KW
800expression depends on a fairly complex set of interactions. These have
801been designed so that in general you don't have to worry about it, but
802this section gives the gory details. As
ed7efc79
KW
803explained below in L</Extended Patterns> it is possible to explicitly
804specify modifiers that apply only to portions of a regular expression.
805The innermost always has priority over any outer ones, and one applying
6368643f
KW
806to the whole expression has priority over any of the default settings that are
807described in the remainder of this section.
ed7efc79 808
916cec3f 809The C<L<use re 'E<sol>foo'|re/"'/flags' mode">> pragma can be used to set
ed7efc79
KW
810default modifiers (including these) for regular expressions compiled
811within its scope. This pragma has precedence over the other pragmas
516074bb 812listed below that also change the defaults.
ed7efc79
KW
813
814Otherwise, C<L<use locale|perllocale>> sets the default modifier to C</l>;
66cbab2c 815and C<L<use feature 'unicode_strings|feature>>, or
ed7efc79
KW
816C<L<use 5.012|perlfunc/use VERSION>> (or higher) set the default to
817C</u> when not in the same scope as either C<L<use locale|perllocale>>
66cbab2c
KW
818or C<L<use bytes|bytes>>.
819(C<L<use locale ':not_characters'|perllocale/Unicode and UTF-8>> also
820sets the default to C</u>, overriding any plain C<use locale>.)
821Unlike the mechanisms mentioned above, these
6368643f
KW
822affect operations besides regular expressions pattern matching, and so
823give more consistent results with other operators, including using
57fbbe96 824C<\U>, C<\l>, I<etc>. in substitution replacements.
ed7efc79
KW
825
826If none of the above apply, for backwards compatibility reasons, the
827C</d> modifier is the one in effect by default. As this can lead to
828unexpected results, it is best to specify which other rule set should be
829used.
830
831=head4 Character set modifier behavior prior to Perl 5.14
832
833Prior to 5.14, there were no explicit modifiers, but C</l> was implied
834for regexes compiled within the scope of C<use locale>, and C</d> was
835implied otherwise. However, interpolating a regex into a larger regex
836would ignore the original compilation in favor of whatever was in effect
837at the time of the second compilation. There were a number of
838inconsistencies (bugs) with the C</d> modifier, where Unicode rules
839would be used when inappropriate, and vice versa. C<\p{}> did not imply
840Unicode rules, and neither did all occurrences of C<\N{}>, until 5.12.
b6fa137b 841
a0d0e21e
LW
842=head2 Regular Expressions
843
04838cea
RGS
844=head3 Quantifiers
845
3644e48f
KW
846Quantifiers are used when a particular portion of a pattern needs to
847match a certain number (or numbers) of times. If there isn't a
848quantifier the number of times to match is exactly one. The following
849standard quantifiers are recognized:
d74e8afc 850X<metacharacter> X<quantifier> X<*> X<+> X<?> X<{n}> X<{n,}> X<{n,m}>
a0d0e21e 851
f793d64a
KW
852 * Match 0 or more times
853 + Match 1 or more times
854 ? Match 1 or 0 times
855 {n} Match exactly n times
856 {n,} Match at least n times
857 {n,m} Match at least n but not more than m times
a0d0e21e 858
3644e48f
KW
859(If a non-escaped curly bracket occurs in a context other than one of
860the quantifiers listed above, where it does not form part of a
861backslashed sequence like C<\x{...}>, it is either a fatal syntax error,
862or treated as a regular character, generally with a deprecation warning
863raised. To escape it, you can precede it with a backslash (C<"\{">) or
864enclose it within square brackets (C<"[{]">).
865This change will allow for future syntax extensions (like making the
866lower bound of a quantifier optional), and better error checking of
867quantifiers).
9af81bfe 868
7711f978
KW
869The C<"*"> quantifier is equivalent to C<{0,}>, the C<"+">
870quantifier to C<{1,}>, and the C<"?"> quantifier to C<{0,1}>. I<n> and I<m> are limited
d0b16107 871to non-negative integral values less than a preset limit defined when perl is built.
9c79236d
GS
872This is usually 32766 on the most common platforms. The actual limit can
873be seen in the error message generated by code such as this:
874
820475bd 875 $_ **= $_ , / {$_} / for 2 .. 42;
a0d0e21e 876
54310121
PP
877By default, a quantified subpattern is "greedy", that is, it will match as
878many times as possible (given a particular starting location) while still
879allowing the rest of the pattern to match. If you want it to match the
7711f978 880minimum number of times possible, follow the quantifier with a C<"?">. Note
54310121 881that the meanings don't change, just the "greediness":
0d017f4d 882X<metacharacter> X<greedy> X<greediness>
d74e8afc 883X<?> X<*?> X<+?> X<??> X<{n}?> X<{n,}?> X<{n,m}?>
a0d0e21e 884
f793d64a
KW
885 *? Match 0 or more times, not greedily
886 +? Match 1 or more times, not greedily
887 ?? Match 0 or 1 time, not greedily
0b928c2f 888 {n}? Match exactly n times, not greedily (redundant)
f793d64a
KW
889 {n,}? Match at least n times, not greedily
890 {n,m}? Match at least n but not more than m times, not greedily
a0d0e21e 891
5f3789aa 892Normally when a quantified subpattern does not allow the rest of the
b9b4dddf 893overall pattern to match, Perl will backtrack. However, this behaviour is
0d017f4d 894sometimes undesirable. Thus Perl provides the "possessive" quantifier form
b9b4dddf
YO
895as well.
896
f793d64a
KW
897 *+ Match 0 or more times and give nothing back
898 ++ Match 1 or more times and give nothing back
899 ?+ Match 0 or 1 time and give nothing back
900 {n}+ Match exactly n times and give nothing back (redundant)
901 {n,}+ Match at least n times and give nothing back
902 {n,m}+ Match at least n but not more than m times and give nothing back
b9b4dddf
YO
903
904For instance,
905
906 'aaaa' =~ /a++a/
907
57fbbe96 908will never match, as the C<a++> will gobble up all the C<"a">'s in the
b9b4dddf
YO
909string and won't leave any for the remaining part of the pattern. This
910feature can be extremely useful to give perl hints about where it
911shouldn't backtrack. For instance, the typical "match a double-quoted
912string" problem can be most efficiently performed when written as:
913
914 /"(?:[^"\\]++|\\.)*+"/
915
0d017f4d 916as we know that if the final quote does not match, backtracking will not
0b928c2f
FC
917help. See the independent subexpression
918L</C<< (?>pattern) >>> for more details;
b9b4dddf
YO
919possessive quantifiers are just syntactic sugar for that construct. For
920instance the above example could also be written as follows:
921
922 /"(?>(?:(?>[^"\\]+)|\\.)*)"/
923
5f3789aa
YO
924Note that the possessive quantifier modifier can not be be combined
925with the non-greedy modifier. This is because it would make no sense.
926Consider the follow equivalency table:
927
928 Illegal Legal
929 ------------ ------
930 X??+ X{0}
931 X+?+ X{1}
932 X{min,max}?+ X{min}
933
04838cea
RGS
934=head3 Escape sequences
935
0b928c2f 936Because patterns are processed as double-quoted strings, the following
a0d0e21e
LW
937also work:
938
f793d64a
KW
939 \t tab (HT, TAB)
940 \n newline (LF, NL)
941 \r return (CR)
942 \f form feed (FF)
943 \a alarm (bell) (BEL)
944 \e escape (think troff) (ESC)
f793d64a 945 \cK control char (example: VT)
dc0d9c48 946 \x{}, \x00 character whose ordinal is the given hexadecimal number
fb121860 947 \N{name} named Unicode character or character sequence
f793d64a 948 \N{U+263D} Unicode character (example: FIRST QUARTER MOON)
f0a2b745 949 \o{}, \000 character whose ordinal is the given octal number
f793d64a
KW
950 \l lowercase next char (think vi)
951 \u uppercase next char (think vi)
ad81d09f
KE
952 \L lowercase until \E (think vi)
953 \U uppercase until \E (think vi)
954 \Q quote (disable) pattern metacharacters until \E
f793d64a 955 \E end either case modification or quoted section, think vi
a0d0e21e 956
9bb1f947 957Details are in L<perlop/Quote and Quote-like Operators>.
1d2dff63 958
e1d1eefb 959=head3 Character Classes and other Special Escapes
04838cea 960
a0d0e21e 961In addition, Perl defines the following:
d0b16107 962X<\g> X<\k> X<\K> X<backreference>
a0d0e21e 963
f793d64a
KW
964 Sequence Note Description
965 [...] [1] Match a character according to the rules of the
966 bracketed character class defined by the "...".
967 Example: [a-z] matches "a" or "b" or "c" ... or "z"
968 [[:...:]] [2] Match a character according to the rules of the POSIX
969 character class "..." within the outer bracketed
970 character class. Example: [[:upper:]] matches any
971 uppercase character.
572224ce 972 (?[...]) [8] Extended bracketed character class
d35dd6c6
KW
973 \w [3] Match a "word" character (alphanumeric plus "_", plus
974 other connector punctuation chars plus Unicode
0b928c2f 975 marks)
f793d64a
KW
976 \W [3] Match a non-"word" character
977 \s [3] Match a whitespace character
978 \S [3] Match a non-whitespace character
979 \d [3] Match a decimal digit character
980 \D [3] Match a non-digit character
981 \pP [3] Match P, named property. Use \p{Prop} for longer names
982 \PP [3] Match non-P
983 \X [4] Match Unicode "eXtended grapheme cluster"
c27a5cfe 984 \1 [5] Backreference to a specific capture group or buffer.
f793d64a
KW
985 '1' may actually be any positive integer.
986 \g1 [5] Backreference to a specific or previous group,
987 \g{-1} [5] The number may be negative indicating a relative
c27a5cfe 988 previous group and may optionally be wrapped in
f793d64a
KW
989 curly brackets for safer parsing.
990 \g{name} [5] Named backreference
991 \k<name> [5] Named backreference
992 \K [6] Keep the stuff left of the \K, don't include it in $&
2171640d 993 \N [7] Any character but \n. Not affected by /s modifier
f793d64a
KW
994 \v [3] Vertical whitespace
995 \V [3] Not vertical whitespace
996 \h [3] Horizontal whitespace
997 \H [3] Not horizontal whitespace
998 \R [4] Linebreak
e1d1eefb 999
9bb1f947
KW
1000=over 4
1001
1002=item [1]
1003
1004See L<perlrecharclass/Bracketed Character Classes> for details.
df225385 1005
9bb1f947 1006=item [2]
b8c5462f 1007
9bb1f947 1008See L<perlrecharclass/POSIX Character Classes> for details.
b8c5462f 1009
9bb1f947 1010=item [3]
5496314a 1011
9bb1f947 1012See L<perlrecharclass/Backslash sequences> for details.
5496314a 1013
9bb1f947 1014=item [4]
5496314a 1015
9bb1f947 1016See L<perlrebackslash/Misc> for details.
d0b16107 1017
9bb1f947 1018=item [5]
b8c5462f 1019
c27a5cfe 1020See L</Capture groups> below for details.
93733859 1021
9bb1f947 1022=item [6]
b8c5462f 1023
9bb1f947
KW
1024See L</Extended Patterns> below for details.
1025
1026=item [7]
1027
1028Note that C<\N> has two meanings. When of the form C<\N{NAME}>, it matches the
fb121860
KW
1029character or character sequence whose name is C<NAME>; and similarly
1030when of the form C<\N{U+I<hex>}>, it matches the character whose Unicode
1031code point is I<hex>. Otherwise it matches any character but C<\n>.
9bb1f947 1032
572224ce
KW
1033=item [8]
1034
1035See L<perlrecharclass/Extended Bracketed Character Classes> for details.
1036
9bb1f947 1037=back
d0b16107 1038
04838cea
RGS
1039=head3 Assertions
1040
c57a3350
KW
1041Besides L<C<"^"> and C<"$">|/Metacharacters>, Perl defines the following
1042zero-width assertions:
d74e8afc
ITB
1043X<zero-width assertion> X<assertion> X<regex, zero-width assertion>
1044X<regexp, zero-width assertion>
1045X<regular expression, zero-width assertion>
1046X<\b> X<\B> X<\A> X<\Z> X<\z> X<\G>
a0d0e21e 1047
c57a3350
KW
1048 \b{} Match at Unicode boundary of specified type
1049 \B{} Match where corresponding \b{} doesn't match
1050 \b Match a \w\W or \W\w boundary
1051 \B Match except at a \w\W or \W\w boundary
1052 \A Match only at beginning of string
1053 \Z Match only at end of string, or before newline at the end
1054 \z Match only at end of string
1055 \G Match only at pos() (e.g. at the end-of-match position
9da458fc 1056 of prior m//g)
a0d0e21e 1057
64935bc6
KW
1058A Unicode boundary (C<\b{}>), available starting in v5.22, is a spot
1059between two characters, or before the first character in the string, or
1060after the final character in the string where certain criteria defined
1061by Unicode are met. See L<perlrebackslash/\b{}, \b, \B{}, \B> for
1062details.
1063
14218588 1064A word boundary (C<\b>) is a spot between two characters
19799a22
GS
1065that has a C<\w> on one side of it and a C<\W> on the other side
1066of it (in either order), counting the imaginary characters off the
1067beginning and end of the string as matching a C<\W>. (Within
1068character classes C<\b> represents backspace rather than a word
1069boundary, just as it normally does in any double-quoted string.)
7711f978 1070The C<\A> and C<\Z> are just like C<"^"> and C<"$">, except that they
19799a22 1071won't match multiple times when the C</m> modifier is used, while
7711f978 1072C<"^"> and C<"$"> will match at every internal line boundary. To match
19799a22
GS
1073the actual end of the string and not ignore an optional trailing
1074newline, use C<\z>.
d74e8afc 1075X<\b> X<\A> X<\Z> X<\z> X</m>
19799a22
GS
1076
1077The C<\G> assertion can be used to chain global matches (using
1078C<m//g>), as described in L<perlop/"Regexp Quote-Like Operators">.
1079It is also useful when writing C<lex>-like scanners, when you have
1080several patterns that you want to match against consequent substrings
0b928c2f 1081of your string; see the previous reference. The actual location
19799a22 1082where C<\G> will match can also be influenced by using C<pos()> as
58e23c8d 1083an lvalue: see L<perlfunc/pos>. Note that the rule for zero-length
0b928c2f
FC
1084matches (see L</"Repeated Patterns Matching a Zero-length Substring">)
1085is modified somewhat, in that contents to the left of C<\G> are
58e23c8d
YO
1086not counted when determining the length of the match. Thus the following
1087will not match forever:
d74e8afc 1088X<\G>
c47ff5f1 1089
e761bb84
CO
1090 my $string = 'ABC';
1091 pos($string) = 1;
1092 while ($string =~ /(.\G)/g) {
1093 print $1;
1094 }
58e23c8d
YO
1095
1096It will print 'A' and then terminate, as it considers the match to
1097be zero-width, and thus will not match at the same position twice in a
1098row.
1099
1100It is worth noting that C<\G> improperly used can result in an infinite
1101loop. Take care when using patterns that include C<\G> in an alternation.
1102
d5e7783a
DM
1103Note also that C<s///> will refuse to overwrite part of a substitution
1104that has already been replaced; so for example this will stop after the
1105first iteration, rather than iterating its way backwards through the
1106string:
1107
1108 $_ = "123456789";
1109 pos = 6;
1110 s/.(?=.\G)/X/g;
1111 print; # prints 1234X6789, not XXXXX6789
1112
1113
c27a5cfe 1114=head3 Capture groups
04838cea 1115
3644e48f 1116The grouping construct C<( ... )> creates capture groups (also referred to as
c27a5cfe 1117capture buffers). To refer to the current contents of a group later on, within
d8b950dc
KW
1118the same pattern, use C<\g1> (or C<\g{1}>) for the first, C<\g2> (or C<\g{2}>)
1119for the second, and so on.
1120This is called a I<backreference>.
d74e8afc 1121X<regex, capture buffer> X<regexp, capture buffer>
c27a5cfe 1122X<regex, capture group> X<regexp, capture group>
d74e8afc 1123X<regular expression, capture buffer> X<backreference>
c27a5cfe 1124X<regular expression, capture group> X<backreference>
1f1031fe 1125X<\g{1}> X<\g{-1}> X<\g{name}> X<relative backreference> X<named backreference>
d8b950dc
KW
1126X<named capture buffer> X<regular expression, named capture buffer>
1127X<named capture group> X<regular expression, named capture group>
1128X<%+> X<$+{name}> X<< \k<name> >>
1129There is no limit to the number of captured substrings that you may use.
57fbbe96 1130Groups are numbered with the leftmost open parenthesis being number 1, I<etc>. If
d8b950dc
KW
1131a group did not match, the associated backreference won't match either. (This
1132can happen if the group is optional, or in a different branch of an
1133alternation.)
57fbbe96 1134You can omit the C<"g">, and write C<"\1">, I<etc>, but there are some issues with
d8b950dc
KW
1135this form, described below.
1136
1137You can also refer to capture groups relatively, by using a negative number, so
1138that C<\g-1> and C<\g{-1}> both refer to the immediately preceding capture
1139group, and C<\g-2> and C<\g{-2}> both refer to the group before it. For
1140example:
5624f11d
YO
1141
1142 /
c27a5cfe
KW
1143 (Y) # group 1
1144 ( # group 2
1145 (X) # group 3
1146 \g{-1} # backref to group 3
1147 \g{-3} # backref to group 1
5624f11d
YO
1148 )
1149 /x
1150
d8b950dc
KW
1151would match the same as C</(Y) ( (X) \g3 \g1 )/x>. This allows you to
1152interpolate regexes into larger regexes and not have to worry about the
1153capture groups being renumbered.
1154
1155You can dispense with numbers altogether and create named capture groups.
1156The notation is C<(?E<lt>I<name>E<gt>...)> to declare and C<\g{I<name>}> to
1157reference. (To be compatible with .Net regular expressions, C<\g{I<name>}> may
1158also be written as C<\k{I<name>}>, C<\kE<lt>I<name>E<gt>> or C<\k'I<name>'>.)
1159I<name> must not begin with a number, nor contain hyphens.
1160When different groups within the same pattern have the same name, any reference
1161to that name assumes the leftmost defined group. Named groups count in
1162absolute and relative numbering, and so can also be referred to by those
1163numbers.
1164(It's possible to do things with named capture groups that would otherwise
1165require C<(??{})>.)
1166
1167Capture group contents are dynamically scoped and available to you outside the
1168pattern until the end of the enclosing block or until the next successful
1169match, whichever comes first. (See L<perlsyn/"Compound Statements">.)
1170You can refer to them by absolute number (using C<"$1"> instead of C<"\g1">,
57fbbe96 1171I<etc>); or by name via the C<%+> hash, using C<"$+{I<name>}">.
d8b950dc
KW
1172
1173Braces are required in referring to named capture groups, but are optional for
1174absolute or relative numbered ones. Braces are safer when creating a regex by
1175concatenating smaller strings. For example if you have C<qr/$a$b/>, and C<$a>
1176contained C<"\g1">, and C<$b> contained C<"37">, you would get C</\g137/> which
1177is probably not what you intended.
1178
1179The C<\g> and C<\k> notations were introduced in Perl 5.10.0. Prior to that
1180there were no named nor relative numbered capture groups. Absolute numbered
0b928c2f 1181groups were referred to using C<\1>,
57fbbe96 1182C<\2>, I<etc>., and this notation is still
d8b950dc
KW
1183accepted (and likely always will be). But it leads to some ambiguities if
1184there are more than 9 capture groups, as C<\10> could mean either the tenth
1185capture group, or the character whose ordinal in octal is 010 (a backspace in
1186ASCII). Perl resolves this ambiguity by interpreting C<\10> as a backreference
1187only if at least 10 left parentheses have opened before it. Likewise C<\11> is
1188a backreference only if at least 11 left parentheses have opened before it.
e1f120a9
KW
1189And so on. C<\1> through C<\9> are always interpreted as backreferences.
1190There are several examples below that illustrate these perils. You can avoid
1191the ambiguity by always using C<\g{}> or C<\g> if you mean capturing groups;
1192and for octal constants always using C<\o{}>, or for C<\077> and below, using 3
1193digits padded with leading zeros, since a leading zero implies an octal
1194constant.
d8b950dc
KW
1195
1196The C<\I<digit>> notation also works in certain circumstances outside
ed7efc79 1197the pattern. See L</Warning on \1 Instead of $1> below for details.
81714fb9 1198
14218588 1199Examples:
a0d0e21e
LW
1200
1201 s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words
1202
d8b950dc 1203 /(.)\g1/ # find first doubled char
81714fb9
YO
1204 and print "'$1' is the first doubled character\n";
1205
1206 /(?<char>.)\k<char>/ # ... a different way
1207 and print "'$+{char}' is the first doubled character\n";
1208
d8b950dc 1209 /(?'char'.)\g1/ # ... mix and match
81714fb9 1210 and print "'$1' is the first doubled character\n";
c47ff5f1 1211
14218588 1212 if (/Time: (..):(..):(..)/) { # parse out values
f793d64a
KW
1213 $hours = $1;
1214 $minutes = $2;
1215 $seconds = $3;
a0d0e21e 1216 }
c47ff5f1 1217
9d860678
KW
1218 /(.)(.)(.)(.)(.)(.)(.)(.)(.)\g10/ # \g10 is a backreference
1219 /(.)(.)(.)(.)(.)(.)(.)(.)(.)\10/ # \10 is octal
1220 /((.)(.)(.)(.)(.)(.)(.)(.)(.))\10/ # \10 is a backreference
1221 /((.)(.)(.)(.)(.)(.)(.)(.)(.))\010/ # \010 is octal
1222
1223 $a = '(.)\1'; # Creates problems when concatenated.
1224 $b = '(.)\g{1}'; # Avoids the problems.
1225 "aa" =~ /${a}/; # True
1226 "aa" =~ /${b}/; # True
1227 "aa0" =~ /${a}0/; # False!
1228 "aa0" =~ /${b}0/; # True
dc0d9c48
KW
1229 "aa\x08" =~ /${a}0/; # True!
1230 "aa\x08" =~ /${b}0/; # False
9d860678 1231
14218588
GS
1232Several special variables also refer back to portions of the previous
1233match. C<$+> returns whatever the last bracket match matched.
1234C<$&> returns the entire matched string. (At one point C<$0> did
1235also, but now it returns the name of the program.) C<$`> returns
77ea4f6d
JV
1236everything before the matched string. C<$'> returns everything
1237after the matched string. And C<$^N> contains whatever was matched by
1238the most-recently closed group (submatch). C<$^N> can be used in
1239extended patterns (see below), for example to assign a submatch to a
81714fb9 1240variable.
d74e8afc 1241X<$+> X<$^N> X<$&> X<$`> X<$'>
14218588 1242
d8b950dc 1243These special variables, like the C<%+> hash and the numbered match variables
57fbbe96 1244(C<$1>, C<$2>, C<$3>, I<etc>.) are dynamically scoped
14218588
GS
1245until the end of the enclosing block or until the next successful
1246match, whichever comes first. (See L<perlsyn/"Compound Statements">.)
d74e8afc
ITB
1247X<$+> X<$^N> X<$&> X<$`> X<$'>
1248X<$1> X<$2> X<$3> X<$4> X<$5> X<$6> X<$7> X<$8> X<$9>
1249
0d017f4d 1250B<NOTE>: Failed matches in Perl do not reset the match variables,
5146ce24 1251which makes it easier to write code that tests for a series of more
665e98b9
JH
1252specific cases and remembers the best match.
1253
13b0f67d
DM
1254B<WARNING>: If your code is to run on Perl 5.16 or earlier,
1255beware that once Perl sees that you need one of C<$&>, C<$`>, or
14218588 1256C<$'> anywhere in the program, it has to provide them for every
13b0f67d
DM
1257pattern match. This may substantially slow your program.
1258
57fbbe96 1259Perl uses the same mechanism to produce C<$1>, C<$2>, I<etc>, so you also
13b0f67d
DM
1260pay a price for each pattern that contains capturing parentheses.
1261(To avoid this cost while retaining the grouping behaviour, use the
14218588
GS
1262extended regular expression C<(?: ... )> instead.) But if you never
1263use C<$&>, C<$`> or C<$'>, then patterns I<without> capturing
1264parentheses will not be penalized. So avoid C<$&>, C<$'>, and C<$`>
1265if you can, but if you can't (and some algorithms really appreciate
1266them), once you've used them once, use them at will, because you've
13b0f67d 1267already paid the price.
d74e8afc 1268X<$&> X<$`> X<$'>
68dc0745 1269
13b0f67d
DM
1270Perl 5.16 introduced a slightly more efficient mechanism that notes
1271separately whether each of C<$`>, C<$&>, and C<$'> have been seen, and
1272thus may only need to copy part of the string. Perl 5.20 introduced a
1273much more efficient copy-on-write mechanism which eliminates any slowdown.
1274
1275As another workaround for this problem, Perl 5.10.0 introduced C<${^PREMATCH}>,
cde0cee5
YO
1276C<${^MATCH}> and C<${^POSTMATCH}>, which are equivalent to C<$`>, C<$&>
1277and C<$'>, B<except> that they are only guaranteed to be defined after a
87e95b7f 1278successful match that was executed with the C</p> (preserve) modifier.
cde0cee5 1279The use of these variables incurs no global performance penalty, unlike
7711f978 1280their punctuation character equivalents, however at the trade-off that you
13b0f67d
DM
1281have to tell perl when you want to use them. As of Perl 5.20, these three
1282variables are equivalent to C<$`>, C<$&> and C<$'>, and C</p> is ignored.
87e95b7f 1283X</p> X<p modifier>
cde0cee5 1284
9d727203
KW
1285=head2 Quoting metacharacters
1286
19799a22
GS
1287Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
1288C<\w>, C<\n>. Unlike some other regular expression languages, there
1289are no backslashed symbols that aren't alphanumeric. So anything
7711f978
KW
1290that looks like C<\\>, C<\(>, C<\)>, C<\[>, C<\]>, C<\{>, or C<\}> is
1291always
19799a22
GS
1292interpreted as a literal character, not a metacharacter. This was
1293once used in a common idiom to disable or quote the special meanings
1294of regular expression metacharacters in a string that you want to
36bbe248 1295use for a pattern. Simply quote all non-"word" characters:
a0d0e21e
LW
1296
1297 $pattern =~ s/(\W)/\\$1/g;
1298
f1cbbd6e 1299(If C<use locale> is set, then this depends on the current locale.)
7711f978
KW
1300Today it is more common to use the C<L<quotemeta()|perlfunc/quotemeta>>
1301function or the C<\Q> metaquoting escape sequence to disable all
1302metacharacters' special meanings like this:
a0d0e21e
LW
1303
1304 /$unquoted\Q$quoted\E$unquoted/
1305
9da458fc
IZ
1306Beware that if you put literal backslashes (those not inside
1307interpolated variables) between C<\Q> and C<\E>, double-quotish
1308backslash interpolation may lead to confusing results. If you
1309I<need> to use literal backslashes within C<\Q...\E>,
1310consult L<perlop/"Gory details of parsing quoted constructs">.
1311
736fe711
KW
1312C<quotemeta()> and C<\Q> are fully described in L<perlfunc/quotemeta>.
1313
19799a22
GS
1314=head2 Extended Patterns
1315
14218588 1316Perl also defines a consistent extension syntax for features not
0b928c2f
FC
1317found in standard tools like B<awk> and
1318B<lex>. The syntax for most of these is a
14218588
GS
1319pair of parentheses with a question mark as the first thing within
1320the parentheses. The character after the question mark indicates
1321the extension.
19799a22 1322
14218588
GS
1323A question mark was chosen for this and for the minimal-matching
1324construct because 1) question marks are rare in older regular
1325expressions, and 2) whenever you see one, you should stop and
0b928c2f 1326"question" exactly what is going on. That's psychology....
a0d0e21e 1327
70ca8714 1328=over 4
a0d0e21e 1329
cc6b7395 1330=item C<(?#text)>
d74e8afc 1331X<(?#)>
a0d0e21e 1332
7c688e65
KW
1333A comment. The text is ignored.
1334Note that Perl closes
7711f978
KW
1335the comment as soon as it sees a C<")">, so there is no way to put a literal
1336C<")"> in the comment. The pattern's closing delimiter must be escaped by
7c688e65
KW
1337a backslash if it appears in the comment.
1338
1339See L</E<sol>x> for another way to have comments in patterns.
a0d0e21e 1340
2ab07670
KW
1341Note that a comment can go just about anywhere, except in the middle of
1342an escape sequence. Examples:
1343
1344 qr/foo(?#comment)bar/' # Matches 'foobar'
1345
1346 # The pattern below matches 'abcd', 'abccd', or 'abcccd'
1347 qr/abc(?#comment between literal and its quantifier){1,3}d/
1348
1349 # The pattern below generates a syntax error, because the '\p' must
1350 # be followed immediately by a '{'.
1351 qr/\p(?#comment between \p and its property name){Any}/
1352
1353 # The pattern below generates a syntax error, because the initial
1354 # '\(' is a literal opening parenthesis, and so there is nothing
1355 # for the closing ')' to match
1356 qr/\(?#the backslash means this isn't a comment)p{Any}/
1357
4cb6b395 1358=item C<(?adlupimnsx-imnsx)>
fb85c044 1359
4cb6b395 1360=item C<(?^alupimnsx)>
fb85c044 1361X<(?)> X<(?^)>
19799a22 1362
0b6d1084 1363One or more embedded pattern-match modifiers, to be turned on (or
2ab07670 1364turned off if preceded by C<"-">) for the remainder of the pattern or
fb85c044
KW
1365the remainder of the enclosing pattern group (if any).
1366
a95b7a20
AC
1367This is particularly useful for dynamically-generated patterns,
1368such as those read in from a
0d017f4d 1369configuration file, taken from an argument, or specified in a table
0b928c2f
FC
1370somewhere. Consider the case where some patterns want to be
1371case-sensitive and some do not: The case-insensitive ones merely need to
0d017f4d 1372include C<(?i)> at the front of the pattern. For example:
19799a22
GS
1373
1374 $pattern = "foobar";
5d458dd8 1375 if ( /$pattern/i ) { }
19799a22
GS
1376
1377 # more flexible:
1378
1379 $pattern = "(?i)foobar";
5d458dd8 1380 if ( /$pattern/ ) { }
19799a22 1381
0b6d1084 1382These modifiers are restored at the end of the enclosing group. For example,
19799a22 1383
d8b950dc 1384 ( (?i) blah ) \s+ \g1
19799a22 1385
0d017f4d
WL
1386will match C<blah> in any case, some spaces, and an exact (I<including the case>!)
1387repetition of the previous word, assuming the C</x> modifier, and no C</i>
1388modifier outside this group.
19799a22 1389
8eb5594e 1390These modifiers do not carry over into named subpatterns called in the
dd72e27b 1391enclosing group. In other words, a pattern such as C<((?i)(?&NAME))> does not
7711f978 1392change the case-sensitivity of the C<"NAME"> pattern.
8eb5594e 1393
2ab07670
KW
1394A modifier is overridden by later occurrences of this construct in the
1395same scope containing the same modifier, so that
1396
1397 /((?im)foo(?-m)bar)/
1398
1399matches all of C<foobar> case insensitively, but uses C</m> rules for
57fbbe96
KW
1400only the C<foo> portion. The C<"a"> flag overrides C<aa> as well;
1401likewise C<aa> overrides C<"a">. The same goes for C<"x"> and C<xx>.
77c8f263
KW
1402Hence, in
1403
1404 /(?-x)foo/xx
1405
1406both C</x> and C</xx> are turned off during matching C<foo>. And in
1407
1408 /(?x)foo/x
1409
1410C</x> but NOT C</xx> is turned on for matching C<foo>. (One might
1411mistakenly think that since the inner C<(?x)> is already in the scope of
1412C</x>, that the result would effectively be the sum of them, yielding
1413C</xx>. It doesn't work that way.) Similarly, doing something like
57fbbe96
KW
1414C<(?xx-x)foo> turns off all C<"x"> behavior for matching C<foo>, it is not
1415that you subtract 1 C<"x"> from 2 to get 1 C<"x"> remaining.
2ab07670 1416
dc925305
KW
1417Any of these modifiers can be set to apply globally to all regular
1418expressions compiled within the scope of a C<use re>. See
a0bbd6ff 1419L<re/"'/flags' mode">.
dc925305 1420
9de15fec 1421Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately
4cb6b395 1422after the C<"?"> is a shorthand equivalent to C<d-imnsx>. Flags (except
9de15fec
KW
1423C<"d">) may follow the caret to override it.
1424But a minus sign is not legal with it.
1425
57fbbe96
KW
1426Note that the C<"a">, C<"d">, C<"l">, C<"p">, and C<"u"> modifiers are special in
1427that they can only be enabled, not disabled, and the C<"a">, C<"d">, C<"l">, and
1428C<"u"> modifiers are mutually exclusive: specifying one de-specifies the
1429others, and a maximum of one (or two C<"a">'s) may appear in the
ed7efc79 1430construct. Thus, for
0b928c2f 1431example, C<(?-p)> will warn when compiled under C<use warnings>;
b6fa137b 1432C<(?-d:...)> and C<(?dl:...)> are fatal errors.
9de15fec 1433
57fbbe96 1434Note also that the C<"p"> modifier is special in that its presence
9de15fec 1435anywhere in a pattern has a global effect.
cde0cee5 1436
5a964f20 1437=item C<(?:pattern)>
d74e8afc 1438X<(?:)>
a0d0e21e 1439
4cb6b395 1440=item C<(?adluimnsx-imnsx:pattern)>
ca9dfc88 1441
4cb6b395 1442=item C<(?^aluimnsx:pattern)>
fb85c044
KW
1443X<(?^:)>
1444
5a964f20 1445This is for clustering, not capturing; it groups subexpressions like
7711f978 1446C<"()">, but doesn't make backreferences as C<"()"> does. So
a0d0e21e 1447
5a964f20 1448 @fields = split(/\b(?:a|b|c)\b/)
a0d0e21e 1449
a95b7a20 1450matches the same field delimiters as
a0d0e21e 1451
5a964f20 1452 @fields = split(/\b(a|b|c)\b/)
a0d0e21e 1453
a95b7a20
AC
1454but doesn't spit out the delimiters themselves as extra fields (even though
1455that's the behaviour of L<perlfunc/split> when its pattern contains capturing
1456groups). It's also cheaper not to capture
19799a22 1457characters if you don't need to.
a0d0e21e 1458
7711f978 1459Any letters between C<"?"> and C<":"> act as flags modifiers as with
4cb6b395 1460C<(?adluimnsx-imnsx)>. For example,
ca9dfc88
IZ
1461
1462 /(?s-i:more.*than).*million/i
1463
14218588 1464is equivalent to the more verbose
ca9dfc88
IZ
1465
1466 /(?:(?s-i)more.*than).*million/i
1467
7711f978 1468Note that any C<()> constructs enclosed within this one will still
4cb6b395
KW
1469capture unless the C</n> modifier is in effect.
1470
57fbbe96
KW
1471Like the L</(?adlupimnsx-imnsx)> construct, C<aa> and C<"a"> override each
1472other, as do C<xx> and C<"x">. They are not additive. So, doing
1473something like C<(?xx-x:foo)> turns off all C<"x"> behavior for matching
77c8f263 1474C<foo>.
2ab07670 1475
fb85c044 1476Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately
4cb6b395 1477after the C<"?"> is a shorthand equivalent to C<d-imnsx>. Any positive
9de15fec 1478flags (except C<"d">) may follow the caret, so
fb85c044
KW
1479
1480 (?^x:foo)
1481
1482is equivalent to
1483
4cb6b395 1484 (?x-imns:foo)
fb85c044
KW
1485
1486The caret tells Perl that this cluster doesn't inherit the flags of any
4cb6b395 1487surrounding pattern, but uses the system defaults (C<d-imnsx>),
fb85c044
KW
1488modified by any flags specified.
1489
1490The caret allows for simpler stringification of compiled regular
1491expressions. These look like
1492
1493 (?^:pattern)
1494
1495with any non-default flags appearing between the caret and the colon.
1496A test that looks at such stringification thus doesn't need to have the
1497system default flags hard-coded in it, just the caret. If new flags are
1498added to Perl, the meaning of the caret's expansion will change to include
1499the default for those flags, so the test will still work, unchanged.
1500
1501Specifying a negative flag after the caret is an error, as the flag is
1502redundant.
1503
1504Mnemonic for C<(?^...)>: A fresh beginning since the usual use of a caret is
1505to match at the beginning.
1506
594d7033
YO
1507=item C<(?|pattern)>
1508X<(?|)> X<Branch reset>
1509
1510This is the "branch reset" pattern, which has the special property
c27a5cfe 1511that the capture groups are numbered from the same starting point
99d59c4d 1512in each alternation branch. It is available starting from perl 5.10.0.
4deaaa80 1513
c27a5cfe 1514Capture groups are numbered from left to right, but inside this
693596a8 1515construct the numbering is restarted for each branch.
4deaaa80 1516
c27a5cfe 1517The numbering within each branch will be as normal, and any groups
4deaaa80
PJ
1518following this construct will be numbered as though the construct
1519contained only one branch, that being the one with the most capture
c27a5cfe 1520groups in it.
4deaaa80 1521
0b928c2f 1522This construct is useful when you want to capture one of a
4deaaa80
PJ
1523number of alternative matches.
1524
1525Consider the following pattern. The numbers underneath show in
c27a5cfe 1526which group the captured content will be stored.
594d7033
YO
1527
1528
57fbbe96 1529 # before ---------------branch-reset----------- after
594d7033 1530 / ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
57fbbe96 1531 # 1 2 2 3 2 3 4
594d7033 1532
57fbbe96
KW
1533Be careful when using the branch reset pattern in combination with
1534named captures. Named captures are implemented as being aliases to
c27a5cfe 1535numbered groups holding the captures, and that interferes with the
ab106183
A
1536implementation of the branch reset pattern. If you are using named
1537captures in a branch reset pattern, it's best to use the same names,
1538in the same order, in each of the alternations:
1539
1540 /(?| (?<a> x ) (?<b> y )
1541 | (?<a> z ) (?<b> w )) /x
1542
1543Not doing so may lead to surprises:
1544
1545 "12" =~ /(?| (?<a> \d+ ) | (?<b> \D+))/x;
a95b7a20
AC
1546 say $+{a}; # Prints '12'
1547 say $+{b}; # *Also* prints '12'.
ab106183 1548
c27a5cfe
KW
1549The problem here is that both the group named C<< a >> and the group
1550named C<< b >> are aliases for the group belonging to C<< $1 >>.
90a18110 1551
f67a5002 1552=item Lookaround Assertions
ee9b8eae
YO
1553X<look-around assertion> X<lookaround assertion> X<look-around> X<lookaround>
1554
f67a5002 1555Lookaround assertions are zero-width patterns which match a specific
ee9b8eae
YO
1556pattern without including it in C<$&>. Positive assertions match when
1557their subpattern matches, negative assertions match when their subpattern
f67a5002
EA
1558fails. Lookbehind matches text up to the current match position,
1559lookahead matches text following the current match position.
ee9b8eae
YO
1560
1561=over 4
1562
5a964f20 1563=item C<(?=pattern)>
d74e8afc 1564X<(?=)> X<look-ahead, positive> X<lookahead, positive>
a0d0e21e 1565
f67a5002 1566A zero-width positive lookahead assertion. For example, C</\w+(?=\t)/>
a0d0e21e
LW
1567matches a word followed by a tab, without including the tab in C<$&>.
1568
5a964f20 1569=item C<(?!pattern)>
d74e8afc 1570X<(?!)> X<look-ahead, negative> X<lookahead, negative>
a0d0e21e 1571
f67a5002 1572A zero-width negative lookahead assertion. For example C</foo(?!bar)/>
a0d0e21e 1573matches any occurrence of "foo" that isn't followed by "bar". Note
f67a5002
EA
1574however that lookahead and lookbehind are NOT the same thing. You cannot
1575use this for lookbehind.
7b8d334a 1576
5a964f20 1577If you are looking for a "bar" that isn't preceded by a "foo", C</(?!foo)bar/>
7b8d334a
GS
1578will not do what you want. That's because the C<(?!foo)> is just saying that
1579the next thing cannot be "foo"--and it's not, it's a "bar", so "foobar" will
f67a5002 1580match. Use lookbehind instead (see below).
c277df42 1581
a8f2f5fa
AC
1582=item C<(?<=pattern)>
1583
1584=item C<\K>
ee9b8eae 1585X<(?<=)> X<look-behind, positive> X<lookbehind, positive> X<\K>
c277df42 1586
f67a5002 1587A zero-width positive lookbehind assertion. For example, C</(?<=\t)\w+/>
19799a22 1588matches a word that follows a tab, without including the tab in C<$&>.
f67a5002 1589Works only for fixed-width lookbehind.
c277df42 1590
3d9df1a7
KE
1591There is a special form of this construct, called C<\K> (available since
1592Perl 5.10.0), which causes the
ee9b8eae 1593regex engine to "keep" everything it had matched prior to the C<\K> and
0b928c2f 1594not include it in C<$&>. This effectively provides variable-length
f67a5002 1595lookbehind. The use of C<\K> inside of another lookaround assertion
ee9b8eae
YO
1596is allowed, but the behaviour is currently not well defined.
1597
c62285ac 1598For various reasons C<\K> may be significantly more efficient than the
ee9b8eae
YO
1599equivalent C<< (?<=...) >> construct, and it is especially useful in
1600situations where you want to efficiently remove something following
1601something else in a string. For instance
1602
1603 s/(foo)bar/$1/g;
1604
1605can be rewritten as the much more efficient
1606
1607 s/foo\Kbar//g;
1608
5a964f20 1609=item C<(?<!pattern)>
d74e8afc 1610X<(?<!)> X<look-behind, negative> X<lookbehind, negative>
c277df42 1611
f67a5002 1612A zero-width negative lookbehind assertion. For example C</(?<!bar)foo/>
19799a22 1613matches any occurrence of "foo" that does not follow "bar". Works
f67a5002 1614only for fixed-width lookbehind.
c277df42 1615
ee9b8eae
YO
1616=back
1617
81714fb9 1618=item C<< (?<NAME>pattern) >>
a8f2f5fa
AC
1619
1620=item C<(?'NAME'pattern)>
81714fb9
YO
1621X<< (?<NAME>) >> X<(?'NAME')> X<named capture> X<capture>
1622
c27a5cfe 1623A named capture group. Identical in every respect to normal capturing
0b928c2f
FC
1624parentheses C<()> but for the additional fact that the group
1625can be referred to by name in various regular expression
1626constructs (like C<\g{NAME}>) and can be accessed by name
1627after a successful match via C<%+> or C<%->. See L<perlvar>
90a18110 1628for more details on the C<%+> and C<%-> hashes.
81714fb9 1629
c27a5cfe 1630If multiple distinct capture groups have the same name then the
7711f978 1631C<$+{NAME}> will refer to the leftmost defined group in the match.
81714fb9 1632
0d017f4d 1633The forms C<(?'NAME'pattern)> and C<< (?<NAME>pattern) >> are equivalent.
81714fb9
YO
1634
1635B<NOTE:> While the notation of this construct is the same as the similar
c27a5cfe 1636function in .NET regexes, the behavior is not. In Perl the groups are
81714fb9
YO
1637numbered sequentially regardless of being named or not. Thus in the
1638pattern
1639
1640 /(x)(?<foo>y)(z)/
1641
7711f978 1642C<$+{I<foo>}> will be the same as C<$2>, and C<$3> will contain 'z' instead of
81714fb9
YO
1643the opposite which is what a .NET regex hacker might expect.
1644
7711f978 1645Currently I<NAME> is restricted to simple identifiers only.
1f1031fe
YO
1646In other words, it must match C</^[_A-Za-z][_A-Za-z0-9]*\z/> or
1647its Unicode extension (see L<utf8>),
1648though it isn't extended by the locale (see L<perllocale>).
81714fb9 1649
1f1031fe 1650B<NOTE:> In order to make things easier for programmers with experience
ae5648b3 1651with the Python or PCRE regex engines, the pattern C<< (?PE<lt>NAMEE<gt>pattern) >>
0d017f4d 1652may be used instead of C<< (?<NAME>pattern) >>; however this form does not
64c5a566 1653support the use of single quotes as a delimiter for the name.
81714fb9 1654
1f1031fe
YO
1655=item C<< \k<NAME> >>
1656
1657=item C<< \k'NAME' >>
81714fb9
YO
1658
1659Named backreference. Similar to numeric backreferences, except that
1660the group is designated by name and not number. If multiple groups
1661have the same name then it refers to the leftmost defined group in
1662the current match.
1663
0d017f4d 1664It is an error to refer to a name not defined by a C<< (?<NAME>) >>
81714fb9
YO
1665earlier in the pattern.
1666
1667Both forms are equivalent.
1668
1f1031fe 1669B<NOTE:> In order to make things easier for programmers with experience
0d017f4d 1670with the Python or PCRE regex engines, the pattern C<< (?P=NAME) >>
64c5a566 1671may be used instead of C<< \k<NAME> >>.
1f1031fe 1672
cc6b7395 1673=item C<(?{ code })>
d74e8afc 1674X<(?{})> X<regex, code in> X<regexp, code in> X<regular expression, code in>
c277df42 1675
83f32aba
RS
1676B<WARNING>: Using this feature safely requires that you understand its
1677limitations. Code executed that has side effects may not perform identically
1678from version to version due to the effect of future optimisations in the regex
1679engine. For more information on this, see L</Embedded Code Execution
1680Frequency>.
c277df42 1681
e128ab2c
DM
1682This zero-width assertion executes any embedded Perl code. It always
1683succeeds, and its return value is set as C<$^R>.
19799a22 1684
e128ab2c
DM
1685In literal patterns, the code is parsed at the same time as the
1686surrounding code. While within the pattern, control is passed temporarily
1687back to the perl parser, until the logically-balancing closing brace is
1688encountered. This is similar to the way that an array index expression in
1689a literal string is handled, for example
77ea4f6d 1690
e128ab2c
DM
1691 "abc$array[ 1 + f('[') + g()]def"
1692
1693In particular, braces do not need to be balanced:
1694
576fa024 1695 s/abc(?{ f('{'); })/def/
e128ab2c
DM
1696
1697Even in a pattern that is interpolated and compiled at run-time, literal
1698code blocks will be compiled once, at perl compile time; the following
1699prints "ABCD":
1700
1701 print "D";
1702 my $qr = qr/(?{ BEGIN { print "A" } })/;
1703 my $foo = "foo";
1704 /$foo$qr(?{ BEGIN { print "B" } })/;
1705 BEGIN { print "C" }
1706
1707In patterns where the text of the code is derived from run-time
1708information rather than appearing literally in a source code /pattern/,
1709the code is compiled at the same time that the pattern is compiled, and
5771dda0 1710for reasons of security, C<use re 'eval'> must be in scope. This is to
e128ab2c
DM
1711stop user-supplied patterns containing code snippets from being
1712executable.
1713
5771dda0 1714In situations where you need to enable this with C<use re 'eval'>, you should
e128ab2c
DM
1715also have taint checking enabled. Better yet, use the carefully
1716constrained evaluation within a Safe compartment. See L<perlsec> for
1717details about both these mechanisms.
1718
1719From the viewpoint of parsing, lexical variable scope and closures,
1720
1721 /AAA(?{ BBB })CCC/
1722
1723behaves approximately like
1724
1725 /AAA/ && do { BBB } && /CCC/
1726
1727Similarly,
1728
1729 qr/AAA(?{ BBB })CCC/
1730
1731behaves approximately like
77ea4f6d 1732
e128ab2c
DM
1733 sub { /AAA/ && do { BBB } && /CCC/ }
1734
1735In particular:
1736
1737 { my $i = 1; $r = qr/(?{ print $i })/ }
1738 my $i = 2;
1739 /$r/; # prints "1"
1740
1741Inside a C<(?{...})> block, C<$_> refers to the string the regular
754091cb 1742expression is matching against. You can also use C<pos()> to know what is
fa11829f 1743the current position of matching within this string.
754091cb 1744
e128ab2c
DM
1745The code block introduces a new scope from the perspective of lexical
1746variable declarations, but B<not> from the perspective of C<local> and
1747similar localizing behaviours. So later code blocks within the same
1748pattern will still see the values which were localized in earlier blocks.
1749These accumulated localizations are undone either at the end of a
1750successful match, or if the assertion is backtracked (compare
5a0de581 1751L</"Backtracking">). For example,
b9ac3b5b
GS
1752
1753 $_ = 'a' x 8;
5d458dd8 1754 m<
d1fbf752 1755 (?{ $cnt = 0 }) # Initialize $cnt.
b9ac3b5b 1756 (
5d458dd8 1757 a
b9ac3b5b 1758 (?{
d1fbf752
KW
1759 local $cnt = $cnt + 1; # Update $cnt,
1760 # backtracking-safe.
b9ac3b5b 1761 })
5d458dd8 1762 )*
b9ac3b5b 1763 aaaa
d1fbf752
KW
1764 (?{ $res = $cnt }) # On success copy to
1765 # non-localized location.
b9ac3b5b
GS
1766 >x;
1767
e128ab2c
DM
1768will initially increment C<$cnt> up to 8; then during backtracking, its
1769value will be unwound back to 4, which is the value assigned to C<$res>.
7711f978 1770At the end of the regex execution, C<$cnt> will be wound back to its initial
e128ab2c
DM
1771value of 0.
1772
1773This assertion may be used as the condition in a
b9ac3b5b 1774
e128ab2c
DM
1775 (?(condition)yes-pattern|no-pattern)
1776
1777switch. If I<not> used in this way, the result of evaluation of C<code>
1778is put into the special variable C<$^R>. This happens immediately, so
1779C<$^R> can be used from other C<(?{ code })> assertions inside the same
1780regular expression.
b9ac3b5b 1781
19799a22
GS
1782The assignment to C<$^R> above is properly localized, so the old
1783value of C<$^R> is restored if the assertion is backtracked; compare
5a0de581 1784L</"Backtracking">.
b9ac3b5b 1785
e128ab2c
DM
1786Note that the special variable C<$^N> is particularly useful with code
1787blocks to capture the results of submatches in variables without having to
1788keep track of the number of nested parentheses. For example:
1789
1790 $_ = "The brown fox jumps over the lazy dog";
1791 /the (\S+)(?{ $color = $^N }) (\S+)(?{ $animal = $^N })/i;
1792 print "color = $color, animal = $animal\n";
1793
8988a1bb 1794
14455d6c 1795=item C<(??{ code })>
d74e8afc
ITB
1796X<(??{})>
1797X<regex, postponed> X<regexp, postponed> X<regular expression, postponed>
0f5d15d6 1798
83f32aba
RS
1799B<WARNING>: Using this feature safely requires that you understand its
1800limitations. Code executed that has side effects may not perform
1801identically from version to version due to the effect of future
1802optimisations in the regex engine. For more information on this, see
1803L</Embedded Code Execution Frequency>.
0f5d15d6 1804
e128ab2c
DM
1805This is a "postponed" regular subexpression. It behaves in I<exactly> the
1806same way as a C<(?{ code })> code block as described above, except that
1807its return value, rather than being assigned to C<$^R>, is treated as a
1808pattern, compiled if it's a string (or used as-is if its a qr// object),
1809then matched as if it were inserted instead of this construct.
6bda09f9 1810
e128ab2c
DM
1811During the matching of this sub-pattern, it has its own set of
1812captures which are valid during the sub-match, but are discarded once
1813control returns to the main pattern. For example, the following matches,
1814with the inner pattern capturing "B" and matching "BB", while the outer
1815pattern captures "A";
1816
1817 my $inner = '(.)\1';
1818 "ABBA" =~ /^(.)(??{ $inner })\1/;
1819 print $1; # prints "A";
6bda09f9 1820
e128ab2c
DM
1821Note that this means that there is no way for the inner pattern to refer
1822to a capture group defined outside. (The code block itself can use C<$1>,
57fbbe96 1823I<etc>., to refer to the enclosing pattern's capture groups.) Thus, although
0f5d15d6 1824
e128ab2c
DM
1825 ('a' x 100)=~/(??{'(.)' x 100})/
1826
7711f978 1827I<will> match, it will I<not> set C<$1> on exit.
19799a22
GS
1828
1829The following pattern matches a parenthesized group:
0f5d15d6 1830
d1fbf752
KW
1831 $re = qr{
1832 \(
1833 (?:
1834 (?> [^()]+ ) # Non-parens without backtracking
1835 |
1836 (??{ $re }) # Group with matching parens
1837 )*
1838 \)
1839 }x;
0f5d15d6 1840
93f313ef
KW
1841See also
1842L<C<(?I<PARNO>)>|/(?PARNO) (?-PARNO) (?+PARNO) (?R) (?0)>
1843for a different, more efficient way to accomplish
6bda09f9
YO
1844the same task.
1845
7e7dae31
KW
1846Executing a postponed regular expression too many times without
1847consuming any input string will also result in a fatal error. The depth
1848at which that happens is compiled into perl, so it can be changed with a
1849custom build.
6bda09f9 1850
93f313ef 1851=item C<(?I<PARNO>)> C<(?-I<PARNO>)> C<(?+I<PARNO>)> C<(?R)> C<(?0)>
542fa716 1852X<(?PARNO)> X<(?1)> X<(?R)> X<(?0)> X<(?-1)> X<(?+1)> X<(?-PARNO)> X<(?+PARNO)>
6bda09f9 1853X<regex, recursive> X<regexp, recursive> X<regular expression, recursive>
d1b2014a
YO
1854X<regex, relative recursion> X<GOSUB> X<GOSTART>
1855
1856Recursive subpattern. Treat the contents of a given capture buffer in the
1857current pattern as an independent subpattern and attempt to match it at
1858the current position in the string. Information about capture state from
1859the caller for things like backreferences is available to the subpattern,
1860but capture buffers set by the subpattern are not visible to the caller.
6bda09f9 1861
e128ab2c
DM
1862Similar to C<(??{ code })> except that it does not involve executing any
1863code or potentially compiling a returned pattern string; instead it treats
1864the part of the current pattern contained within a specified capture group
d1b2014a
YO
1865as an independent pattern that must match at the current position. Also
1866different is the treatment of capture buffers, unlike C<(??{ code })>
dd407255 1867recursive patterns have access to their caller's match state, so one can
d1b2014a 1868use backreferences safely.
6bda09f9 1869
93f313ef 1870I<PARNO> is a sequence of digits (not starting with 0) whose value reflects
c27a5cfe 1871the paren-number of the capture group to recurse to. C<(?R)> recurses to
894be9b7 1872the beginning of the whole pattern. C<(?0)> is an alternate syntax for
93f313ef 1873C<(?R)>. If I<PARNO> is preceded by a plus or minus sign then it is assumed
c27a5cfe 1874to be relative, with negative numbers indicating preceding capture groups
542fa716 1875and positive ones following. Thus C<(?-1)> refers to the most recently
c27a5cfe 1876declared group, and C<(?+1)> indicates the next group to be declared.
c74340f9 1877Note that the counting for relative recursion differs from that of
c27a5cfe 1878relative backreferences, in that with recursion unclosed groups B<are>
c74340f9 1879included.
6bda09f9 1880
7711f978 1881The following pattern matches a function C<foo()> which may contain
f145b7e9 1882balanced parentheses as the argument.
6bda09f9 1883
d1fbf752 1884 $re = qr{ ( # paren group 1 (full function)
81714fb9 1885 foo
d1fbf752 1886 ( # paren group 2 (parens)
6bda09f9 1887 \(
d1fbf752 1888 ( # paren group 3 (contents of parens)
6bda09f9 1889 (?:
d1fbf752 1890 (?> [^()]+ ) # Non-parens without backtracking
6bda09f9 1891 |
d1fbf752 1892 (?2) # Recurse to start of paren group 2
6bda09f9
YO
1893 )*
1894 )
1895 \)
1896 )
1897 )
1898 }x;
1899
1900If the pattern was used as follows
1901
1902 'foo(bar(baz)+baz(bop))'=~/$re/
1903 and print "\$1 = $1\n",
1904 "\$2 = $2\n",
1905 "\$3 = $3\n";
1906
1907the output produced should be the following:
1908
1909 $1 = foo(bar(baz)+baz(bop))
1910 $2 = (bar(baz)+baz(bop))
81714fb9 1911 $3 = bar(baz)+baz(bop)
6bda09f9 1912
c27a5cfe 1913If there is no corresponding capture group defined, then it is a
7e7dae31
KW
1914fatal error. Recursing deeply without consuming any input string will
1915also result in a fatal error. The depth at which that happens is
1916compiled into perl, so it can be changed with a custom build.
6bda09f9 1917
542fa716
YO
1918The following shows how using negative indexing can make it
1919easier to embed recursive patterns inside of a C<qr//> construct
1920for later use:
1921
1922 my $parens = qr/(\((?:[^()]++|(?-1))*+\))/;
c77257ed 1923 if (/foo $parens \s+ \+ \s+ bar $parens/x) {
542fa716
YO
1924 # do something here...
1925 }
1926
81714fb9 1927B<Note> that this pattern does not behave the same way as the equivalent
0d017f4d 1928PCRE or Python construct of the same form. In Perl you can backtrack into
6bda09f9 1929a recursed group, in PCRE and Python the recursed into group is treated
542fa716 1930as atomic. Also, modifiers are resolved at compile time, so constructs
7711f978 1931like C<(?i:(?1))> or C<(?:(?i)(?1))> do not affect how the sub-pattern will
542fa716 1932be processed.
6bda09f9 1933
894be9b7
YO
1934=item C<(?&NAME)>
1935X<(?&NAME)>
1936
93f313ef 1937Recurse to a named subpattern. Identical to C<(?I<PARNO>)> except that the
0d017f4d 1938parenthesis to recurse to is determined by name. If multiple parentheses have
894be9b7
YO
1939the same name, then it recurses to the leftmost.
1940
1941It is an error to refer to a name that is not declared somewhere in the
1942pattern.
1943
1f1031fe
YO
1944B<NOTE:> In order to make things easier for programmers with experience
1945with the Python or PCRE regex engines the pattern C<< (?P>NAME) >>
64c5a566 1946may be used instead of C<< (?&NAME) >>.
1f1031fe 1947
e2e6a0f1
YO
1948=item C<(?(condition)yes-pattern|no-pattern)>
1949X<(?()>
286f584a 1950
e2e6a0f1 1951=item C<(?(condition)yes-pattern)>
286f584a 1952
41ef34de
ML
1953Conditional expression. Matches C<yes-pattern> if C<condition> yields
1954a true value, matches C<no-pattern> otherwise. A missing pattern always
1955matches.
1956
7711f978
KW
1957C<(condition)> should be one of:
1958
1959=over 4
1960
1961=item an integer in parentheses
1962
1963(which is valid if the corresponding pair of parentheses
1964matched);
1965
f67a5002 1966=item a lookahead/lookbehind/evaluate zero-width assertion;
7711f978
KW
1967
1968=item a name in angle brackets or single quotes
1969
1970(which is valid if a group with the given name matched);
1971
1972=item the special symbol C<(R)>
1973
1974(true when evaluated inside of recursion or eval). Additionally the
57fbbe96 1975C<"R"> may be
e2e6a0f1
YO
1976followed by a number, (which will be true when evaluated when recursing
1977inside of the appropriate group), or by C<&NAME>, in which case it will
1978be true only when evaluated during recursion in the named group.
1979
7711f978
KW
1980=back
1981
e2e6a0f1
YO
1982Here's a summary of the possible predicates:
1983
1984=over 4
1985
7711f978 1986=item C<(1)> C<(2)> ...
e2e6a0f1 1987
c27a5cfe 1988Checks if the numbered capturing group has matched something.
9240ab7d 1989Full syntax: C<< (?(1)then|else) >>
e2e6a0f1 1990
7711f978 1991=item C<(E<lt>I<NAME>E<gt>)> C<('I<NAME>')>
e2e6a0f1 1992
c27a5cfe 1993Checks if a group with the given name has matched something.
9240ab7d 1994Full syntax: C<< (?(<name>)then|else) >>
e2e6a0f1 1995
7711f978 1996=item C<(?=...)> C<(?!...)> C<(?<=...)> C<(?<!...)>
f01cd190 1997
7711f978 1998Checks whether the pattern matches (or does not match, for the C<"!">
f01cd190 1999variants).
9240ab7d 2000Full syntax: C<< (?(?=lookahead)then|else) >>
f01cd190 2001
7711f978 2002=item C<(?{ I<CODE> })>
e2e6a0f1 2003
f01cd190 2004Treats the return value of the code block as the condition.
9240ab7d 2005Full syntax: C<< (?(?{ code })then|else) >>
e2e6a0f1 2006
7711f978 2007=item C<(R)>
e2e6a0f1
YO
2008
2009Checks if the expression has been evaluated inside of recursion.
9240ab7d 2010Full syntax: C<< (?(R)then|else) >>
e2e6a0f1 2011
7711f978 2012=item C<(R1)> C<(R2)> ...
e2e6a0f1
YO
2013
2014Checks if the expression has been evaluated while executing directly
2015inside of the n-th capture group. This check is the regex equivalent of
2016
2017 if ((caller(0))[3] eq 'subname') { ... }
2018
2019In other words, it does not check the full recursion stack.
2020
9240ab7d
AC
2021Full syntax: C<< (?(R1)then|else) >>
2022
7711f978 2023=item C<(R&I<NAME>)>
e2e6a0f1
YO
2024
2025Similar to C<(R1)>, this predicate checks to see if we're executing
2026directly inside of the leftmost group with a given name (this is the same
7711f978 2027logic used by C<(?&I<NAME>)> to disambiguate). It does not check the full
e2e6a0f1 2028stack, but only the name of the innermost active recursion.
9240ab7d 2029Full syntax: C<< (?(R&name)then|else) >>
e2e6a0f1 2030
7711f978 2031=item C<(DEFINE)>
e2e6a0f1
YO
2032
2033In this case, the yes-pattern is never directly executed, and no
2034no-pattern is allowed. Similar in spirit to C<(?{0})> but more efficient.
2035See below for details.
9240ab7d 2036Full syntax: C<< (?(DEFINE)definitions...) >>
e2e6a0f1
YO
2037
2038=back
2039
2040For example:
2041
2042 m{ ( \( )?
2043 [^()]+
2044 (?(1) \) )
2045 }x
2046
2047matches a chunk of non-parentheses, possibly included in parentheses
2048themselves.
2049
0b928c2f
FC
2050A special form is the C<(DEFINE)> predicate, which never executes its
2051yes-pattern directly, and does not allow a no-pattern. This allows one to
2052define subpatterns which will be executed only by the recursion mechanism.
e2e6a0f1
YO
2053This way, you can define a set of regular expression rules that can be
2054bundled into any pattern you choose.
2055
2056It is recommended that for this usage you put the DEFINE block at the
2057end of the pattern, and that you name any subpatterns defined within it.
2058
2059Also, it's worth noting that patterns defined this way probably will
31dc26d6 2060not be as efficient, as the optimizer is not very clever about
e2e6a0f1
YO
2061handling them.
2062
2063An example of how this might be used is as follows:
2064
2bf803e2 2065 /(?<NAME>(?&NAME_PAT))(?<ADDR>(?&ADDRESS_PAT))
e2e6a0f1 2066 (?(DEFINE)
2bf803e2 2067 (?<NAME_PAT>....)
22dc6719 2068 (?<ADDRESS_PAT>....)
e2e6a0f1
YO
2069 )/x
2070
c27a5cfe
KW
2071Note that capture groups matched inside of recursion are not accessible
2072after the recursion returns, so the extra layer of capturing groups is
e2e6a0f1
YO
2073necessary. Thus C<$+{NAME_PAT}> would not be defined even though
2074C<$+{NAME}> would be.
286f584a 2075
51a1303c
BF
2076Finally, keep in mind that subpatterns created inside a DEFINE block
2077count towards the absolute and relative number of captures, so this:
2078
2079 my @captures = "a" =~ /(.) # First capture
2080 (?(DEFINE)
2081 (?<EXAMPLE> 1 ) # Second capture
2082 )/x;
2083 say scalar @captures;
2084
2085Will output 2, not 1. This is particularly important if you intend to
2086compile the definitions with the C<qr//> operator, and later
2087interpolate them in another pattern.
2088
c47ff5f1 2089=item C<< (?>pattern) >>
6bda09f9 2090X<backtrack> X<backtracking> X<atomic> X<possessive>
5a964f20 2091
19799a22
GS
2092An "independent" subexpression, one which matches the substring
2093that a I<standalone> C<pattern> would match if anchored at the given
9da458fc 2094position, and it matches I<nothing other than this substring>. This
19799a22 2095construct is useful for optimizations of what would otherwise be
5a0de581 2096"eternal" matches, because it will not backtrack (see L</"Backtracking">).
9da458fc
IZ
2097It may also be useful in places where the "grab all you can, and do not
2098give anything back" semantic is desirable.
19799a22 2099
c47ff5f1 2100For example: C<< ^(?>a*)ab >> will never match, since C<< (?>a*) >>
19799a22 2101(anchored at the beginning of string, as above) will match I<all>
57fbbe96 2102characters C<"a"> at the beginning of string, leaving no C<"a"> for
19799a22
GS
2103C<ab> to match. In contrast, C<a*ab> will match the same as C<a+b>,
2104since the match of the subgroup C<a*> is influenced by the following
5a0de581 2105group C<ab> (see L</"Backtracking">). In particular, C<a*> inside
19799a22
GS
2106C<a*ab> will match fewer characters than a standalone C<a*>, since
2107this makes the tail match.
2108
0b928c2f
FC
2109C<< (?>pattern) >> does not disable backtracking altogether once it has
2110matched. It is still possible to backtrack past the construct, but not
2111into it. So C<< ((?>a*)|(?>b*))ar >> will still match "bar".
2112
c47ff5f1 2113An effect similar to C<< (?>pattern) >> may be achieved by writing
0b928c2f
FC
2114C<(?=(pattern))\g{-1}>. This matches the same substring as a standalone
2115C<a+>, and the following C<\g{-1}> eats the matched string; it therefore
c47ff5f1 2116makes a zero-length assertion into an analogue of C<< (?>...) >>.
19799a22
GS
2117(The difference between these two constructs is that the second one
2118uses a capturing group, thus shifting ordinals of backreferences
2119in the rest of a regular expression.)
2120
2121Consider this pattern:
c277df42 2122
871b0233 2123 m{ \(
e2e6a0f1 2124 (
f793d64a 2125 [^()]+ # x+
e2e6a0f1 2126 |
871b0233
IZ
2127 \( [^()]* \)
2128 )+
e2e6a0f1 2129 \)
871b0233 2130 }x
5a964f20 2131
19799a22
GS
2132That will efficiently match a nonempty group with matching parentheses
2133two levels deep or less. However, if there is no such group, it
2134will take virtually forever on a long string. That's because there
2135are so many different ways to split a long string into several
2136substrings. This is what C<(.+)+> is doing, and C<(.+)+> is similar
2137to a subpattern of the above pattern. Consider how the pattern
2138above detects no-match on C<((()aaaaaaaaaaaaaaaaaa> in several
2139seconds, but that each extra letter doubles this time. This
2140exponential performance will make it appear that your program has
14218588 2141hung. However, a tiny change to this pattern
5a964f20 2142
e2e6a0f1
YO
2143 m{ \(
2144 (
f793d64a 2145 (?> [^()]+ ) # change x+ above to (?> x+ )
e2e6a0f1 2146 |
871b0233
IZ
2147 \( [^()]* \)
2148 )+
e2e6a0f1 2149 \)
871b0233 2150 }x
c277df42 2151
c47ff5f1 2152which uses C<< (?>...) >> matches exactly when the one above does (verifying
5a964f20 2153this yourself would be a productive exercise), but finishes in a fourth
57fbbe96 2154the time when used on a similar string with 1000000 C<"a">s. Be aware,
0b928c2f
FC
2155however, that, when this construct is followed by a
2156quantifier, it currently triggers a warning message under
9f1b1f2d 2157the C<use warnings> pragma or B<-w> switch saying it
6bab786b 2158C<"matches null string many times in regex">.
c277df42 2159
c47ff5f1 2160On simple groups, such as the pattern C<< (?> [^()]+ ) >>, a comparable
f67a5002 2161effect may be achieved by negative lookahead, as in C<[^()]+ (?! [^()] )>.
57fbbe96 2162This was only 4 times slower on a string with 1000000 C<"a">s.
c277df42 2163
9da458fc
IZ
2164The "grab all you can, and do not give anything back" semantic is desirable
2165in many situations where on the first sight a simple C<()*> looks like
2166the correct solution. Suppose we parse text with comments being delimited
7711f978 2167by C<"#"> followed by some optional (horizontal) whitespace. Contrary to
4375e838 2168its appearance, C<#[ \t]*> I<is not> the correct subexpression to match
9da458fc
IZ
2169the comment delimiter, because it may "give up" some whitespace if
2170the remainder of the pattern can be made to match that way. The correct
2171answer is either one of these:
2172
2173 (?>#[ \t]*)
2174 #[ \t]*(?![ \t])
2175
7711f978 2176For example, to grab non-empty comments into C<$1>, one should use either
9da458fc
IZ
2177one of these:
2178
2179 / (?> \# [ \t]* ) ( .+ ) /x;
2180 / \# [ \t]* ( [^ \t] .* ) /x;
2181
2182Which one you pick depends on which of these expressions better reflects
2183the above specification of comments.
2184
6bda09f9
YO
2185In some literature this construct is called "atomic matching" or
2186"possessive matching".
2187
b9b4dddf
YO
2188Possessive quantifiers are equivalent to putting the item they are applied
2189to inside of one of these constructs. The following equivalences apply:
2190
2191 Quantifier Form Bracketing Form
2192 --------------- ---------------
2193 PAT*+ (?>PAT*)
2194 PAT++ (?>PAT+)
2195 PAT?+ (?>PAT?)
2196 PAT{min,max}+ (?>PAT{min,max})
2197
9d1a5160 2198=item C<(?[ ])>
f4f5fe57 2199
572224ce 2200See L<perlrecharclass/Extended Bracketed Character Classes>.
9d1a5160 2201
ff8bb468
AC
2202Note that this feature is currently L<experimental|perlpolicy/experimental>;
2203using it yields a warning in the C<experimental::regex_sets> category.
2204
e2e6a0f1
YO
2205=back
2206
1e0a6411
RGS
2207=head2 Backtracking
2208X<backtrack> X<backtracking>
2209
2210NOTE: This section presents an abstract approximation of regular
2211expression behavior. For a more rigorous (and complicated) view of
2212the rules involved in selecting a match among possible alternatives,
2213see L</Combining RE Pieces>.
2214
2215A fundamental feature of regular expression matching involves the
2216notion called I<backtracking>, which is currently used (when needed)
57fbbe96 2217by all regular non-possessive expression quantifiers, namely C<"*">, C<*?>, C<"+">,
a95b7a20 2218C<+?>, C<{n,m}>, and C<{n,m}?>. Backtracking is often optimized
1e0a6411
RGS
2219internally, but the general principle outlined here is valid.
2220
2221For a regular expression to match, the I<entire> regular expression must
2222match, not just part of it. So if the beginning of a pattern containing a
2223quantifier succeeds in a way that causes later parts in the pattern to
2224fail, the matching engine backs up and recalculates the beginning
2225part--that's why it's called backtracking.
2226
2227Here is an example of backtracking: Let's say you want to find the
2228word following "foo" in the string "Food is on the foo table.":
2229
2230 $_ = "Food is on the foo table.";
2231 if ( /\b(foo)\s+(\w+)/i ) {
2232 print "$2 follows $1.\n";
2233 }
2234
2235When the match runs, the first part of the regular expression (C<\b(foo)>)
2236finds a possible match right at the beginning of the string, and loads up
2237C<$1> with "Foo". However, as soon as the matching engine sees that there's
2238no whitespace following the "Foo" that it had saved in C<$1>, it realizes its
2239mistake and starts over again one character after where it had the
2240tentative match. This time it goes all the way until the next occurrence
2241of "foo". The complete regular expression matches this time, and you get
2242the expected output of "table follows foo."
2243
2244Sometimes minimal matching can help a lot. Imagine you'd like to match
2245everything between "foo" and "bar". Initially, you write something
2246like this:
2247
2248 $_ = "The food is under the bar in the barn.";
2249 if ( /foo(.*)bar/ ) {
2250 print "got <$1>\n";
2251 }
2252
2253Which perhaps unexpectedly yields:
2254
2255 got <d is under the bar in the >
2256
2257That's because C<.*> was greedy, so you get everything between the
2258I<first> "foo" and the I<last> "bar". Here it's more effective
2259to use minimal matching to make sure you get the text between a "foo"
2260and the first "bar" thereafter.
2261
2262 if ( /foo(.*?)bar/ ) { print "got <$1>\n" }
2263 got <d is under the >
2264
2265Here's another example. Let's say you'd like to match a number at the end
2266of a string, and you also want to keep the preceding part of the match.
2267So you write this:
2268
2269 $_ = "I have 2 numbers: 53147";
2270 if ( /(.*)(\d*)/ ) { # Wrong!
2271 print "Beginning is <$1>, number is <$2>.\n";
2272 }
2273
2274That won't work at all, because C<.*> was greedy and gobbled up the
2275whole string. As C<\d*> can match on an empty string the complete
2276regular expression matched successfully.
2277
2278 Beginning is <I have 2 numbers: 53147>, number is <>.
2279
2280Here are some variants, most of which don't work:
2281
2282 $_ = "I have 2 numbers: 53147";
2283 @pats = qw{
2284 (.*)(\d*)
2285 (.*)(\d+)
2286 (.*?)(\d*)
2287 (.*?)(\d+)
2288 (.*)(\d+)$
2289 (.*?)(\d+)$
2290 (.*)\b(\d+)$
2291 (.*\D)(\d+)$
2292 };
2293
2294 for $pat (@pats) {
2295 printf "%-12s ", $pat;
2296 if ( /$pat/ ) {
2297 print "<$1> <$2>\n";
2298 } else {
2299 print "FAIL\n";
2300 }
2301 }
2302
2303That will print out:
2304
2305 (.*)(\d*) <I have 2 numbers: 53147> <>
2306 (.*)(\d+) <I have 2 numbers: 5314> <7>
2307 (.*?)(\d*) <> <>
2308 (.*?)(\d+) <I have > <2>
2309 (.*)(\d+)$ <I have 2 numbers: 5314> <7>
2310 (.*?)(\d+)$ <I have 2 numbers: > <53147>
2311 (.*)\b(\d+)$ <I have 2 numbers: > <53147>
2312 (.*\D)(\d+)$ <I have 2 numbers: > <53147>
2313
2314As you see, this can be a bit tricky. It's important to realize that a
2315regular expression is merely a set of assertions that gives a definition
2316of success. There may be 0, 1, or several different ways that the
2317definition might succeed against a particular string. And if there are
2318multiple ways it might succeed, you need to understand backtracking to
2319know which variety of success you will achieve.
2320
2321When using lookahead assertions and negations, this can all get even
2322trickier. Imagine you'd like to find a sequence of non-digits not
2323followed by "123". You might try to write that as
2324
2325 $_ = "ABC123";
2326 if ( /^\D*(?!123)/ ) { # Wrong!
2327 print "Yup, no 123 in $_\n";
2328 }
2329
2330But that isn't going to match; at least, not the way you're hoping. It
2331claims that there is no 123 in the string. Here's a clearer picture of
2332why that pattern matches, contrary to popular expectations:
2333
2334 $x = 'ABC123';
2335 $y = 'ABC445';
2336
2337 print "1: got $1\n" if $x =~ /^(ABC)(?!123)/;
2338 print "2: got $1\n" if $y =~ /^(ABC)(?!123)/;
2339
2340 print "3: got $1\n" if $x =~ /^(\D*)(?!123)/;
2341 print "4: got $1\n" if $y =~ /^(\D*)(?!123)/;
2342
2343This prints
2344
2345 2: got ABC
2346 3: got AB
2347 4: got ABC
2348
2349You might have expected test 3 to fail because it seems to a more
2350general purpose version of test 1. The important difference between
2351them is that test 3 contains a quantifier (C<\D*>) and so can use
2352backtracking, whereas test 1 will not. What's happening is
2353that you've asked "Is it true that at the start of C<$x>, following 0 or more
2354non-digits, you have something that's not 123?" If the pattern matcher had
2355let C<\D*> expand to "ABC", this would have caused the whole pattern to
2356fail.
2357
2358The search engine will initially match C<\D*> with "ABC". Then it will
2359try to match C<(?!123)> with "123", which fails. But because
2360a quantifier (C<\D*>) has been used in the regular expression, the
2361search engine can backtrack and retry the match differently
2362in the hope of matching the complete regular expression.
2363
2364The pattern really, I<really> wants to succeed, so it uses the
2365standard pattern back-off-and-retry and lets C<\D*> expand to just "AB" this
2366time. Now there's indeed something following "AB" that is not
2367"123". It's "C123", which suffices.
2368
2369We can deal with this by using both an assertion and a negation.
2370We'll say that the first part in C<$1> must be followed both by a digit
2371and by something that's not "123". Remember that the lookaheads
2372are zero-width expressions--they only look, but don't consume any
2373of the string in their match. So rewriting this way produces what
2374you'd expect; that is, case 5 will fail, but case 6 succeeds:
2375
2376 print "5: got $1\n" if $x =~ /^(\D*)(?=\d)(?!123)/;
2377 print "6: got $1\n" if $y =~ /^(\D*)(?=\d)(?!123)/;
2378
2379 6: got ABC
2380
2381In other words, the two zero-width assertions next to each other work as though
2382they're ANDed together, just as you'd use any built-in assertions: C</^$/>
2383matches only if you're at the beginning of the line AND the end of the
2384line simultaneously. The deeper underlying truth is that juxtaposition in
2385regular expressions always means AND, except when you write an explicit OR
2386using the vertical bar. C</ab/> means match "a" AND (then) match "b",
2387although the attempted matches are made at different positions because "a"
2388is not a zero-width assertion, but a one-width assertion.
2389
2390B<WARNING>: Particularly complicated regular expressions can take
2391exponential time to solve because of the immense number of possible
2392ways they can use backtracking to try for a match. For example, without
2393internal optimizations done by the regular expression engine, this will
2394take a painfully long time to run:
2395
2396 'aaaaaaaaaaaa' =~ /((a{0,5}){0,5})*[c]/
2397
2398And if you used C<"*">'s in the internal groups instead of limiting them
2399to 0 through 5 matches, then it would take forever--or until you ran
2400out of stack space. Moreover, these internal optimizations are not
2401always applicable. For example, if you put C<{0,5}> instead of C<"*">
2402on the external group, no current optimization is applicable, and the
2403match takes a long time to finish.
2404
2405A powerful tool for optimizing such beasts is what is known as an
2406"independent group",
2407which does not backtrack (see L</C<< (?>pattern) >>>). Note also that
2408zero-length lookahead/lookbehind assertions will not backtrack to make
2409the tail match, since they are in "logical" context: only
2410whether they match is considered relevant. For an example
2411where side-effects of lookahead I<might> have influenced the
2412following match, see L</C<< (?>pattern) >>>.
2413
e2e6a0f1
YO
2414=head2 Special Backtracking Control Verbs
2415
7711f978
KW
2416These special patterns are generally of the form C<(*I<VERB>:I<ARG>)>. Unless
2417otherwise stated the I<ARG> argument is optional; in some cases, it is
fee50582 2418mandatory.
e2e6a0f1
YO
2419
2420Any pattern containing a special backtracking verb that allows an argument
e1020413 2421has the special behaviour that when executed it sets the current package's
5d458dd8
YO
2422C<$REGERROR> and C<$REGMARK> variables. When doing so the following
2423rules apply:
e2e6a0f1 2424
7711f978 2425On failure, the C<$REGERROR> variable will be set to the I<ARG> value of the
5d458dd8 2426verb pattern, if the verb was involved in the failure of the match. If the
7711f978 2427I<ARG> part of the pattern was omitted, then C<$REGERROR> will be set to the
5d458dd8
YO
2428name of the last C<(*MARK:NAME)> pattern executed, or to TRUE if there was
2429none. Also, the C<$REGMARK> variable will be set to FALSE.
e2e6a0f1 2430
5d458dd8
YO
2431On a successful match, the C<$REGERROR> variable will be set to FALSE, and
2432the C<$REGMARK> variable will be set to the name of the last
2433C<(*MARK:NAME)> pattern executed. See the explanation for the
2434C<(*MARK:NAME)> verb below for more details.
e2e6a0f1 2435
5d458dd8 2436B<NOTE:> C<$REGERROR> and C<$REGMARK> are not magic variables like C<$1>
0b928c2f 2437and most other regex-related variables. They are not local to a scope, nor
5d458dd8 2438readonly, but instead are volatile package variables similar to C<$AUTOLOAD>.
ddb07903
AC
2439They are set in the package containing the code that I<executed> the regex
2440(rather than the one that compiled it, where those differ). If necessary, you
2441can use C<local> to localize changes to these variables to a specific scope
2442before executing a regex.
e2e6a0f1
YO
2443
2444If a pattern does not contain a special backtracking verb that allows an
5d458dd8 2445argument, then C<$REGERROR> and C<$REGMARK> are not touched at all.
e2e6a0f1 2446
70ca8714 2447=over 3
e2e6a0f1 2448
fee50582 2449=item Verbs
e2e6a0f1
YO
2450
2451=over 4
2452
5d458dd8 2453=item C<(*PRUNE)> C<(*PRUNE:NAME)>
f7819f85 2454X<(*PRUNE)> X<(*PRUNE:NAME)>
54612592 2455
5d458dd8 2456This zero-width pattern prunes the backtracking tree at the current point
a95b7a20 2457when backtracked into on failure. Consider the pattern C</I<A> (*PRUNE) I<B>/>,
7711f978
KW
2458where I<A> and I<B> are complex patterns. Until the C<(*PRUNE)> verb is reached,
2459I<A> may backtrack as necessary to match. Once it is reached, matching
2460continues in I<B>, which may also backtrack as necessary; however, should B
5d458dd8
YO
2461not match, then no further backtracking will take place, and the pattern
2462will fail outright at the current starting position.
54612592
YO
2463
2464The following example counts all the possible matching strings in a
2465pattern (without actually matching any of them).
2466
e2e6a0f1 2467 'aaab' =~ /a+b?(?{print "$&\n"; $count++})(*FAIL)/;
54612592
YO
2468 print "Count=$count\n";
2469
2470which produces:
2471
2472 aaab
2473 aaa
2474 aa
2475 a
2476 aab
2477 aa
2478 a
2479 ab
2480 a
2481 Count=9
2482
5d458dd8 2483If we add a C<(*PRUNE)> before the count like the following
54612592 2484
5d458dd8 2485 'aaab' =~ /a+b?(*PRUNE)(?{print "$&\n"; $count++})(*FAIL)/;
54612592
YO
2486 print "Count=$count\n";
2487
0b928c2f 2488we prevent backtracking and find the count of the longest matching string
353c6505 2489at each matching starting point like so:
54612592
YO
2490
2491 aaab
2492 aab
2493 ab
2494 Count=3
2495
5d458dd8 2496Any number of C<(*PRUNE)> assertions may be used in a pattern.
54612592 2497
4b05bc8e
KW
2498See also C<<< L<< /(?>pattern) >> >>> and possessive quantifiers for
2499other ways to
5d458dd8
YO
2500control backtracking. In some cases, the use of C<(*PRUNE)> can be
2501replaced with a C<< (?>pattern) >> with no functional difference; however,
2502C<(*PRUNE)> can be used to handle cases that cannot be expressed using a
2503C<< (?>pattern) >> alone.
54612592 2504
5d458dd8
YO
2505=item C<(*SKIP)> C<(*SKIP:NAME)>
2506X<(*SKIP)>
e2e6a0f1 2507
5d458dd8 2508This zero-width pattern is similar to C<(*PRUNE)>, except that on
e2e6a0f1 2509failure it also signifies that whatever text that was matched leading up
5d458dd8
YO
2510to the C<(*SKIP)> pattern being executed cannot be part of I<any> match
2511of this pattern. This effectively means that the regex engine "skips" forward
2512to this position on failure and tries to match again, (assuming that
2513there is sufficient room to match).
2514
2515The name of the C<(*SKIP:NAME)> pattern has special significance. If a
2516C<(*MARK:NAME)> was encountered while matching, then it is that position
2517which is used as the "skip point". If no C<(*MARK)> of that name was
2518encountered, then the C<(*SKIP)> operator has no effect. When used
2519without a name the "skip point" is where the match point was when
7711f978 2520executing the C<(*SKIP)> pattern.
5d458dd8 2521
0b928c2f 2522Compare the following to the examples in C<(*PRUNE)>; note the string
24b23f37
YO
2523is twice as long:
2524
d1fbf752
KW
2525 'aaabaaab' =~ /a+b?(*SKIP)(?{print "$&\n"; $count++})(*FAIL)/;
2526 print "Count=$count\n";
24b23f37
YO
2527
2528outputs
2529
2530 aaab
2531 aaab
2532 Count=2
2533
5d458dd8 2534Once the 'aaab' at the start of the string has matched, and the C<(*SKIP)>
353c6505 2535executed, the next starting point will be where the cursor was when the
5d458dd8
YO
2536C<(*SKIP)> was executed.
2537
5d458dd8 2538=item C<(*MARK:NAME)> C<(*:NAME)>
b16db30f 2539X<(*MARK)> X<(*MARK:NAME)> X<(*:NAME)>
5d458dd8
YO
2540
2541This zero-width pattern can be used to mark the point reached in a string
2542when a certain part of the pattern has been successfully matched. This
2543mark may be given a name. A later C<(*SKIP)> pattern will then skip
2544forward to that point if backtracked into on failure. Any number of
7711f978 2545C<(*MARK)> patterns are allowed, and the I<NAME> portion may be duplicated.
5d458dd8
YO
2546
2547In addition to interacting with the C<(*SKIP)> pattern, C<(*MARK:NAME)>
2548can be used to "label" a pattern branch, so that after matching, the
2549program can determine which branches of the pattern were involved in the
2550match.
2551
2552When a match is successful, the C<$REGMARK> variable will be set to the
2553name of the most recently executed C<(*MARK:NAME)> that was involved
2554in the match.
2555
2556This can be used to determine which branch of a pattern was matched
c27a5cfe 2557without using a separate capture group for each branch, which in turn
5d458dd8
YO
2558can result in a performance improvement, as perl cannot optimize
2559C</(?:(x)|(y)|(z))/> as efficiently as something like
2560C</(?:x(*MARK:x)|y(*MARK:y)|z(*MARK:z))/>.
2561
2562When a match has failed, and unless another verb has been involved in
2563failing the match and has provided its own name to use, the C<$REGERROR>
2564variable will be set to the name of the most recently executed
2565C<(*MARK:NAME)>.
2566
42ac7c82 2567See L</(*SKIP)> for more details.
5d458dd8 2568
b62d2d15
YO
2569As a shortcut C<(*MARK:NAME)> can be written C<(*:NAME)>.
2570
5d458dd8
YO
2571=item C<(*THEN)> C<(*THEN:NAME)>
2572
ac9d8485 2573This is similar to the "cut group" operator C<::> from Perl 6. Like
5d458dd8
YO
2574C<(*PRUNE)>, this verb always matches, and when backtracked into on
2575failure, it causes the regex engine to try the next alternation in the
ac9d8485
FC
2576innermost enclosing group (capturing or otherwise) that has alternations.
2577The two branches of a C<(?(condition)yes-pattern|no-pattern)> do not
2578count as an alternation, as far as C<(*THEN)> is concerned.
5d458dd8
YO
2579
2580Its name comes from the observation that this operation combined with the
7711f978 2581alternation operator (C<"|">) can be used to create what is essentially a
5d458dd8
YO
2582pattern-based if/then/else block:
2583
2584 ( COND (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ )
2585
2586Note that if this operator is used and NOT inside of an alternation then
2587it acts exactly like the C<(*PRUNE)> operator.
2588
2589 / A (*PRUNE) B /
2590
2591is the same as
2592
2593 / A (*THEN) B /
2594
2595but
2596
25e26d77 2597 / ( A (*THEN) B | C ) /
5d458dd8
YO
2598
2599is not the same as
2600
25e26d77 2601 / ( A (*PRUNE) B | C ) /
5d458dd8 2602
7711f978
KW
2603as after matching the I<A> but failing on the I<B> the C<(*THEN)> verb will
2604backtrack and try I<C>; but the C<(*PRUNE)> verb will simply fail.
24b23f37 2605
fee50582 2606=item C<(*COMMIT)> C<(*COMMIT:args)>
e2e6a0f1 2607X<(*COMMIT)>
24b23f37 2608
241e7389 2609This is the Perl 6 "commit pattern" C<< <commit> >> or C<:::>. It's a
5d458dd8
YO
2610zero-width pattern similar to C<(*SKIP)>, except that when backtracked
2611into on failure it causes the match to fail outright. No further attempts
2612to find a valid match by advancing the start pointer will occur again.
2613For example,
24b23f37 2614
d1fbf752
KW
2615 'aaabaaab' =~ /a+b?(*COMMIT)(?{print "$&\n"; $count++})(*FAIL)/;
2616 print "Count=$count\n";
24b23f37
YO
2617
2618outputs
2619
2620 aaab
2621 Count=1
2622
e2e6a0f1
YO
2623In other words, once the C<(*COMMIT)> has been entered, and if the pattern
2624does not match, the regex engine will not try any further matching on the
2625rest of the string.
c277df42 2626
fee50582 2627=item C<(*FAIL)> C<(*F)> C<(*FAIL:arg)>
e2e6a0f1 2628X<(*FAIL)> X<(*F)>
9af228c6 2629
e2e6a0f1
YO
2630This pattern matches nothing and always fails. It can be used to force the
2631engine to backtrack. It is equivalent to C<(?!)>, but easier to read. In
fee50582 2632fact, C<(?!)> gets optimised into C<(*FAIL)> internally. You can provide
7711f978
KW
2633an argument so that if the match fails because of this C<FAIL> directive
2634the argument can be obtained from C<$REGERROR>.
9af228c6 2635
e2e6a0f1 2636It is probably useful only when combined with C<(?{})> or C<(??{})>.
9af228c6 2637
fee50582 2638=item C<(*ACCEPT)> C<(*ACCEPT:arg)>
e2e6a0f1 2639X<(*ACCEPT)>
9af228c6 2640
e2e6a0f1
YO
2641This pattern matches nothing and causes the end of successful matching at
2642the point at which the C<(*ACCEPT)> pattern was encountered, regardless of
2643whether there is actually more to match in the string. When inside of a
0d017f4d 2644nested pattern, such as recursion, or in a subpattern dynamically generated
e2e6a0f1 2645via C<(??{})>, only the innermost pattern is ended immediately.
9af228c6 2646
c27a5cfe 2647If the C<(*ACCEPT)> is inside of capturing groups then the groups are
e2e6a0f1
YO
2648marked as ended at the point at which the C<(*ACCEPT)> was encountered.
2649For instance:
9af228c6 2650
e2e6a0f1 2651 'AB' =~ /(A (A|B(*ACCEPT)|C) D)(E)/x;
9af228c6 2652
57fbbe96 2653will match, and C<$1> will be C<AB> and C<$2> will be C<"B">, C<$3> will not
0b928c2f 2654be set. If another branch in the inner parentheses was matched, such as in the
57fbbe96 2655string 'ACDE', then the C<"D"> and C<"E"> would have to be matched as well.
9af228c6 2656
7711f978
KW
2657You can provide an argument, which will be available in the var
2658C<$REGMARK> after the match completes.
fee50582 2659
9af228c6 2660=back
c277df42 2661
a0d0e21e
LW
2662=back
2663
7711f978 2664=head2 Warning on C<\1> Instead of C<$1>
cb1a09d0 2665
5a964f20 2666Some people get too used to writing things like:
cb1a09d0
AD
2667
2668 $pattern =~ s/(\W)/\\\1/g;
2669
3ff1c45a
KW
2670This is grandfathered (for \1 to \9) for the RHS of a substitute to avoid
2671shocking the
cb1a09d0 2672B<sed> addicts, but it's a dirty habit to get into. That's because in
d1be9408 2673PerlThink, the righthand side of an C<s///> is a double-quoted string. C<\1> in
cb1a09d0
AD
2674the usual double-quoted string means a control-A. The customary Unix
2675meaning of C<\1> is kludged in for C<s///>. However, if you get into the habit
2676of doing that, you get yourself into trouble if you then add an C</e>
2677modifier.
2678
f793d64a 2679 s/(\d+)/ \1 + 1 /eg; # causes warning under -w
cb1a09d0
AD
2680
2681Or if you try to do
2682
2683 s/(\d+)/\1000/;
2684
2685You can't disambiguate that by saying C<\{1}000>, whereas you can fix it with
14218588 2686C<${1}000>. The operation of interpolation should not be confused
cb1a09d0
AD
2687with the operation of matching a backreference. Certainly they mean two
2688different things on the I<left> side of the C<s///>.
9fa51da4 2689
0d017f4d 2690=head2 Repeated Patterns Matching a Zero-length Substring
c84d73f1 2691
19799a22 2692B<WARNING>: Difficult material (and prose) ahead. This section needs a rewrite.
c84d73f1
IZ
2693
2694Regular expressions provide a terse and powerful programming language. As
2695with most other power tools, power comes together with the ability
2696to wreak havoc.
2697
2698A common abuse of this power stems from the ability to make infinite
628afcb5 2699loops using regular expressions, with something as innocuous as:
c84d73f1
IZ
2700
2701 'foo' =~ m{ ( o? )* }x;
2702
57fbbe96 2703The C<o?> matches at the beginning of "C<foo>", and since the position
c84d73f1 2704in the string is not moved by the match, C<o?> would match again and again
7711f978 2705because of the C<"*"> quantifier. Another common way to create a similar cycle
f1dc5bb2 2706is with the looping modifier C</g>:
c84d73f1
IZ
2707
2708 @matches = ( 'foo' =~ m{ o? }xg );
2709
2710or
2711
2712 print "match: <$&>\n" while 'foo' =~ m{ o? }xg;
2713
7711f978 2714or the loop implied by C<split()>.
c84d73f1
IZ
2715
2716However, long experience has shown that many programming tasks may
14218588
GS
2717be significantly simplified by using repeated subexpressions that
2718may match zero-length substrings. Here's a simple example being:
c84d73f1 2719
d1fbf752 2720 @chars = split //, $string; # // is not magic in split
c84d73f1
IZ
2721 ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /
2722
9da458fc 2723Thus Perl allows such constructs, by I<forcefully breaking
c84d73f1 2724the infinite loop>. The rules for this are different for lower-level
527e91da 2725loops given by the greedy quantifiers C<*+{}>, and for higher-level
7711f978 2726ones like the C</g> modifier or C<split()> operator.
c84d73f1 2727
19799a22
GS
2728The lower-level loops are I<interrupted> (that is, the loop is
2729broken) when Perl detects that a repeated expression matched a
2730zero-length substring. Thus
c84d73f1
IZ
2731
2732 m{ (?: NON_ZERO_LENGTH | ZERO_LENGTH )* }x;
2733
5d458dd8 2734is made equivalent to
c84d73f1 2735
0b928c2f
FC
2736 m{ (?: NON_ZERO_LENGTH )* (?: ZERO_LENGTH )? }x;
2737
2738For example, this program
2739
2740 #!perl -l
2741 "aaaaab" =~ /
2742 (?:
2743 a # non-zero
2744 | # or
2745 (?{print "hello"}) # print hello whenever this
2746 # branch is tried
2747 (?=(b)) # zero-width assertion
2748 )* # any number of times
2749 /x;
2750 print $&;
2751 print $1;
c84d73f1 2752
0b928c2f
FC
2753prints
2754
2755 hello
2756 aaaaa
2757 b
2758
2759Notice that "hello" is only printed once, as when Perl sees that the sixth
2760iteration of the outermost C<(?:)*> matches a zero-length string, it stops
7711f978 2761the C<"*">.
0b928c2f
FC
2762
2763The higher-level loops preserve an additional state between iterations:
5d458dd8 2764whether the last match was zero-length. To break the loop, the following
c84d73f1 2765match after a zero-length match is prohibited to have a length of zero.
5a0de581 2766This prohibition interacts with backtracking (see L</"Backtracking">),
c84d73f1
IZ
2767and so the I<second best> match is chosen if the I<best> match is of
2768zero length.
2769
19799a22 2770For example:
c84d73f1
IZ
2771
2772 $_ = 'bar';
2773 s/\w??/<$&>/g;
2774
20fb949f 2775results in C<< <><b><><a><><r><> >>. At each position of the string the best
5d458dd8 2776match given by non-greedy C<??> is the zero-length match, and the I<second
c84d73f1
IZ
2777best> match is what is matched by C<\w>. Thus zero-length matches
2778alternate with one-character-long matches.
2779
5d458dd8 2780Similarly, for repeated C<m/()/g> the second-best match is the match at the
c84d73f1
IZ
2781position one notch further in the string.
2782
19799a22 2783The additional state of being I<matched with zero-length> is associated with
7711f978 2784the matched string, and is reset by each assignment to C<pos()>.
9da458fc
IZ
2785Zero-length matches at the end of the previous match are ignored
2786during C<split>.
c84d73f1 2787
0d017f4d 2788=head2 Combining RE Pieces
35a734be
IZ
2789
2790Each of the elementary pieces of regular expressions which were described
2791before (such as C<ab> or C<\Z>) could match at most one substring
2792at the given position of the input string. However, in a typical regular
2793expression these elementary pieces are combined into more complicated
57fbbe96
KW
2794patterns using combining operators C<ST>, C<S|T>, C<S*> I<etc>.
2795(in these examples C<"S"> and C<"T"> are regular subexpressions).
35a734be
IZ
2796
2797Such combinations can include alternatives, leading to a problem of choice:
2798if we match a regular expression C<a|ab> against C<"abc">, will it match
2799substring C<"a"> or C<"ab">? One way to describe which substring is
5a0de581 2800actually matched is the concept of backtracking (see L</"Backtracking">).
35a734be
IZ
2801However, this description is too low-level and makes you think
2802in terms of a particular implementation.
2803
2804Another description starts with notions of "better"/"worse". All the
2805substrings which may be matched by the given regular expression can be
2806sorted from the "best" match to the "worst" match, and it is the "best"
2807match which is chosen. This substitutes the question of "what is chosen?"
2808by the question of "which matches are better, and which are worse?".
2809
2810Again, for elementary pieces there is no such question, since at most
2811one match at a given position is possible. This section describes the
2812notion of better/worse for combining operators. In the description
57fbbe96 2813below C<"S"> and C<"T"> are regular subexpressions.
35a734be 2814
13a2d996 2815=over 4
35a734be
IZ
2816
2817=item C<ST>
2818
57fbbe96
KW
2819Consider two possible matches, C<AB> and C<A'B'>, C<"A"> and C<A'> are
2820substrings which can be matched by C<"S">, C<"B"> and C<B'> are substrings
2821which can be matched by C<"T">.
35a734be 2822
57fbbe96 2823If C<"A"> is a better match for C<"S"> than C<A'>, C<AB> is a better
35a734be
IZ
2824match than C<A'B'>.
2825
57fbbe96
KW
2826If C<"A"> and C<A'> coincide: C<AB> is a better match than C<AB'> if
2827C<"B"> is a better match for C<"T"> than C<B'>.
35a734be
IZ
2828
2829=item C<S|T>
2830
57fbbe96 2831When C<"S"> can match, it is a better match than when only C<"T"> can match.
35a734be 2832
57fbbe96
KW
2833Ordering of two matches for C<"S"> is the same as for C<"S">. Similar for
2834two matches for C<"T">.
35a734be
IZ
2835
2836=item C<S{REPEAT_COUNT}>
2837
2838Matches as C<SSS...S> (repeated as many times as necessary).
2839
2840=item C<S{min,max}>
2841
2842Matches as C<S{max}|S{max-1}|...|S{min+1}|S{min}>.
2843
2844=item C<S{min,max}?>
2845
2846Matches as C<S{min}|S{min+1}|...|S{max-1}|S{max}>.
2847
2848=item C<S?>, C<S*>, C<S+>
2849
2850Same as C<S{0,1}>, C<S{0,BIG_NUMBER}>, C<S{1,BIG_NUMBER}> respectively.
2851
2852=item C<S??>, C<S*?>, C<S+?>
2853
2854Same as C<S{0,1}?>, C<S{0,BIG_NUMBER}?>, C<S{1,BIG_NUMBER}?> respectively.
2855
c47ff5f1 2856=item C<< (?>S) >>
35a734be 2857
57fbbe96 2858Matches the best match for C<"S"> and only that.
35a734be
IZ
2859
2860=item C<(?=S)>, C<(?<=S)>
2861
57fbbe96
KW
2862Only the best match for C<"S"> is considered. (This is important only if
2863C<"S"> has capturing parentheses, and backreferences are used somewhere
35a734be
IZ
2864else in the whole regular expression.)
2865
2866=item C<(?!S)>, C<(?<!S)>
2867
2868For this grouping operator there is no need to describe the ordering, since
57fbbe96 2869only whether or not C<"S"> can match is important.
35a734be 2870
93f313ef 2871=item C<(??{ EXPR })>, C<(?I<PARNO>)>
35a734be
IZ
2872
2873The ordering is the same as for the regular expression which is
93f313ef 2874the result of EXPR, or the pattern contained by capture group I<PARNO>.
35a734be
IZ
2875
2876=item C<(?(condition)yes-pattern|no-pattern)>
2877
2878Recall that which of C<yes-pattern> or C<no-pattern> actually matches is
2879already determined. The ordering of the matches is the same as for the
2880chosen subexpression.
2881
2882=back
2883
2884The above recipes describe the ordering of matches I<at a given position>.
2885One more rule is needed to understand how a match is determined for the
2886whole regular expression: a match at an earlier position is always better
2887than a match at a later position.
2888
0d017f4d 2889=head2 Creating Custom RE Engines
c84d73f1 2890
0b928c2f
FC
2891As of Perl 5.10.0, one can create custom regular expression engines. This
2892is not for the faint of heart, as they have to plug in at the C level. See
2893L<perlreapi> for more details.
2894
2895As an alternative, overloaded constants (see L<overload>) provide a simple
2896way to extend the functionality of the RE engine, by substituting one
2897pattern for another.
c84d73f1
IZ
2898
2899Suppose that we want to enable a new RE escape-sequence C<\Y|> which
0d017f4d 2900matches at a boundary between whitespace characters and non-whitespace
c84d73f1
IZ
2901characters. Note that C<(?=\S)(?<!\S)|(?!\S)(?<=\S)> matches exactly
2902at these positions, so we want to have each C<\Y|> in the place of the
2903more complicated version. We can create a module C<customre> to do
2904this:
2905
2906 package customre;
2907 use overload;
2908
2909 sub import {
2910 shift;
2911 die "No argument to customre::import allowed" if @_;
2912 overload::constant 'qr' => \&convert;
2913 }
2914
2915 sub invalid { die "/$_[0]/: invalid escape '\\$_[1]'"}
2916
580a9fe1
RGS
2917 # We must also take care of not escaping the legitimate \\Y|
2918 # sequence, hence the presence of '\\' in the conversion rules.
5d458dd8 2919 my %rules = ( '\\' => '\\\\',
f793d64a 2920 'Y|' => qr/(?=\S)(?<!\S)|(?!\S)(?<=\S)/ );
c84d73f1
IZ
2921 sub convert {
2922 my $re = shift;
5d458dd8 2923 $re =~ s{
c84d73f1
IZ
2924 \\ ( \\ | Y . )
2925 }
5d458dd8 2926 { $rules{$1} or invalid($re,$1) }sgex;
c84d73f1
IZ
2927 return $re;
2928 }
2929
2930Now C<use customre> enables the new escape in constant regular
57fbbe96 2931expressions, I<i.e.>, those without any runtime variable interpolations.
c84d73f1
IZ
2932As documented in L<overload>, this conversion will work only over
2933literal parts of regular expressions. For C<\Y|$re\Y|> the variable
2934part of this regular expression needs to be converted explicitly
7711f978 2935(but only if the special meaning of C<\Y|> should be enabled inside C<$re>):
c84d73f1
IZ
2936
2937 use customre;
2938 $re = <>;
2939 chomp $re;
2940 $re = customre::convert $re;
2941 /\Y|$re\Y|/;
2942
83f32aba
RS
2943=head2 Embedded Code Execution Frequency
2944
57fbbe96 2945The exact rules for how often C<(??{})> and C<(?{})> are executed in a pattern
83f32aba
RS
2946are unspecified. In the case of a successful match you can assume that
2947they DWIM and will be executed in left to right order the appropriate
2948number of times in the accepting path of the pattern as would any other
2949meta-pattern. How non-accepting pathways and match failures affect the
2950number of times a pattern is executed is specifically unspecified and
2951may vary depending on what optimizations can be applied to the pattern
2952and is likely to change from version to version.
2953
2954For instance in
2955
2956 "aaabcdeeeee"=~/a(?{print "a"})b(?{print "b"})cde/;
2957
2958the exact number of times "a" or "b" are printed out is unspecified for
2959failure, but you may assume they will be printed at least once during
2960a successful match, additionally you may assume that if "b" is printed,
2961it will be preceded by at least one "a".
2962
2963In the case of branching constructs like the following:
2964
2965 /a(b|(?{ print "a" }))c(?{ print "c" })/;
2966
2967you can assume that the input "ac" will output "ac", and that "abc"
2968will output only "c".
2969
2970When embedded code is quantified, successful matches will call the
2971code once for each matched iteration of the quantifier. For
2972example:
2973
2974 "good" =~ /g(?:o(?{print "o"}))*d/;
2975
2976will output "o" twice.
2977
0b928c2f 2978=head2 PCRE/Python Support
1f1031fe 2979
0b928c2f 2980As of Perl 5.10.0, Perl supports several Python/PCRE-specific extensions
1f1031fe 2981to the regex syntax. While Perl programmers are encouraged to use the
0b928c2f 2982Perl-specific syntax, the following are also accepted:
1f1031fe
YO
2983
2984=over 4
2985
ae5648b3 2986=item C<< (?PE<lt>NAMEE<gt>pattern) >>
1f1031fe 2987
c27a5cfe 2988Define a named capture group. Equivalent to C<< (?<NAME>pattern) >>.
1f1031fe
YO
2989
2990=item C<< (?P=NAME) >>
2991
c27a5cfe 2992Backreference to a named capture group. Equivalent to C<< \g{NAME} >>.
1f1031fe
YO
2993
2994=item C<< (?P>NAME) >>
2995
c27a5cfe 2996Subroutine call to a named capture group. Equivalent to C<< (?&NAME) >>.
1f1031fe 2997
ee9b8eae 2998=back
1f1031fe 2999
19799a22
GS
3000=head1 BUGS
3001
ed7efc79 3002There are a number of issues with regard to case-insensitive matching
57fbbe96 3003in Unicode rules. See C<"i"> under L</Modifiers> above.
ed7efc79 3004
9da458fc
IZ
3005This document varies from difficult to understand to completely
3006and utterly opaque. The wandering prose riddled with jargon is
3007hard to fathom in several places.
3008
3009This document needs a rewrite that separates the tutorial content
3010from the reference content.
19799a22
GS
3011
3012=head1 SEE ALSO
9fa51da4 3013
c57a3350
KW
3014The syntax of patterns used in Perl pattern matching evolved from those
3015supplied in the Bell Labs Research Unix 8th Edition (Version 8) regex
3016routines. (The code is actually derived (distantly) from Henry
3017Spencer's freely redistributable reimplementation of those V8 routines.)
3018
91e0c79e
MJD
3019L<perlrequick>.
3020
3021L<perlretut>.
3022
9b599b2a
GS
3023L<perlop/"Regexp Quote-Like Operators">.
3024
1e66bd83
PP
3025L<perlop/"Gory details of parsing quoted constructs">.
3026
14218588
GS
3027L<perlfaq6>.
3028
9b599b2a
GS
3029L<perlfunc/pos>.
3030
3031L<perllocale>.
3032
fb55449c
JH
3033L<perlebcdic>.
3034
14218588
GS
3035I<Mastering Regular Expressions> by Jeffrey Friedl, published
3036by O'Reilly and Associates.