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