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