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