This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add Unicode property wildcards
[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
FC
927help. See the independent subexpression
928L</C<< (?>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
1038Note that C<\N> has two meanings. When of the form C<\N{NAME}>, it matches the
fb121860
KW
1039character or character sequence whose name is C<NAME>; and similarly
1040when of the form C<\N{U+I<hex>}>, it matches the character whose Unicode
1041code point is I<hex>. Otherwise it matches any character but C<\n>.
9bb1f947 1042
572224ce
KW
1043=item [8]
1044
1045See L<perlrecharclass/Extended Bracketed Character Classes> for details.
1046
9bb1f947 1047=back
d0b16107 1048
04838cea
RGS
1049=head3 Assertions
1050
c57a3350
KW
1051Besides L<C<"^"> and C<"$">|/Metacharacters>, Perl defines the following
1052zero-width assertions:
d74e8afc
ITB
1053X<zero-width assertion> X<assertion> X<regex, zero-width assertion>
1054X<regexp, zero-width assertion>
1055X<regular expression, zero-width assertion>
1056X<\b> X<\B> X<\A> X<\Z> X<\z> X<\G>
a0d0e21e 1057
c57a3350
KW
1058 \b{} Match at Unicode boundary of specified type
1059 \B{} Match where corresponding \b{} doesn't match
1060 \b Match a \w\W or \W\w boundary
1061 \B Match except at a \w\W or \W\w boundary
1062 \A Match only at beginning of string
1063 \Z Match only at end of string, or before newline at the end
1064 \z Match only at end of string
1065 \G Match only at pos() (e.g. at the end-of-match position
9da458fc 1066 of prior m//g)
a0d0e21e 1067
64935bc6
KW
1068A Unicode boundary (C<\b{}>), available starting in v5.22, is a spot
1069between two characters, or before the first character in the string, or
1070after the final character in the string where certain criteria defined
1071by Unicode are met. See L<perlrebackslash/\b{}, \b, \B{}, \B> for
1072details.
1073
14218588 1074A word boundary (C<\b>) is a spot between two characters
19799a22
GS
1075that has a C<\w> on one side of it and a C<\W> on the other side
1076of it (in either order), counting the imaginary characters off the
1077beginning and end of the string as matching a C<\W>. (Within
1078character classes C<\b> represents backspace rather than a word
1079boundary, just as it normally does in any double-quoted string.)
7711f978 1080The C<\A> and C<\Z> are just like C<"^"> and C<"$">, except that they
19799a22 1081won't match multiple times when the C</m> modifier is used, while
7711f978 1082C<"^"> and C<"$"> will match at every internal line boundary. To match
19799a22
GS
1083the actual end of the string and not ignore an optional trailing
1084newline, use C<\z>.
d74e8afc 1085X<\b> X<\A> X<\Z> X<\z> X</m>
19799a22
GS
1086
1087The C<\G> assertion can be used to chain global matches (using
1088C<m//g>), as described in L<perlop/"Regexp Quote-Like Operators">.
1089It is also useful when writing C<lex>-like scanners, when you have
1090several patterns that you want to match against consequent substrings
0b928c2f 1091of your string; see the previous reference. The actual location
19799a22 1092where C<\G> will match can also be influenced by using C<pos()> as
58e23c8d 1093an lvalue: see L<perlfunc/pos>. Note that the rule for zero-length
0b928c2f
FC
1094matches (see L</"Repeated Patterns Matching a Zero-length Substring">)
1095is modified somewhat, in that contents to the left of C<\G> are
58e23c8d
YO
1096not counted when determining the length of the match. Thus the following
1097will not match forever:
d74e8afc 1098X<\G>
c47ff5f1 1099
e761bb84
CO
1100 my $string = 'ABC';
1101 pos($string) = 1;
1102 while ($string =~ /(.\G)/g) {
1103 print $1;
1104 }
58e23c8d
YO
1105
1106It will print 'A' and then terminate, as it considers the match to
1107be zero-width, and thus will not match at the same position twice in a
1108row.
1109
1110It is worth noting that C<\G> improperly used can result in an infinite
1111loop. Take care when using patterns that include C<\G> in an alternation.
1112
d5e7783a
DM
1113Note also that C<s///> will refuse to overwrite part of a substitution
1114that has already been replaced; so for example this will stop after the
1115first iteration, rather than iterating its way backwards through the
1116string:
1117
1118 $_ = "123456789";
1119 pos = 6;
1120 s/.(?=.\G)/X/g;
1121 print; # prints 1234X6789, not XXXXX6789
1122
1123
c27a5cfe 1124=head3 Capture groups
04838cea 1125
3644e48f 1126The grouping construct C<( ... )> creates capture groups (also referred to as
c27a5cfe 1127capture buffers). To refer to the current contents of a group later on, within
d8b950dc
KW
1128the same pattern, use C<\g1> (or C<\g{1}>) for the first, C<\g2> (or C<\g{2}>)
1129for the second, and so on.
1130This is called a I<backreference>.
d74e8afc 1131X<regex, capture buffer> X<regexp, capture buffer>
c27a5cfe 1132X<regex, capture group> X<regexp, capture group>
d74e8afc 1133X<regular expression, capture buffer> X<backreference>
c27a5cfe 1134X<regular expression, capture group> X<backreference>
1f1031fe 1135X<\g{1}> X<\g{-1}> X<\g{name}> X<relative backreference> X<named backreference>
d8b950dc
KW
1136X<named capture buffer> X<regular expression, named capture buffer>
1137X<named capture group> X<regular expression, named capture group>
1138X<%+> X<$+{name}> X<< \k<name> >>
1139There is no limit to the number of captured substrings that you may use.
57fbbe96 1140Groups are numbered with the leftmost open parenthesis being number 1, I<etc>. If
d8b950dc
KW
1141a group did not match, the associated backreference won't match either. (This
1142can happen if the group is optional, or in a different branch of an
1143alternation.)
57fbbe96 1144You can omit the C<"g">, and write C<"\1">, I<etc>, but there are some issues with
d8b950dc
KW
1145this form, described below.
1146
1147You can also refer to capture groups relatively, by using a negative number, so
1148that C<\g-1> and C<\g{-1}> both refer to the immediately preceding capture
1149group, and C<\g-2> and C<\g{-2}> both refer to the group before it. For
1150example:
5624f11d
YO
1151
1152 /
c27a5cfe
KW
1153 (Y) # group 1
1154 ( # group 2
1155 (X) # group 3
1156 \g{-1} # backref to group 3
1157 \g{-3} # backref to group 1
5624f11d
YO
1158 )
1159 /x
1160
d8b950dc
KW
1161would match the same as C</(Y) ( (X) \g3 \g1 )/x>. This allows you to
1162interpolate regexes into larger regexes and not have to worry about the
1163capture groups being renumbered.
1164
1165You can dispense with numbers altogether and create named capture groups.
1166The notation is C<(?E<lt>I<name>E<gt>...)> to declare and C<\g{I<name>}> to
1167reference. (To be compatible with .Net regular expressions, C<\g{I<name>}> may
1168also be written as C<\k{I<name>}>, C<\kE<lt>I<name>E<gt>> or C<\k'I<name>'>.)
1169I<name> must not begin with a number, nor contain hyphens.
1170When different groups within the same pattern have the same name, any reference
1171to that name assumes the leftmost defined group. Named groups count in
1172absolute and relative numbering, and so can also be referred to by those
1173numbers.
1174(It's possible to do things with named capture groups that would otherwise
1175require C<(??{})>.)
1176
1177Capture group contents are dynamically scoped and available to you outside the
1178pattern until the end of the enclosing block or until the next successful
1179match, whichever comes first. (See L<perlsyn/"Compound Statements">.)
1180You can refer to them by absolute number (using C<"$1"> instead of C<"\g1">,
57fbbe96 1181I<etc>); or by name via the C<%+> hash, using C<"$+{I<name>}">.
d8b950dc
KW
1182
1183Braces are required in referring to named capture groups, but are optional for
1184absolute or relative numbered ones. Braces are safer when creating a regex by
1185concatenating smaller strings. For example if you have C<qr/$a$b/>, and C<$a>
1186contained C<"\g1">, and C<$b> contained C<"37">, you would get C</\g137/> which
1187is probably not what you intended.
1188
1189The C<\g> and C<\k> notations were introduced in Perl 5.10.0. Prior to that
1190there were no named nor relative numbered capture groups. Absolute numbered
0b928c2f 1191groups were referred to using C<\1>,
57fbbe96 1192C<\2>, I<etc>., and this notation is still
d8b950dc
KW
1193accepted (and likely always will be). But it leads to some ambiguities if
1194there are more than 9 capture groups, as C<\10> could mean either the tenth
1195capture group, or the character whose ordinal in octal is 010 (a backspace in
1196ASCII). Perl resolves this ambiguity by interpreting C<\10> as a backreference
1197only if at least 10 left parentheses have opened before it. Likewise C<\11> is
1198a backreference only if at least 11 left parentheses have opened before it.
e1f120a9
KW
1199And so on. C<\1> through C<\9> are always interpreted as backreferences.
1200There are several examples below that illustrate these perils. You can avoid
1201the ambiguity by always using C<\g{}> or C<\g> if you mean capturing groups;
1202and for octal constants always using C<\o{}>, or for C<\077> and below, using 3
1203digits padded with leading zeros, since a leading zero implies an octal
1204constant.
d8b950dc
KW
1205
1206The C<\I<digit>> notation also works in certain circumstances outside
ed7efc79 1207the pattern. See L</Warning on \1 Instead of $1> below for details.
81714fb9 1208
14218588 1209Examples:
a0d0e21e
LW
1210
1211 s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words
1212
d8b950dc 1213 /(.)\g1/ # find first doubled char
81714fb9
YO
1214 and print "'$1' is the first doubled character\n";
1215
1216 /(?<char>.)\k<char>/ # ... a different way
1217 and print "'$+{char}' is the first doubled character\n";
1218
d8b950dc 1219 /(?'char'.)\g1/ # ... mix and match
81714fb9 1220 and print "'$1' is the first doubled character\n";
c47ff5f1 1221
14218588 1222 if (/Time: (..):(..):(..)/) { # parse out values
f793d64a
KW
1223 $hours = $1;
1224 $minutes = $2;
1225 $seconds = $3;
a0d0e21e 1226 }
c47ff5f1 1227
9d860678
KW
1228 /(.)(.)(.)(.)(.)(.)(.)(.)(.)\g10/ # \g10 is a backreference
1229 /(.)(.)(.)(.)(.)(.)(.)(.)(.)\10/ # \10 is octal
1230 /((.)(.)(.)(.)(.)(.)(.)(.)(.))\10/ # \10 is a backreference
1231 /((.)(.)(.)(.)(.)(.)(.)(.)(.))\010/ # \010 is octal
1232
1233 $a = '(.)\1'; # Creates problems when concatenated.
1234 $b = '(.)\g{1}'; # Avoids the problems.
1235 "aa" =~ /${a}/; # True
1236 "aa" =~ /${b}/; # True
1237 "aa0" =~ /${a}0/; # False!
1238 "aa0" =~ /${b}0/; # True
dc0d9c48
KW
1239 "aa\x08" =~ /${a}0/; # True!
1240 "aa\x08" =~ /${b}0/; # False
9d860678 1241
14218588
GS
1242Several special variables also refer back to portions of the previous
1243match. C<$+> returns whatever the last bracket match matched.
1244C<$&> returns the entire matched string. (At one point C<$0> did
1245also, but now it returns the name of the program.) C<$`> returns
77ea4f6d
JV
1246everything before the matched string. C<$'> returns everything
1247after the matched string. And C<$^N> contains whatever was matched by
1248the most-recently closed group (submatch). C<$^N> can be used in
1249extended patterns (see below), for example to assign a submatch to a
81714fb9 1250variable.
d74e8afc 1251X<$+> X<$^N> X<$&> X<$`> X<$'>
14218588 1252
d8b950dc 1253These special variables, like the C<%+> hash and the numbered match variables
57fbbe96 1254(C<$1>, C<$2>, C<$3>, I<etc>.) are dynamically scoped
14218588
GS
1255until the end of the enclosing block or until the next successful
1256match, whichever comes first. (See L<perlsyn/"Compound Statements">.)
d74e8afc
ITB
1257X<$+> X<$^N> X<$&> X<$`> X<$'>
1258X<$1> X<$2> X<$3> X<$4> X<$5> X<$6> X<$7> X<$8> X<$9>
1259
0d017f4d 1260B<NOTE>: Failed matches in Perl do not reset the match variables,
5146ce24 1261which makes it easier to write code that tests for a series of more
665e98b9
JH
1262specific cases and remembers the best match.
1263
13b0f67d
DM
1264B<WARNING>: If your code is to run on Perl 5.16 or earlier,
1265beware that once Perl sees that you need one of C<$&>, C<$`>, or
14218588 1266C<$'> anywhere in the program, it has to provide them for every
13b0f67d
DM
1267pattern match. This may substantially slow your program.
1268
57fbbe96 1269Perl uses the same mechanism to produce C<$1>, C<$2>, I<etc>, so you also
13b0f67d
DM
1270pay a price for each pattern that contains capturing parentheses.
1271(To avoid this cost while retaining the grouping behaviour, use the
14218588
GS
1272extended regular expression C<(?: ... )> instead.) But if you never
1273use C<$&>, C<$`> or C<$'>, then patterns I<without> capturing
1274parentheses will not be penalized. So avoid C<$&>, C<$'>, and C<$`>
1275if you can, but if you can't (and some algorithms really appreciate
1276them), once you've used them once, use them at will, because you've
13b0f67d 1277already paid the price.
d74e8afc 1278X<$&> X<$`> X<$'>
68dc0745 1279
13b0f67d
DM
1280Perl 5.16 introduced a slightly more efficient mechanism that notes
1281separately whether each of C<$`>, C<$&>, and C<$'> have been seen, and
1282thus may only need to copy part of the string. Perl 5.20 introduced a
1283much more efficient copy-on-write mechanism which eliminates any slowdown.
1284
1285As another workaround for this problem, Perl 5.10.0 introduced C<${^PREMATCH}>,
cde0cee5
YO
1286C<${^MATCH}> and C<${^POSTMATCH}>, which are equivalent to C<$`>, C<$&>
1287and C<$'>, B<except> that they are only guaranteed to be defined after a
87e95b7f 1288successful match that was executed with the C</p> (preserve) modifier.
cde0cee5 1289The use of these variables incurs no global performance penalty, unlike
7711f978 1290their punctuation character equivalents, however at the trade-off that you
13b0f67d
DM
1291have to tell perl when you want to use them. As of Perl 5.20, these three
1292variables are equivalent to C<$`>, C<$&> and C<$'>, and C</p> is ignored.
87e95b7f 1293X</p> X<p modifier>
cde0cee5 1294
9d727203
KW
1295=head2 Quoting metacharacters
1296
19799a22
GS
1297Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
1298C<\w>, C<\n>. Unlike some other regular expression languages, there
1299are no backslashed symbols that aren't alphanumeric. So anything
7711f978
KW
1300that looks like C<\\>, C<\(>, C<\)>, C<\[>, C<\]>, C<\{>, or C<\}> is
1301always
19799a22
GS
1302interpreted as a literal character, not a metacharacter. This was
1303once used in a common idiom to disable or quote the special meanings
1304of regular expression metacharacters in a string that you want to
36bbe248 1305use for a pattern. Simply quote all non-"word" characters:
a0d0e21e
LW
1306
1307 $pattern =~ s/(\W)/\\$1/g;
1308
f1cbbd6e 1309(If C<use locale> is set, then this depends on the current locale.)
7711f978
KW
1310Today it is more common to use the C<L<quotemeta()|perlfunc/quotemeta>>
1311function or the C<\Q> metaquoting escape sequence to disable all
1312metacharacters' special meanings like this:
a0d0e21e
LW
1313
1314 /$unquoted\Q$quoted\E$unquoted/
1315
9da458fc
IZ
1316Beware that if you put literal backslashes (those not inside
1317interpolated variables) between C<\Q> and C<\E>, double-quotish
1318backslash interpolation may lead to confusing results. If you
1319I<need> to use literal backslashes within C<\Q...\E>,
1320consult L<perlop/"Gory details of parsing quoted constructs">.
1321
736fe711
KW
1322C<quotemeta()> and C<\Q> are fully described in L<perlfunc/quotemeta>.
1323
19799a22
GS
1324=head2 Extended Patterns
1325
14218588 1326Perl also defines a consistent extension syntax for features not
0b928c2f
FC
1327found in standard tools like B<awk> and
1328B<lex>. The syntax for most of these is a
14218588
GS
1329pair of parentheses with a question mark as the first thing within
1330the parentheses. The character after the question mark indicates
1331the extension.
19799a22 1332
14218588
GS
1333A question mark was chosen for this and for the minimal-matching
1334construct because 1) question marks are rare in older regular
1335expressions, and 2) whenever you see one, you should stop and
0b928c2f 1336"question" exactly what is going on. That's psychology....
a0d0e21e 1337
70ca8714 1338=over 4
a0d0e21e 1339
cc6b7395 1340=item C<(?#text)>
d74e8afc 1341X<(?#)>
a0d0e21e 1342
7c688e65
KW
1343A comment. The text is ignored.
1344Note that Perl closes
7711f978
KW
1345the comment as soon as it sees a C<")">, so there is no way to put a literal
1346C<")"> in the comment. The pattern's closing delimiter must be escaped by
7c688e65
KW
1347a backslash if it appears in the comment.
1348
1349See L</E<sol>x> for another way to have comments in patterns.
a0d0e21e 1350
2ab07670
KW
1351Note that a comment can go just about anywhere, except in the middle of
1352an escape sequence. Examples:
1353
1354 qr/foo(?#comment)bar/' # Matches 'foobar'
1355
1356 # The pattern below matches 'abcd', 'abccd', or 'abcccd'
1357 qr/abc(?#comment between literal and its quantifier){1,3}d/
1358
1359 # The pattern below generates a syntax error, because the '\p' must
1360 # be followed immediately by a '{'.
1361 qr/\p(?#comment between \p and its property name){Any}/
1362
1363 # The pattern below generates a syntax error, because the initial
1364 # '\(' is a literal opening parenthesis, and so there is nothing
1365 # for the closing ')' to match
1366 qr/\(?#the backslash means this isn't a comment)p{Any}/
1367
e4a1c03b
KW
1368 # Comments can be used to fold long patterns into multiple lines
1369 qr/First part of a long regex(?#
1370 )remaining part/
1371
4cb6b395 1372=item C<(?adlupimnsx-imnsx)>
fb85c044 1373
4cb6b395 1374=item C<(?^alupimnsx)>
fb85c044 1375X<(?)> X<(?^)>
19799a22 1376
0b6d1084 1377One or more embedded pattern-match modifiers, to be turned on (or
2ab07670 1378turned off if preceded by C<"-">) for the remainder of the pattern or
fb85c044
KW
1379the remainder of the enclosing pattern group (if any).
1380
a95b7a20
AC
1381This is particularly useful for dynamically-generated patterns,
1382such as those read in from a
0d017f4d 1383configuration file, taken from an argument, or specified in a table
0b928c2f
FC
1384somewhere. Consider the case where some patterns want to be
1385case-sensitive and some do not: The case-insensitive ones merely need to
0d017f4d 1386include C<(?i)> at the front of the pattern. For example:
19799a22
GS
1387
1388 $pattern = "foobar";
5d458dd8 1389 if ( /$pattern/i ) { }
19799a22
GS
1390
1391 # more flexible:
1392
1393 $pattern = "(?i)foobar";
5d458dd8 1394 if ( /$pattern/ ) { }
19799a22 1395
0b6d1084 1396These modifiers are restored at the end of the enclosing group. For example,
19799a22 1397
d8b950dc 1398 ( (?i) blah ) \s+ \g1
19799a22 1399
0d017f4d
WL
1400will match C<blah> in any case, some spaces, and an exact (I<including the case>!)
1401repetition of the previous word, assuming the C</x> modifier, and no C</i>
1402modifier outside this group.
19799a22 1403
8eb5594e 1404These modifiers do not carry over into named subpatterns called in the
dd72e27b 1405enclosing group. In other words, a pattern such as C<((?i)(?&NAME))> does not
7711f978 1406change the case-sensitivity of the C<"NAME"> pattern.
8eb5594e 1407
2ab07670
KW
1408A modifier is overridden by later occurrences of this construct in the
1409same scope containing the same modifier, so that
1410
1411 /((?im)foo(?-m)bar)/
1412
1413matches all of C<foobar> case insensitively, but uses C</m> rules for
57fbbe96
KW
1414only the C<foo> portion. The C<"a"> flag overrides C<aa> as well;
1415likewise C<aa> overrides C<"a">. The same goes for C<"x"> and C<xx>.
77c8f263
KW
1416Hence, in
1417
1418 /(?-x)foo/xx
1419
1420both C</x> and C</xx> are turned off during matching C<foo>. And in
1421
1422 /(?x)foo/x
1423
1424C</x> but NOT C</xx> is turned on for matching C<foo>. (One might
1425mistakenly think that since the inner C<(?x)> is already in the scope of
1426C</x>, that the result would effectively be the sum of them, yielding
1427C</xx>. It doesn't work that way.) Similarly, doing something like
57fbbe96
KW
1428C<(?xx-x)foo> turns off all C<"x"> behavior for matching C<foo>, it is not
1429that you subtract 1 C<"x"> from 2 to get 1 C<"x"> remaining.
2ab07670 1430
dc925305
KW
1431Any of these modifiers can be set to apply globally to all regular
1432expressions compiled within the scope of a C<use re>. See
a0bbd6ff 1433L<re/"'/flags' mode">.
dc925305 1434
9de15fec 1435Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately
4cb6b395 1436after the C<"?"> is a shorthand equivalent to C<d-imnsx>. Flags (except
9de15fec
KW
1437C<"d">) may follow the caret to override it.
1438But a minus sign is not legal with it.
1439
57fbbe96
KW
1440Note that the C<"a">, C<"d">, C<"l">, C<"p">, and C<"u"> modifiers are special in
1441that they can only be enabled, not disabled, and the C<"a">, C<"d">, C<"l">, and
1442C<"u"> modifiers are mutually exclusive: specifying one de-specifies the
1443others, and a maximum of one (or two C<"a">'s) may appear in the
ed7efc79 1444construct. Thus, for
0b928c2f 1445example, C<(?-p)> will warn when compiled under C<use warnings>;
b6fa137b 1446C<(?-d:...)> and C<(?dl:...)> are fatal errors.
9de15fec 1447
57fbbe96 1448Note also that the C<"p"> modifier is special in that its presence
9de15fec 1449anywhere in a pattern has a global effect.
cde0cee5 1450
5a964f20 1451=item C<(?:pattern)>
d74e8afc 1452X<(?:)>
a0d0e21e 1453
4cb6b395 1454=item C<(?adluimnsx-imnsx:pattern)>
ca9dfc88 1455
4cb6b395 1456=item C<(?^aluimnsx:pattern)>
fb85c044
KW
1457X<(?^:)>
1458
5a964f20 1459This is for clustering, not capturing; it groups subexpressions like
7711f978 1460C<"()">, but doesn't make backreferences as C<"()"> does. So
a0d0e21e 1461
5a964f20 1462 @fields = split(/\b(?:a|b|c)\b/)
a0d0e21e 1463
a95b7a20 1464matches the same field delimiters as
a0d0e21e 1465
5a964f20 1466 @fields = split(/\b(a|b|c)\b/)
a0d0e21e 1467
a95b7a20
AC
1468but doesn't spit out the delimiters themselves as extra fields (even though
1469that's the behaviour of L<perlfunc/split> when its pattern contains capturing
1470groups). It's also cheaper not to capture
19799a22 1471characters if you don't need to.
a0d0e21e 1472
7711f978 1473Any letters between C<"?"> and C<":"> act as flags modifiers as with
4cb6b395 1474C<(?adluimnsx-imnsx)>. For example,
ca9dfc88
IZ
1475
1476 /(?s-i:more.*than).*million/i
1477
14218588 1478is equivalent to the more verbose
ca9dfc88
IZ
1479
1480 /(?:(?s-i)more.*than).*million/i
1481
7711f978 1482Note that any C<()> constructs enclosed within this one will still
4cb6b395
KW
1483capture unless the C</n> modifier is in effect.
1484
57fbbe96
KW
1485Like the L</(?adlupimnsx-imnsx)> construct, C<aa> and C<"a"> override each
1486other, as do C<xx> and C<"x">. They are not additive. So, doing
1487something like C<(?xx-x:foo)> turns off all C<"x"> behavior for matching
77c8f263 1488C<foo>.
2ab07670 1489
fb85c044 1490Starting in Perl 5.14, a C<"^"> (caret or circumflex accent) immediately
4cb6b395 1491after the C<"?"> is a shorthand equivalent to C<d-imnsx>. Any positive
9de15fec 1492flags (except C<"d">) may follow the caret, so
fb85c044
KW
1493
1494 (?^x:foo)
1495
1496is equivalent to
1497
4cb6b395 1498 (?x-imns:foo)
fb85c044
KW
1499
1500The caret tells Perl that this cluster doesn't inherit the flags of any
4cb6b395 1501surrounding pattern, but uses the system defaults (C<d-imnsx>),
fb85c044
KW
1502modified by any flags specified.
1503
1504The caret allows for simpler stringification of compiled regular
1505expressions. These look like
1506
1507 (?^:pattern)
1508
1509with any non-default flags appearing between the caret and the colon.
1510A test that looks at such stringification thus doesn't need to have the
1511system default flags hard-coded in it, just the caret. If new flags are
1512added to Perl, the meaning of the caret's expansion will change to include
1513the default for those flags, so the test will still work, unchanged.
1514
1515Specifying a negative flag after the caret is an error, as the flag is
1516redundant.
1517
1518Mnemonic for C<(?^...)>: A fresh beginning since the usual use of a caret is
1519to match at the beginning.
1520
594d7033
YO
1521=item C<(?|pattern)>
1522X<(?|)> X<Branch reset>
1523
1524This is the "branch reset" pattern, which has the special property
c27a5cfe 1525that the capture groups are numbered from the same starting point
99d59c4d 1526in each alternation branch. It is available starting from perl 5.10.0.
4deaaa80 1527
c27a5cfe 1528Capture groups are numbered from left to right, but inside this
693596a8 1529construct the numbering is restarted for each branch.
4deaaa80 1530
c27a5cfe 1531The numbering within each branch will be as normal, and any groups
4deaaa80
PJ
1532following this construct will be numbered as though the construct
1533contained only one branch, that being the one with the most capture
c27a5cfe 1534groups in it.
4deaaa80 1535
0b928c2f 1536This construct is useful when you want to capture one of a
4deaaa80
PJ
1537number of alternative matches.
1538
1539Consider the following pattern. The numbers underneath show in
c27a5cfe 1540which group the captured content will be stored.
594d7033
YO
1541
1542
57fbbe96 1543 # before ---------------branch-reset----------- after
594d7033 1544 / ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
57fbbe96 1545 # 1 2 2 3 2 3 4
594d7033 1546
57fbbe96
KW
1547Be careful when using the branch reset pattern in combination with
1548named captures. Named captures are implemented as being aliases to
c27a5cfe 1549numbered groups holding the captures, and that interferes with the
ab106183
A
1550implementation of the branch reset pattern. If you are using named
1551captures in a branch reset pattern, it's best to use the same names,
1552in the same order, in each of the alternations:
1553
1554 /(?| (?<a> x ) (?<b> y )
1555 | (?<a> z ) (?<b> w )) /x
1556
1557Not doing so may lead to surprises:
1558
1559 "12" =~ /(?| (?<a> \d+ ) | (?<b> \D+))/x;
a95b7a20
AC
1560 say $+{a}; # Prints '12'
1561 say $+{b}; # *Also* prints '12'.
ab106183 1562
c27a5cfe
KW
1563The problem here is that both the group named C<< a >> and the group
1564named C<< b >> are aliases for the group belonging to C<< $1 >>.
90a18110 1565
f67a5002 1566=item Lookaround Assertions
ee9b8eae
YO
1567X<look-around assertion> X<lookaround assertion> X<look-around> X<lookaround>
1568
f67a5002 1569Lookaround assertions are zero-width patterns which match a specific
ee9b8eae
YO
1570pattern without including it in C<$&>. Positive assertions match when
1571their subpattern matches, negative assertions match when their subpattern
f67a5002
EA
1572fails. Lookbehind matches text up to the current match position,
1573lookahead matches text following the current match position.
ee9b8eae
YO
1574
1575=over 4
1576
5a964f20 1577=item C<(?=pattern)>
e7206367
KW
1578
1579=item C<(*pla:pattern)>
1580
1581=item C<(*positive_lookahead:pattern)>
1582X<(?=)>
1583X<(*pla>
1584X<(*positive_lookahead>
1585X<look-ahead, positive> X<lookahead, positive>
a0d0e21e 1586
f67a5002 1587A zero-width positive lookahead assertion. For example, C</\w+(?=\t)/>
a0d0e21e
LW
1588matches a word followed by a tab, without including the tab in C<$&>.
1589
e7206367
KW
1590The alphabetic forms are experimental; using them yields a warning in the
1591C<experimental::alpha_assertions> category.
1592
5a964f20 1593=item C<(?!pattern)>
e7206367
KW
1594
1595=item C<(*nla:pattern)>
1596
1597=item C<(*negative_lookahead:pattern)>
1598X<(?!)>
1599X<(*nla>
1600X<(*negative_lookahead>
1601X<look-ahead, negative> X<lookahead, negative>
a0d0e21e 1602
f67a5002 1603A zero-width negative lookahead assertion. For example C</foo(?!bar)/>
a0d0e21e 1604matches any occurrence of "foo" that isn't followed by "bar". Note
f67a5002
EA
1605however that lookahead and lookbehind are NOT the same thing. You cannot
1606use this for lookbehind.
7b8d334a 1607
5a964f20 1608If you are looking for a "bar" that isn't preceded by a "foo", C</(?!foo)bar/>
7b8d334a
GS
1609will not do what you want. That's because the C<(?!foo)> is just saying that
1610the next thing cannot be "foo"--and it's not, it's a "bar", so "foobar" will
f67a5002 1611match. Use lookbehind instead (see below).
c277df42 1612
e7206367
KW
1613The alphabetic forms are experimental; using them yields a warning in the
1614C<experimental::alpha_assertions> category.
1615
a8f2f5fa
AC
1616=item C<(?<=pattern)>
1617
1618=item C<\K>
e7206367
KW
1619
1620=item C<(*plb:pattern)>
1621
1622=item C<(*positive_lookbehind:pattern)>
1623X<(?<=)>
1624X<(*plb>
1625X<(*positive_lookbehind>
1626X<look-behind, positive> X<lookbehind, positive> X<\K>
c277df42 1627
f67a5002 1628A zero-width positive lookbehind assertion. For example, C</(?<=\t)\w+/>
19799a22 1629matches a word that follows a tab, without including the tab in C<$&>.
bb2c6dbd
KW
1630Works only for fixed-width lookbehind of up to 255 characters. Note
1631that a compilation error will be generated if the assertion contains a
1632multi-character match under C</i>, as that could match a single
1633character, or it could match two or three, and that makes it variable
1634length, which is forbidden.
c277df42 1635
3d9df1a7
KE
1636There is a special form of this construct, called C<\K> (available since
1637Perl 5.10.0), which causes the
ee9b8eae 1638regex engine to "keep" everything it had matched prior to the C<\K> and
0b928c2f 1639not include it in C<$&>. This effectively provides variable-length
f67a5002 1640lookbehind. The use of C<\K> inside of another lookaround assertion
ee9b8eae
YO
1641is allowed, but the behaviour is currently not well defined.
1642
c62285ac 1643For various reasons C<\K> may be significantly more efficient than the
ee9b8eae
YO
1644equivalent C<< (?<=...) >> construct, and it is especially useful in
1645situations where you want to efficiently remove something following
1646something else in a string. For instance
1647
1648 s/(foo)bar/$1/g;
1649
1650can be rewritten as the much more efficient
1651
1652 s/foo\Kbar//g;
1653
e7206367
KW
1654The alphabetic forms (not including C<\K> are experimental; using them
1655yields a warning in the C<experimental::alpha_assertions> category.
1656
5a964f20 1657=item C<(?<!pattern)>
e7206367
KW
1658
1659=item C<(*nlb:pattern)>
1660
1661=item C<(*negative_lookbehind:pattern)>
1662X<(?<!)>
1663X<(*nlb>
1664X<(*negative_lookbehind>
1665X<look-behind, negative> X<lookbehind, negative>
c277df42 1666
f67a5002 1667A zero-width negative lookbehind assertion. For example C</(?<!bar)foo/>
19799a22 1668matches any occurrence of "foo" that does not follow "bar". Works
bb2c6dbd
KW
1669only for fixed-width lookbehind of up to 255 characters. Note that a
1670compilation error will be generated if the assertion contains a
1671multi-character match under C</i>, as that could match a single
1672character, or it could match two or three, and that makes it variable
1673length, which is forbidden.
c277df42 1674
e7206367
KW
1675The alphabetic forms are experimental; using them yields a warning in the
1676C<experimental::alpha_assertions> category.
1677
ee9b8eae
YO
1678=back
1679
81714fb9 1680=item C<< (?<NAME>pattern) >>
a8f2f5fa
AC
1681
1682=item C<(?'NAME'pattern)>
81714fb9
YO
1683X<< (?<NAME>) >> X<(?'NAME')> X<named capture> X<capture>
1684
c27a5cfe 1685A named capture group. Identical in every respect to normal capturing
0b928c2f
FC
1686parentheses C<()> but for the additional fact that the group
1687can be referred to by name in various regular expression
1688constructs (like C<\g{NAME}>) and can be accessed by name
1689after a successful match via C<%+> or C<%->. See L<perlvar>
90a18110 1690for more details on the C<%+> and C<%-> hashes.
81714fb9 1691
33727e0f 1692If multiple distinct capture groups have the same name, then
7711f978 1693C<$+{NAME}> will refer to the leftmost defined group in the match.
81714fb9 1694
0d017f4d 1695The forms C<(?'NAME'pattern)> and C<< (?<NAME>pattern) >> are equivalent.
81714fb9
YO
1696
1697B<NOTE:> While the notation of this construct is the same as the similar
c27a5cfe 1698function in .NET regexes, the behavior is not. In Perl the groups are
81714fb9
YO
1699numbered sequentially regardless of being named or not. Thus in the
1700pattern
1701
1702 /(x)(?<foo>y)(z)/
1703
7711f978 1704C<$+{I<foo>}> will be the same as C<$2>, and C<$3> will contain 'z' instead of
81714fb9
YO
1705the opposite which is what a .NET regex hacker might expect.
1706
7711f978 1707Currently I<NAME> is restricted to simple identifiers only.
1f1031fe
YO
1708In other words, it must match C</^[_A-Za-z][_A-Za-z0-9]*\z/> or
1709its Unicode extension (see L<utf8>),
1710though it isn't extended by the locale (see L<perllocale>).
81714fb9 1711
1f1031fe 1712B<NOTE:> In order to make things easier for programmers with experience
ae5648b3 1713with the Python or PCRE regex engines, the pattern C<< (?PE<lt>NAMEE<gt>pattern) >>
0d017f4d 1714may be used instead of C<< (?<NAME>pattern) >>; however this form does not
64c5a566 1715support the use of single quotes as a delimiter for the name.
81714fb9 1716
1f1031fe
YO
1717=item C<< \k<NAME> >>
1718
1719=item C<< \k'NAME' >>
81714fb9
YO
1720
1721Named backreference. Similar to numeric backreferences, except that
1722the group is designated by name and not number. If multiple groups
1723have the same name then it refers to the leftmost defined group in
1724the current match.
1725
0d017f4d 1726It is an error to refer to a name not defined by a C<< (?<NAME>) >>
81714fb9
YO
1727earlier in the pattern.
1728
1729Both forms are equivalent.
1730
1f1031fe 1731B<NOTE:> In order to make things easier for programmers with experience
0d017f4d 1732with the Python or PCRE regex engines, the pattern C<< (?P=NAME) >>
64c5a566 1733may be used instead of C<< \k<NAME> >>.
1f1031fe 1734
cc6b7395 1735=item C<(?{ code })>
d74e8afc 1736X<(?{})> X<regex, code in> X<regexp, code in> X<regular expression, code in>
c277df42 1737
83f32aba
RS
1738B<WARNING>: Using this feature safely requires that you understand its
1739limitations. Code executed that has side effects may not perform identically
1740from version to version due to the effect of future optimisations in the regex
1741engine. For more information on this, see L</Embedded Code Execution
1742Frequency>.
c277df42 1743
e128ab2c
DM
1744This zero-width assertion executes any embedded Perl code. It always
1745succeeds, and its return value is set as C<$^R>.
19799a22 1746
e128ab2c
DM
1747In literal patterns, the code is parsed at the same time as the
1748surrounding code. While within the pattern, control is passed temporarily
1749back to the perl parser, until the logically-balancing closing brace is
1750encountered. This is similar to the way that an array index expression in
1751a literal string is handled, for example
77ea4f6d 1752
e128ab2c
DM
1753 "abc$array[ 1 + f('[') + g()]def"
1754
1755In particular, braces do not need to be balanced:
1756
576fa024 1757 s/abc(?{ f('{'); })/def/
e128ab2c
DM
1758
1759Even in a pattern that is interpolated and compiled at run-time, literal
1760code blocks will be compiled once, at perl compile time; the following
1761prints "ABCD":
1762
1763 print "D";
1764 my $qr = qr/(?{ BEGIN { print "A" } })/;
1765 my $foo = "foo";
1766 /$foo$qr(?{ BEGIN { print "B" } })/;
1767 BEGIN { print "C" }
1768
1769In patterns where the text of the code is derived from run-time
1770information rather than appearing literally in a source code /pattern/,
1771the code is compiled at the same time that the pattern is compiled, and
5771dda0 1772for reasons of security, C<use re 'eval'> must be in scope. This is to
e128ab2c
DM
1773stop user-supplied patterns containing code snippets from being
1774executable.
1775
5771dda0 1776In situations where you need to enable this with C<use re 'eval'>, you should
e128ab2c
DM
1777also have taint checking enabled. Better yet, use the carefully
1778constrained evaluation within a Safe compartment. See L<perlsec> for
1779details about both these mechanisms.
1780
1781From the viewpoint of parsing, lexical variable scope and closures,
1782
1783 /AAA(?{ BBB })CCC/
1784
1785behaves approximately like
1786
1787 /AAA/ && do { BBB } && /CCC/
1788
1789Similarly,
1790
1791 qr/AAA(?{ BBB })CCC/
1792
1793behaves approximately like
77ea4f6d 1794
e128ab2c
DM
1795 sub { /AAA/ && do { BBB } && /CCC/ }
1796
1797In particular:
1798
1799 { my $i = 1; $r = qr/(?{ print $i })/ }
1800 my $i = 2;
1801 /$r/; # prints "1"
1802
1803Inside a C<(?{...})> block, C<$_> refers to the string the regular
754091cb 1804expression is matching against. You can also use C<pos()> to know what is
fa11829f 1805the current position of matching within this string.
754091cb 1806
e128ab2c
DM
1807The code block introduces a new scope from the perspective of lexical
1808variable declarations, but B<not> from the perspective of C<local> and
1809similar localizing behaviours. So later code blocks within the same
1810pattern will still see the values which were localized in earlier blocks.
1811These accumulated localizations are undone either at the end of a
1812successful match, or if the assertion is backtracked (compare
5a0de581 1813L</"Backtracking">). For example,
b9ac3b5b
GS
1814
1815 $_ = 'a' x 8;
5d458dd8 1816 m<
d1fbf752 1817 (?{ $cnt = 0 }) # Initialize $cnt.
b9ac3b5b 1818 (
5d458dd8 1819 a
b9ac3b5b 1820 (?{
d1fbf752
KW
1821 local $cnt = $cnt + 1; # Update $cnt,
1822 # backtracking-safe.
b9ac3b5b 1823 })
5d458dd8 1824 )*
b9ac3b5b 1825 aaaa
d1fbf752
KW
1826 (?{ $res = $cnt }) # On success copy to
1827 # non-localized location.
b9ac3b5b
GS
1828 >x;
1829
e128ab2c
DM
1830will initially increment C<$cnt> up to 8; then during backtracking, its
1831value will be unwound back to 4, which is the value assigned to C<$res>.
7711f978 1832At the end of the regex execution, C<$cnt> will be wound back to its initial
e128ab2c
DM
1833value of 0.
1834
1835This assertion may be used as the condition in a
b9ac3b5b 1836
e128ab2c
DM
1837 (?(condition)yes-pattern|no-pattern)
1838
1839switch. If I<not> used in this way, the result of evaluation of C<code>
1840is put into the special variable C<$^R>. This happens immediately, so
1841C<$^R> can be used from other C<(?{ code })> assertions inside the same
1842regular expression.
b9ac3b5b 1843
19799a22
GS
1844The assignment to C<$^R> above is properly localized, so the old
1845value of C<$^R> is restored if the assertion is backtracked; compare
5a0de581 1846L</"Backtracking">.
b9ac3b5b 1847
e128ab2c
DM
1848Note that the special variable C<$^N> is particularly useful with code
1849blocks to capture the results of submatches in variables without having to
1850keep track of the number of nested parentheses. For example:
1851
1852 $_ = "The brown fox jumps over the lazy dog";
1853 /the (\S+)(?{ $color = $^N }) (\S+)(?{ $animal = $^N })/i;
1854 print "color = $color, animal = $animal\n";
1855
8988a1bb 1856
14455d6c 1857=item C<(??{ code })>
d74e8afc
ITB
1858X<(??{})>
1859X<regex, postponed> X<regexp, postponed> X<regular expression, postponed>
0f5d15d6 1860
83f32aba
RS
1861B<WARNING>: Using this feature safely requires that you understand its
1862limitations. Code executed that has side effects may not perform
1863identically from version to version due to the effect of future
1864optimisations in the regex engine. For more information on this, see
1865L</Embedded Code Execution Frequency>.
0f5d15d6 1866
e128ab2c
DM
1867This is a "postponed" regular subexpression. It behaves in I<exactly> the
1868same way as a C<(?{ code })> code block as described above, except that
1869its return value, rather than being assigned to C<$^R>, is treated as a
1870pattern, compiled if it's a string (or used as-is if its a qr// object),
1871then matched as if it were inserted instead of this construct.
6bda09f9 1872
e128ab2c
DM
1873During the matching of this sub-pattern, it has its own set of
1874captures which are valid during the sub-match, but are discarded once
1875control returns to the main pattern. For example, the following matches,
1876with the inner pattern capturing "B" and matching "BB", while the outer
1877pattern captures "A";
1878
1879 my $inner = '(.)\1';
1880 "ABBA" =~ /^(.)(??{ $inner })\1/;
1881 print $1; # prints "A";
6bda09f9 1882
e128ab2c
DM
1883Note that this means that there is no way for the inner pattern to refer
1884to a capture group defined outside. (The code block itself can use C<$1>,
57fbbe96 1885I<etc>., to refer to the enclosing pattern's capture groups.) Thus, although
0f5d15d6 1886
e128ab2c
DM
1887 ('a' x 100)=~/(??{'(.)' x 100})/
1888
7711f978 1889I<will> match, it will I<not> set C<$1> on exit.
19799a22
GS
1890
1891The following pattern matches a parenthesized group:
0f5d15d6 1892
d1fbf752
KW
1893 $re = qr{
1894 \(
1895 (?:
1896 (?> [^()]+ ) # Non-parens without backtracking
1897 |
1898 (??{ $re }) # Group with matching parens
1899 )*
1900 \)
1901 }x;
0f5d15d6 1902
93f313ef
KW
1903See also
1904L<C<(?I<PARNO>)>|/(?PARNO) (?-PARNO) (?+PARNO) (?R) (?0)>
1905for a different, more efficient way to accomplish
6bda09f9
YO
1906the same task.
1907
7e7dae31
KW
1908Executing a postponed regular expression too many times without
1909consuming any input string will also result in a fatal error. The depth
1910at which that happens is compiled into perl, so it can be changed with a
1911custom build.
6bda09f9 1912
93f313ef 1913=item C<(?I<PARNO>)> C<(?-I<PARNO>)> C<(?+I<PARNO>)> C<(?R)> C<(?0)>
542fa716 1914X<(?PARNO)> X<(?1)> X<(?R)> X<(?0)> X<(?-1)> X<(?+1)> X<(?-PARNO)> X<(?+PARNO)>
6bda09f9 1915X<regex, recursive> X<regexp, recursive> X<regular expression, recursive>
d1b2014a
YO
1916X<regex, relative recursion> X<GOSUB> X<GOSTART>
1917
1918Recursive subpattern. Treat the contents of a given capture buffer in the
1919current pattern as an independent subpattern and attempt to match it at
1920the current position in the string. Information about capture state from
1921the caller for things like backreferences is available to the subpattern,
1922but capture buffers set by the subpattern are not visible to the caller.
6bda09f9 1923
e128ab2c
DM
1924Similar to C<(??{ code })> except that it does not involve executing any
1925code or potentially compiling a returned pattern string; instead it treats
1926the part of the current pattern contained within a specified capture group
d1b2014a
YO
1927as an independent pattern that must match at the current position. Also
1928different is the treatment of capture buffers, unlike C<(??{ code })>
dd407255 1929recursive patterns have access to their caller's match state, so one can
d1b2014a 1930use backreferences safely.
6bda09f9 1931
93f313ef 1932I<PARNO> is a sequence of digits (not starting with 0) whose value reflects
c27a5cfe 1933the paren-number of the capture group to recurse to. C<(?R)> recurses to
894be9b7 1934the beginning of the whole pattern. C<(?0)> is an alternate syntax for
93f313ef 1935C<(?R)>. If I<PARNO> is preceded by a plus or minus sign then it is assumed
c27a5cfe 1936to be relative, with negative numbers indicating preceding capture groups
542fa716 1937and positive ones following. Thus C<(?-1)> refers to the most recently
c27a5cfe 1938declared group, and C<(?+1)> indicates the next group to be declared.
c74340f9 1939Note that the counting for relative recursion differs from that of
c27a5cfe 1940relative backreferences, in that with recursion unclosed groups B<are>
c74340f9 1941included.
6bda09f9 1942
7711f978 1943The following pattern matches a function C<foo()> which may contain
f145b7e9 1944balanced parentheses as the argument.
6bda09f9 1945
d1fbf752 1946 $re = qr{ ( # paren group 1 (full function)
81714fb9 1947 foo
d1fbf752 1948 ( # paren group 2 (parens)
6bda09f9 1949 \(
d1fbf752 1950 ( # paren group 3 (contents of parens)
6bda09f9 1951 (?:
d1fbf752 1952 (?> [^()]+ ) # Non-parens without backtracking
6bda09f9 1953 |
d1fbf752 1954 (?2) # Recurse to start of paren group 2
6bda09f9
YO
1955 )*
1956 )
1957 \)
1958 )
1959 )
1960 }x;
1961
1962If the pattern was used as follows
1963
1964 'foo(bar(baz)+baz(bop))'=~/$re/
1965 and print "\$1 = $1\n",
1966 "\$2 = $2\n",
1967 "\$3 = $3\n";
1968
1969the output produced should be the following:
1970
1971 $1 = foo(bar(baz)+baz(bop))
1972 $2 = (bar(baz)+baz(bop))
81714fb9 1973 $3 = bar(baz)+baz(bop)
6bda09f9 1974
c27a5cfe 1975If there is no corresponding capture group defined, then it is a
7e7dae31
KW
1976fatal error. Recursing deeply without consuming any input string will
1977also result in a fatal error. The depth at which that happens is
1978compiled into perl, so it can be changed with a custom build.
6bda09f9 1979
542fa716
YO
1980The following shows how using negative indexing can make it
1981easier to embed recursive patterns inside of a C<qr//> construct
1982for later use:
1983
1984 my $parens = qr/(\((?:[^()]++|(?-1))*+\))/;
c77257ed 1985 if (/foo $parens \s+ \+ \s+ bar $parens/x) {
542fa716
YO
1986 # do something here...
1987 }
1988
81714fb9 1989B<Note> that this pattern does not behave the same way as the equivalent
0d017f4d 1990PCRE or Python construct of the same form. In Perl you can backtrack into
6bda09f9 1991a recursed group, in PCRE and Python the recursed into group is treated
542fa716 1992as atomic. Also, modifiers are resolved at compile time, so constructs
7711f978 1993like C<(?i:(?1))> or C<(?:(?i)(?1))> do not affect how the sub-pattern will
542fa716 1994be processed.
6bda09f9 1995
894be9b7
YO
1996=item C<(?&NAME)>
1997X<(?&NAME)>
1998
93f313ef 1999Recurse to a named subpattern. Identical to C<(?I<PARNO>)> except that the
0d017f4d 2000parenthesis to recurse to is determined by name. If multiple parentheses have
894be9b7
YO
2001the same name, then it recurses to the leftmost.
2002
2003It is an error to refer to a name that is not declared somewhere in the
2004pattern.
2005
1f1031fe
YO
2006B<NOTE:> In order to make things easier for programmers with experience
2007with the Python or PCRE regex engines the pattern C<< (?P>NAME) >>
64c5a566 2008may be used instead of C<< (?&NAME) >>.
1f1031fe 2009
e2e6a0f1
YO
2010=item C<(?(condition)yes-pattern|no-pattern)>
2011X<(?()>
286f584a 2012
e2e6a0f1 2013=item C<(?(condition)yes-pattern)>
286f584a 2014
41ef34de
ML
2015Conditional expression. Matches C<yes-pattern> if C<condition> yields
2016a true value, matches C<no-pattern> otherwise. A missing pattern always
2017matches.
2018
7711f978
KW
2019C<(condition)> should be one of:
2020
2021=over 4
2022
2023=item an integer in parentheses
2024
2025(which is valid if the corresponding pair of parentheses
2026matched);
2027
f67a5002 2028=item a lookahead/lookbehind/evaluate zero-width assertion;
7711f978
KW
2029
2030=item a name in angle brackets or single quotes
2031
2032(which is valid if a group with the given name matched);
2033
2034=item the special symbol C<(R)>
2035
2036(true when evaluated inside of recursion or eval). Additionally the
57fbbe96 2037C<"R"> may be
e2e6a0f1
YO
2038followed by a number, (which will be true when evaluated when recursing
2039inside of the appropriate group), or by C<&NAME>, in which case it will
2040be true only when evaluated during recursion in the named group.
2041
7711f978
KW
2042=back
2043
e2e6a0f1
YO
2044Here's a summary of the possible predicates:
2045
2046=over 4
2047
7711f978 2048=item C<(1)> C<(2)> ...
e2e6a0f1 2049
c27a5cfe 2050Checks if the numbered capturing group has matched something.
9240ab7d 2051Full syntax: C<< (?(1)then|else) >>
e2e6a0f1 2052
7711f978 2053=item C<(E<lt>I<NAME>E<gt>)> C<('I<NAME>')>
e2e6a0f1 2054
c27a5cfe 2055Checks if a group with the given name has matched something.
9240ab7d 2056Full syntax: C<< (?(<name>)then|else) >>
e2e6a0f1 2057
7711f978 2058=item C<(?=...)> C<(?!...)> C<(?<=...)> C<(?<!...)>
f01cd190 2059
7711f978 2060Checks whether the pattern matches (or does not match, for the C<"!">
f01cd190 2061variants).
fdec910a 2062Full syntax: C<< (?(?=I<lookahead>)I<then>|I<else>) >>
f01cd190 2063
7711f978 2064=item C<(?{ I<CODE> })>
e2e6a0f1 2065
f01cd190 2066Treats the return value of the code block as the condition.
9240ab7d 2067Full syntax: C<< (?(?{ code })then|else) >>
e2e6a0f1 2068
7711f978 2069=item C<(R)>
e2e6a0f1
YO
2070
2071Checks if the expression has been evaluated inside of recursion.
9240ab7d 2072Full syntax: C<< (?(R)then|else) >>
e2e6a0f1 2073
7711f978 2074=item C<(R1)> C<(R2)> ...
e2e6a0f1
YO
2075
2076Checks if the expression has been evaluated while executing directly
2077inside of the n-th capture group. This check is the regex equivalent of
2078
2079 if ((caller(0))[3] eq 'subname') { ... }
2080
2081In other words, it does not check the full recursion stack.
2082
9240ab7d
AC
2083Full syntax: C<< (?(R1)then|else) >>
2084
7711f978 2085=item C<(R&I<NAME>)>
e2e6a0f1
YO
2086
2087Similar to C<(R1)>, this predicate checks to see if we're executing
2088directly inside of the leftmost group with a given name (this is the same
7711f978 2089logic used by C<(?&I<NAME>)> to disambiguate). It does not check the full
e2e6a0f1 2090stack, but only the name of the innermost active recursion.
9240ab7d 2091Full syntax: C<< (?(R&name)then|else) >>
e2e6a0f1 2092
7711f978 2093=item C<(DEFINE)>
e2e6a0f1
YO
2094
2095In this case, the yes-pattern is never directly executed, and no
2096no-pattern is allowed. Similar in spirit to C<(?{0})> but more efficient.
2097See below for details.
9240ab7d 2098Full syntax: C<< (?(DEFINE)definitions...) >>
e2e6a0f1
YO
2099
2100=back
2101
2102For example:
2103
2104 m{ ( \( )?
2105 [^()]+
2106 (?(1) \) )
2107 }x
2108
2109matches a chunk of non-parentheses, possibly included in parentheses
2110themselves.
2111
0b928c2f
FC
2112A special form is the C<(DEFINE)> predicate, which never executes its
2113yes-pattern directly, and does not allow a no-pattern. This allows one to
2114define subpatterns which will be executed only by the recursion mechanism.
e2e6a0f1
YO
2115This way, you can define a set of regular expression rules that can be
2116bundled into any pattern you choose.
2117
2118It is recommended that for this usage you put the DEFINE block at the
2119end of the pattern, and that you name any subpatterns defined within it.
2120
2121Also, it's worth noting that patterns defined this way probably will
31dc26d6 2122not be as efficient, as the optimizer is not very clever about
e2e6a0f1
YO
2123handling them.
2124
2125An example of how this might be used is as follows:
2126
2bf803e2 2127 /(?<NAME>(?&NAME_PAT))(?<ADDR>(?&ADDRESS_PAT))
e2e6a0f1 2128 (?(DEFINE)
2bf803e2 2129 (?<NAME_PAT>....)
22dc6719 2130 (?<ADDRESS_PAT>....)
e2e6a0f1
YO
2131 )/x
2132
c27a5cfe
KW
2133Note that capture groups matched inside of recursion are not accessible
2134after the recursion returns, so the extra layer of capturing groups is
e2e6a0f1
YO
2135necessary. Thus C<$+{NAME_PAT}> would not be defined even though
2136C<$+{NAME}> would be.
286f584a 2137
51a1303c
BF
2138Finally, keep in mind that subpatterns created inside a DEFINE block
2139count towards the absolute and relative number of captures, so this:
2140
2141 my @captures = "a" =~ /(.) # First capture
2142 (?(DEFINE)
2143 (?<EXAMPLE> 1 ) # Second capture
2144 )/x;
2145 say scalar @captures;
2146
2147Will output 2, not 1. This is particularly important if you intend to
2148compile the definitions with the C<qr//> operator, and later
2149interpolate them in another pattern.
2150
c47ff5f1 2151=item C<< (?>pattern) >>
e7206367
KW
2152
2153=item C<< (*atomic:pattern) >>
2154X<(?E<gt>pattern)>
2155X<(*atomic>
6bda09f9 2156X<backtrack> X<backtracking> X<atomic> X<possessive>
5a964f20 2157
19799a22
GS
2158An "independent" subexpression, one which matches the substring
2159that a I<standalone> C<pattern> would match if anchored at the given
9da458fc 2160position, and it matches I<nothing other than this substring>. This
19799a22 2161construct is useful for optimizations of what would otherwise be
5a0de581 2162"eternal" matches, because it will not backtrack (see L</"Backtracking">).
9da458fc
IZ
2163It may also be useful in places where the "grab all you can, and do not
2164give anything back" semantic is desirable.
19799a22 2165
c47ff5f1 2166For example: C<< ^(?>a*)ab >> will never match, since C<< (?>a*) >>
19799a22 2167(anchored at the beginning of string, as above) will match I<all>
57fbbe96 2168characters C<"a"> at the beginning of string, leaving no C<"a"> for
19799a22
GS
2169C<ab> to match. In contrast, C<a*ab> will match the same as C<a+b>,
2170since the match of the subgroup C<a*> is influenced by the following
5a0de581 2171group C<ab> (see L</"Backtracking">). In particular, C<a*> inside
19799a22
GS
2172C<a*ab> will match fewer characters than a standalone C<a*>, since
2173this makes the tail match.
2174
0b928c2f
FC
2175C<< (?>pattern) >> does not disable backtracking altogether once it has
2176matched. It is still possible to backtrack past the construct, but not
2177into it. So C<< ((?>a*)|(?>b*))ar >> will still match "bar".
2178
c47ff5f1 2179An effect similar to C<< (?>pattern) >> may be achieved by writing
0b928c2f
FC
2180C<(?=(pattern))\g{-1}>. This matches the same substring as a standalone
2181C<a+>, and the following C<\g{-1}> eats the matched string; it therefore
c47ff5f1 2182makes a zero-length assertion into an analogue of C<< (?>...) >>.
19799a22
GS
2183(The difference between these two constructs is that the second one
2184uses a capturing group, thus shifting ordinals of backreferences
2185in the rest of a regular expression.)
2186
2187Consider this pattern:
c277df42 2188
871b0233 2189 m{ \(
e2e6a0f1 2190 (
f793d64a 2191 [^()]+ # x+
e2e6a0f1 2192 |
871b0233
IZ
2193 \( [^()]* \)
2194 )+
e2e6a0f1 2195 \)
871b0233 2196 }x
5a964f20 2197
19799a22
GS
2198That will efficiently match a nonempty group with matching parentheses
2199two levels deep or less. However, if there is no such group, it
2200will take virtually forever on a long string. That's because there
2201are so many different ways to split a long string into several
2202substrings. This is what C<(.+)+> is doing, and C<(.+)+> is similar
2203to a subpattern of the above pattern. Consider how the pattern
2204above detects no-match on C<((()aaaaaaaaaaaaaaaaaa> in several
2205seconds, but that each extra letter doubles this time. This
2206exponential performance will make it appear that your program has
14218588 2207hung. However, a tiny change to this pattern
5a964f20 2208
e2e6a0f1
YO
2209 m{ \(
2210 (
f793d64a 2211 (?> [^()]+ ) # change x+ above to (?> x+ )
e2e6a0f1 2212 |
871b0233
IZ
2213 \( [^()]* \)
2214 )+
e2e6a0f1 2215 \)
871b0233 2216 }x
c277df42 2217
c47ff5f1 2218which uses C<< (?>...) >> matches exactly when the one above does (verifying
5a964f20 2219this yourself would be a productive exercise), but finishes in a fourth
57fbbe96 2220the time when used on a similar string with 1000000 C<"a">s. Be aware,
0b928c2f
FC
2221however, that, when this construct is followed by a
2222quantifier, it currently triggers a warning message under
9f1b1f2d 2223the C<use warnings> pragma or B<-w> switch saying it
6bab786b 2224C<"matches null string many times in regex">.
c277df42 2225
c47ff5f1 2226On simple groups, such as the pattern C<< (?> [^()]+ ) >>, a comparable
f67a5002 2227effect may be achieved by negative lookahead, as in C<[^()]+ (?! [^()] )>.
57fbbe96 2228This was only 4 times slower on a string with 1000000 C<"a">s.
c277df42 2229
9da458fc
IZ
2230The "grab all you can, and do not give anything back" semantic is desirable
2231in many situations where on the first sight a simple C<()*> looks like
2232the correct solution. Suppose we parse text with comments being delimited
7711f978 2233by C<"#"> followed by some optional (horizontal) whitespace. Contrary to
4375e838 2234its appearance, C<#[ \t]*> I<is not> the correct subexpression to match
9da458fc
IZ
2235the comment delimiter, because it may "give up" some whitespace if
2236the remainder of the pattern can be made to match that way. The correct
2237answer is either one of these:
2238
2239 (?>#[ \t]*)
2240 #[ \t]*(?![ \t])
2241
7711f978 2242For example, to grab non-empty comments into C<$1>, one should use either
9da458fc
IZ
2243one of these:
2244
2245 / (?> \# [ \t]* ) ( .+ ) /x;
2246 / \# [ \t]* ( [^ \t] .* ) /x;
2247
2248Which one you pick depends on which of these expressions better reflects
2249the above specification of comments.
2250
6bda09f9
YO
2251In some literature this construct is called "atomic matching" or
2252"possessive matching".
2253
b9b4dddf
YO
2254Possessive quantifiers are equivalent to putting the item they are applied
2255to inside of one of these constructs. The following equivalences apply:
2256
2257 Quantifier Form Bracketing Form
2258 --------------- ---------------
2259 PAT*+ (?>PAT*)
2260 PAT++ (?>PAT+)
2261 PAT?+ (?>PAT?)
2262 PAT{min,max}+ (?>PAT{min,max})
2263
30457add
KW
2264Nested C<(?E<gt>...)> constructs are not no-ops, even if at first glance
2265they might seem to be. This is because the nested C<(?E<gt>...)> can
2266restrict internal backtracking that otherwise might occur. For example,
2267
2268 "abc" =~ /(?>a[bc]*c)/
2269
2270matches, but
2271
2272 "abc" =~ /(?>a(?>[bc]*)c)/
2273
2274does not.
2275
e7206367
KW
2276The alphabetic form (C<(*atomic:...)>) is experimental; using it
2277yields a warning in the C<experimental::alpha_assertions> category.
2278
9d1a5160 2279=item C<(?[ ])>
f4f5fe57 2280
572224ce 2281See L<perlrecharclass/Extended Bracketed Character Classes>.
9d1a5160 2282
ff8bb468
AC
2283Note that this feature is currently L<experimental|perlpolicy/experimental>;
2284using it yields a warning in the C<experimental::regex_sets> category.
2285
e2e6a0f1
YO
2286=back
2287
1e0a6411
RGS
2288=head2 Backtracking
2289X<backtrack> X<backtracking>
2290
2291NOTE: This section presents an abstract approximation of regular
2292expression behavior. For a more rigorous (and complicated) view of
2293the rules involved in selecting a match among possible alternatives,
2294see L</Combining RE Pieces>.
2295
2296A fundamental feature of regular expression matching involves the
2297notion called I<backtracking>, which is currently used (when needed)
57fbbe96 2298by all regular non-possessive expression quantifiers, namely C<"*">, C<*?>, C<"+">,
a95b7a20 2299C<+?>, C<{n,m}>, and C<{n,m}?>. Backtracking is often optimized
1e0a6411
RGS
2300internally, but the general principle outlined here is valid.
2301
2302For a regular expression to match, the I<entire> regular expression must
2303match, not just part of it. So if the beginning of a pattern containing a
2304quantifier succeeds in a way that causes later parts in the pattern to
2305fail, the matching engine backs up and recalculates the beginning
2306part--that's why it's called backtracking.
2307
2308Here is an example of backtracking: Let's say you want to find the
2309word following "foo" in the string "Food is on the foo table.":
2310
2311 $_ = "Food is on the foo table.";
2312 if ( /\b(foo)\s+(\w+)/i ) {
2313 print "$2 follows $1.\n";
2314 }
2315
2316When the match runs, the first part of the regular expression (C<\b(foo)>)
2317finds a possible match right at the beginning of the string, and loads up
2318C<$1> with "Foo". However, as soon as the matching engine sees that there's
2319no whitespace following the "Foo" that it had saved in C<$1>, it realizes its
2320mistake and starts over again one character after where it had the
2321tentative match. This time it goes all the way until the next occurrence
2322of "foo". The complete regular expression matches this time, and you get
2323the expected output of "table follows foo."
2324
2325Sometimes minimal matching can help a lot. Imagine you'd like to match
2326everything between "foo" and "bar". Initially, you write something
2327like this:
2328
2329 $_ = "The food is under the bar in the barn.";
2330 if ( /foo(.*)bar/ ) {
2331 print "got <$1>\n";
2332 }
2333
2334Which perhaps unexpectedly yields:
2335
2336 got <d is under the bar in the >
2337
2338That's because C<.*> was greedy, so you get everything between the
2339I<first> "foo" and the I<last> "bar". Here it's more effective
2340to use minimal matching to make sure you get the text between a "foo"
2341and the first "bar" thereafter.
2342
2343 if ( /foo(.*?)bar/ ) { print "got <$1>\n" }
2344 got <d is under the >
2345
2346Here's another example. Let's say you'd like to match a number at the end
2347of a string, and you also want to keep the preceding part of the match.
2348So you write this:
2349
2350 $_ = "I have 2 numbers: 53147";
2351 if ( /(.*)(\d*)/ ) { # Wrong!
2352 print "Beginning is <$1>, number is <$2>.\n";
2353 }
2354
2355That won't work at all, because C<.*> was greedy and gobbled up the
2356whole string. As C<\d*> can match on an empty string the complete
2357regular expression matched successfully.
2358
2359 Beginning is <I have 2 numbers: 53147>, number is <>.
2360
2361Here are some variants, most of which don't work:
2362
2363 $_ = "I have 2 numbers: 53147";
2364 @pats = qw{
2365 (.*)(\d*)
2366 (.*)(\d+)
2367 (.*?)(\d*)
2368 (.*?)(\d+)
2369 (.*)(\d+)$
2370 (.*?)(\d+)$
2371 (.*)\b(\d+)$
2372 (.*\D)(\d+)$
2373 };
2374
2375 for $pat (@pats) {
2376 printf "%-12s ", $pat;
2377 if ( /$pat/ ) {
2378 print "<$1> <$2>\n";
2379 } else {
2380 print "FAIL\n";
2381 }
2382 }
2383
2384That will print out:
2385
2386 (.*)(\d*) <I have 2 numbers: 53147> <>
2387 (.*)(\d+) <I have 2 numbers: 5314> <7>
2388 (.*?)(\d*) <> <>
2389 (.*?)(\d+) <I have > <2>
2390 (.*)(\d+)$ <I have 2 numbers: 5314> <7>
2391 (.*?)(\d+)$ <I have 2 numbers: > <53147>
2392 (.*)\b(\d+)$ <I have 2 numbers: > <53147>
2393 (.*\D)(\d+)$ <I have 2 numbers: > <53147>
2394
2395As you see, this can be a bit tricky. It's important to realize that a
2396regular expression is merely a set of assertions that gives a definition
2397of success. There may be 0, 1, or several different ways that the
2398definition might succeed against a particular string. And if there are
2399multiple ways it might succeed, you need to understand backtracking to
2400know which variety of success you will achieve.
2401
2402When using lookahead assertions and negations, this can all get even
2403trickier. Imagine you'd like to find a sequence of non-digits not
2404followed by "123". You might try to write that as
2405
2406 $_ = "ABC123";
2407 if ( /^\D*(?!123)/ ) { # Wrong!
2408 print "Yup, no 123 in $_\n";
2409 }
2410
2411But that isn't going to match; at least, not the way you're hoping. It
2412claims that there is no 123 in the string. Here's a clearer picture of
2413why that pattern matches, contrary to popular expectations:
2414
2415 $x = 'ABC123';
2416 $y = 'ABC445';
2417
2418 print "1: got $1\n" if $x =~ /^(ABC)(?!123)/;
2419 print "2: got $1\n" if $y =~ /^(ABC)(?!123)/;
2420
2421 print "3: got $1\n" if $x =~ /^(\D*)(?!123)/;
2422 print "4: got $1\n" if $y =~ /^(\D*)(?!123)/;
2423
2424This prints
2425
2426 2: got ABC
2427 3: got AB
2428 4: got ABC
2429
2430You might have expected test 3 to fail because it seems to a more
2431general purpose version of test 1. The important difference between
2432them is that test 3 contains a quantifier (C<\D*>) and so can use
2433backtracking, whereas test 1 will not. What's happening is
2434that you've asked "Is it true that at the start of C<$x>, following 0 or more
2435non-digits, you have something that's not 123?" If the pattern matcher had
2436let C<\D*> expand to "ABC", this would have caused the whole pattern to
2437fail.
2438
2439The search engine will initially match C<\D*> with "ABC". Then it will
2440try to match C<(?!123)> with "123", which fails. But because
2441a quantifier (C<\D*>) has been used in the regular expression, the
2442search engine can backtrack and retry the match differently
2443in the hope of matching the complete regular expression.
2444
2445The pattern really, I<really> wants to succeed, so it uses the
2446standard pattern back-off-and-retry and lets C<\D*> expand to just "AB" this
2447time. Now there's indeed something following "AB" that is not
2448"123". It's "C123", which suffices.
2449
2450We can deal with this by using both an assertion and a negation.
2451We'll say that the first part in C<$1> must be followed both by a digit
2452and by something that's not "123". Remember that the lookaheads
2453are zero-width expressions--they only look, but don't consume any
2454of the string in their match. So rewriting this way produces what
2455you'd expect; that is, case 5 will fail, but case 6 succeeds:
2456
2457 print "5: got $1\n" if $x =~ /^(\D*)(?=\d)(?!123)/;
2458 print "6: got $1\n" if $y =~ /^(\D*)(?=\d)(?!123)/;
2459
2460 6: got ABC
2461
2462In other words, the two zero-width assertions next to each other work as though
2463they're ANDed together, just as you'd use any built-in assertions: C</^$/>
2464matches only if you're at the beginning of the line AND the end of the
2465line simultaneously. The deeper underlying truth is that juxtaposition in
2466regular expressions always means AND, except when you write an explicit OR
2467using the vertical bar. C</ab/> means match "a" AND (then) match "b",
2468although the attempted matches are made at different positions because "a"
2469is not a zero-width assertion, but a one-width assertion.
2470
2471B<WARNING>: Particularly complicated regular expressions can take
2472exponential time to solve because of the immense number of possible
2473ways they can use backtracking to try for a match. For example, without
2474internal optimizations done by the regular expression engine, this will
2475take a painfully long time to run:
2476
2477 'aaaaaaaaaaaa' =~ /((a{0,5}){0,5})*[c]/
2478
2479And if you used C<"*">'s in the internal groups instead of limiting them
2480to 0 through 5 matches, then it would take forever--or until you ran
2481out of stack space. Moreover, these internal optimizations are not
2482always applicable. For example, if you put C<{0,5}> instead of C<"*">
2483on the external group, no current optimization is applicable, and the
2484match takes a long time to finish.
2485
2486A powerful tool for optimizing such beasts is what is known as an
2487"independent group",
2488which does not backtrack (see L</C<< (?>pattern) >>>). Note also that
2489zero-length lookahead/lookbehind assertions will not backtrack to make
2490the tail match, since they are in "logical" context: only
2491whether they match is considered relevant. For an example
2492where side-effects of lookahead I<might> have influenced the
2493following match, see L</C<< (?>pattern) >>>.
2494
034602eb 2495=head2 Script Runs
d9790612 2496X<(*script_run:...)> X<(sr:...)>
3337229c 2497X<(*atomic_script_run:...)> X<(asr:...)>
034602eb
KW
2498
2499A script run is basically a sequence of characters, all from the same
2500Unicode script (see L<perlunicode/Scripts>), such as Latin or Greek. In
2501most places a single word would never be written in multiple scripts,
2502unless it is a spoofing attack. An infamous example, is
2503
2504 paypal.com
2505
2506Those letters could all be Latin (as in the example just above), or they
2507could be all Cyrillic (except for the dot), or they could be a mixture
2508of the two. In the case of an internet address the C<.com> would be in
2509Latin, And any Cyrillic ones would cause it to be a mixture, not a
2510script run. Someone clicking on such a link would not be directed to
2511the real Paypal website, but an attacker would craft a look-alike one to
2512attempt to gather sensitive information from the person.
2513
2514Starting in Perl 5.28, it is now easy to detect strings that aren't
d9790612
KW
2515script runs. Simply enclose just about any pattern like either of
2516these:
034602eb 2517
d9790612
KW
2518 (*script_run:pattern)
2519 (*sr:pattern)
034602eb
KW
2520
2521What happens is that after I<pattern> succeeds in matching, it is
2522subjected to the additional criterion that every character in it must be
2523from the same script (see exceptions below). If this isn't true,
2524backtracking occurs until something all in the same script is found that
2525matches, or all possibilities are exhausted. This can cause a lot of
2526backtracking, but generally, only malicious input will result in this,
2527though the slow down could cause a denial of service attack. If your
4a1d9640
KW
2528needs permit, it is best to make the pattern atomic to cut down on the
2529amount of backtracking. This is so likely to be what you want, that
2530instead of writing this:
034602eb 2531
d9790612 2532 (*script_run:(?>pattern))
034602eb 2533
3337229c
KW
2534you can write either of these:
2535
2536 (*atomic_script_run:pattern)
2537 (*asr:pattern)
2538
034602eb
KW
2539(See L</C<(?E<gt>pattern)>>.)
2540
2541In Taiwan, Japan, and Korea, it is common for text to have a mixture of
2542characters from their native scripts and base Chinese. Perl follows
2543Unicode's UTS 39 (L<http://unicode.org/reports/tr39/>) Unicode Security
4a1d9640
KW
2544Mechanisms in allowing such mixtures. For example, the Japanese scripts
2545Katakana and Hiragana are commonly mixed together in practice, along
2546with some Chinese characters, and hence are treated as being in a single
2547script run by Perl.
034602eb
KW
2548
2549The rules used for matching decimal digits are somewhat different. Many
2550scripts have their own sets of digits equivalent to the Western C<0>
2551through C<9> ones. A few, such as Arabic, have more than one set. For
2552a string to be considered a script run, all digits in it must come from
2553the same set, as determined by the first digit encountered. The ASCII
2554C<[0-9]> are accepted as being in any script, even those that have their
2555own set. This is because these are often used in commerce even in such
2556scripts. But any mixing of the ASCII and other digits will cause the
2557sequence to not be a script run, failing the match. As an example,
2558
d9790612 2559 qr/(*script_run: \d+ \b )/x
034602eb
KW
2560
2561guarantees that the digits matched will all be from the same set of 10.
2562You won't get a look-alike digit from a different script that has a
2563different value than what it appears to be.
2564
2565Unicode has three pseudo scripts that are handled specially.
2566
2567"Unknown" is applied to code points whose meaning has yet to be
2568determined. Perl currently will match as a script run, any single
2569character string consisting of one of these code points. But any string
2570longer than one code point containing one of these will not be
2571considered a script run.
2572
2573"Inherited" is applied to characters that modify another, such as an
2574accent of some type. These are considered to be in the script of the
2575master character, and so never cause a script run to not match.
2576
2577The other one is "Common". This consists of mostly punctuation, emoji,
2578and characters used in mathematics and music, and the ASCII digits C<0>
2579through C<9>. These characters can appear intermixed in text in many of
2580the world's scripts. These also don't cause a script run to not match,
2581except any ASCII digits encountered have to obey the decimal digit rules
2582described above.
2583
2584This construct is non-capturing. You can add parentheses to I<pattern>
2585to capture, if desired. You will have to do this if you plan to use
2586L</(*ACCEPT) (*ACCEPT:arg)> and not have it bypass the script run
2587checking.
2588
2589This feature is experimental, and the exact syntax and details of
2590operation are subject to change; using it yields a warning in the
2591C<experimental::script_run> category.
2592
4a1d9640
KW
2593The C<Script_Extensions> property as modified by UTS 39
2594(L<http://unicode.org/reports/tr39/>) is used as the basis for this
2595feature.
2596
2597To summarize,
2598
2599=over 4
2600
2601=item *
2602
2603All length 0 or length 1 sequences are script runs.
2604
2605=item *
2606
2607A longer sequence is a script run if and only if B<all> of the following
2608conditions are met:
2609
2610Z<>
2611
2612=over
2613
2614=item 1
2615
2616No code point in the sequence has the C<Script_Extension> property of
2617C<Unknown>.
2618
3f4fa0ec 2619This currently means that all code points in the sequence have been
4a1d9640
KW
2620assigned by Unicode to be characters that aren't private use nor
2621surrogate code points.
2622
2623=item 2
2624
2625All characters in the sequence come from the Common script and/or the
2626Inherited script and/or a single other script.
2627
2628The script of a character is determined by the C<Script_Extensions>
2629property as modified by UTS 39 (L<http://unicode.org/reports/tr39/>), as
2630described above.
2631
2632=item 3
2633
2634All decimal digits in the sequence come from the same block of 10
2635consecutive digits.
2636
2637=back
2638
2639=back
034602eb 2640
e2e6a0f1
YO
2641=head2 Special Backtracking Control Verbs
2642
7711f978
KW
2643These special patterns are generally of the form C<(*I<VERB>:I<ARG>)>. Unless
2644otherwise stated the I<ARG> argument is optional; in some cases, it is
fee50582 2645mandatory.
e2e6a0f1
YO
2646
2647Any pattern containing a special backtracking verb that allows an argument
e1020413 2648has the special behaviour that when executed it sets the current package's
5d458dd8
YO
2649C<$REGERROR> and C<$REGMARK> variables. When doing so the following
2650rules apply:
e2e6a0f1 2651
7711f978 2652On failure, the C<$REGERROR> variable will be set to the I<ARG> value of the
5d458dd8 2653verb pattern, if the verb was involved in the failure of the match. If the
7711f978 2654I<ARG> part of the pattern was omitted, then C<$REGERROR> will be set to the
5d458dd8
YO
2655name of the last C<(*MARK:NAME)> pattern executed, or to TRUE if there was
2656none. Also, the C<$REGMARK> variable will be set to FALSE.
e2e6a0f1 2657
5d458dd8
YO
2658On a successful match, the C<$REGERROR> variable will be set to FALSE, and
2659the C<$REGMARK> variable will be set to the name of the last
2660C<(*MARK:NAME)> pattern executed. See the explanation for the
2661C<(*MARK:NAME)> verb below for more details.
e2e6a0f1 2662
5d458dd8 2663B<NOTE:> C<$REGERROR> and C<$REGMARK> are not magic variables like C<$1>
0b928c2f 2664and most other regex-related variables. They are not local to a scope, nor
5d458dd8 2665readonly, but instead are volatile package variables similar to C<$AUTOLOAD>.
ddb07903
AC
2666They are set in the package containing the code that I<executed> the regex
2667(rather than the one that compiled it, where those differ). If necessary, you
2668can use C<local> to localize changes to these variables to a specific scope
2669before executing a regex.
e2e6a0f1
YO
2670
2671If a pattern does not contain a special backtracking verb that allows an
5d458dd8 2672argument, then C<$REGERROR> and C<$REGMARK> are not touched at all.
e2e6a0f1 2673
70ca8714 2674=over 3
e2e6a0f1 2675
fee50582 2676=item Verbs
e2e6a0f1
YO
2677
2678=over 4
2679
5d458dd8 2680=item C<(*PRUNE)> C<(*PRUNE:NAME)>
f7819f85 2681X<(*PRUNE)> X<(*PRUNE:NAME)>
54612592 2682
5d458dd8 2683This zero-width pattern prunes the backtracking tree at the current point
a95b7a20 2684when backtracked into on failure. Consider the pattern C</I<A> (*PRUNE) I<B>/>,
7711f978
KW
2685where I<A> and I<B> are complex patterns. Until the C<(*PRUNE)> verb is reached,
2686I<A> may backtrack as necessary to match. Once it is reached, matching
2687continues in I<B>, which may also backtrack as necessary; however, should B
5d458dd8
YO
2688not match, then no further backtracking will take place, and the pattern
2689will fail outright at the current starting position.
54612592
YO
2690
2691The following example counts all the possible matching strings in a
2692pattern (without actually matching any of them).
2693
e2e6a0f1 2694 'aaab' =~ /a+b?(?{print "$&\n"; $count++})(*FAIL)/;
54612592
YO
2695 print "Count=$count\n";
2696
2697which produces:
2698
2699 aaab
2700 aaa
2701 aa
2702 a
2703 aab
2704 aa
2705 a
2706 ab
2707 a
2708 Count=9
2709
5d458dd8 2710If we add a C<(*PRUNE)> before the count like the following
54612592 2711
5d458dd8 2712 'aaab' =~ /a+b?(*PRUNE)(?{print "$&\n"; $count++})(*FAIL)/;
54612592
YO
2713 print "Count=$count\n";
2714
0b928c2f 2715we prevent backtracking and find the count of the longest matching string
353c6505 2716at each matching starting point like so:
54612592
YO
2717
2718 aaab
2719 aab
2720 ab
2721 Count=3
2722
5d458dd8 2723Any number of C<(*PRUNE)> assertions may be used in a pattern.
54612592 2724
4b05bc8e
KW
2725See also C<<< L<< /(?>pattern) >> >>> and possessive quantifiers for
2726other ways to
5d458dd8
YO
2727control backtracking. In some cases, the use of C<(*PRUNE)> can be
2728replaced with a C<< (?>pattern) >> with no functional difference; however,
2729C<(*PRUNE)> can be used to handle cases that cannot be expressed using a
2730C<< (?>pattern) >> alone.
54612592 2731
5d458dd8
YO
2732=item C<(*SKIP)> C<(*SKIP:NAME)>
2733X<(*SKIP)>
e2e6a0f1 2734
5d458dd8 2735This zero-width pattern is similar to C<(*PRUNE)>, except that on
e2e6a0f1 2736failure it also signifies that whatever text that was matched leading up
5d458dd8
YO
2737to the C<(*SKIP)> pattern being executed cannot be part of I<any> match
2738of this pattern. This effectively means that the regex engine "skips" forward
2739to this position on failure and tries to match again, (assuming that
2740there is sufficient room to match).
2741
2742The name of the C<(*SKIP:NAME)> pattern has special significance. If a
2743C<(*MARK:NAME)> was encountered while matching, then it is that position
2744which is used as the "skip point". If no C<(*MARK)> of that name was
2745encountered, then the C<(*SKIP)> operator has no effect. When used
2746without a name the "skip point" is where the match point was when
7711f978 2747executing the C<(*SKIP)> pattern.
5d458dd8 2748
0b928c2f 2749Compare the following to the examples in C<(*PRUNE)>; note the string
24b23f37
YO
2750is twice as long:
2751
d1fbf752
KW
2752 'aaabaaab' =~ /a+b?(*SKIP)(?{print "$&\n"; $count++})(*FAIL)/;
2753 print "Count=$count\n";
24b23f37
YO
2754
2755outputs
2756
2757 aaab
2758 aaab
2759 Count=2
2760
5d458dd8 2761Once the 'aaab' at the start of the string has matched, and the C<(*SKIP)>
353c6505 2762executed, the next starting point will be where the cursor was when the
5d458dd8
YO
2763C<(*SKIP)> was executed.
2764
5d458dd8 2765=item C<(*MARK:NAME)> C<(*:NAME)>
b16db30f 2766X<(*MARK)> X<(*MARK:NAME)> X<(*:NAME)>
5d458dd8
YO
2767
2768This zero-width pattern can be used to mark the point reached in a string
2769when a certain part of the pattern has been successfully matched. This
2770mark may be given a name. A later C<(*SKIP)> pattern will then skip
2771forward to that point if backtracked into on failure. Any number of
7711f978 2772C<(*MARK)> patterns are allowed, and the I<NAME> portion may be duplicated.
5d458dd8
YO
2773
2774In addition to interacting with the C<(*SKIP)> pattern, C<(*MARK:NAME)>
2775can be used to "label" a pattern branch, so that after matching, the
2776program can determine which branches of the pattern were involved in the
2777match.
2778
2779When a match is successful, the C<$REGMARK> variable will be set to the
2780name of the most recently executed C<(*MARK:NAME)> that was involved
2781in the match.
2782
2783This can be used to determine which branch of a pattern was matched
c27a5cfe 2784without using a separate capture group for each branch, which in turn
5d458dd8
YO
2785can result in a performance improvement, as perl cannot optimize
2786C</(?:(x)|(y)|(z))/> as efficiently as something like
2787C</(?:x(*MARK:x)|y(*MARK:y)|z(*MARK:z))/>.
2788
2789When a match has failed, and unless another verb has been involved in
2790failing the match and has provided its own name to use, the C<$REGERROR>
2791variable will be set to the name of the most recently executed
2792C<(*MARK:NAME)>.
2793
42ac7c82 2794See L</(*SKIP)> for more details.
5d458dd8 2795
b62d2d15
YO
2796As a shortcut C<(*MARK:NAME)> can be written C<(*:NAME)>.
2797
5d458dd8
YO
2798=item C<(*THEN)> C<(*THEN:NAME)>
2799
ac9d8485 2800This is similar to the "cut group" operator C<::> from Perl 6. Like
5d458dd8
YO
2801C<(*PRUNE)>, this verb always matches, and when backtracked into on
2802failure, it causes the regex engine to try the next alternation in the
ac9d8485
FC
2803innermost enclosing group (capturing or otherwise) that has alternations.
2804The two branches of a C<(?(condition)yes-pattern|no-pattern)> do not
2805count as an alternation, as far as C<(*THEN)> is concerned.
5d458dd8
YO
2806
2807Its name comes from the observation that this operation combined with the
7711f978 2808alternation operator (C<"|">) can be used to create what is essentially a
5d458dd8
YO
2809pattern-based if/then/else block:
2810
2811 ( COND (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ )
2812
2813Note that if this operator is used and NOT inside of an alternation then
2814it acts exactly like the C<(*PRUNE)> operator.
2815
2816 / A (*PRUNE) B /
2817
2818is the same as
2819
2820 / A (*THEN) B /
2821
2822but
2823
25e26d77 2824 / ( A (*THEN) B | C ) /
5d458dd8
YO
2825
2826is not the same as
2827
25e26d77 2828 / ( A (*PRUNE) B | C ) /
5d458dd8 2829
7711f978
KW
2830as after matching the I<A> but failing on the I<B> the C<(*THEN)> verb will
2831backtrack and try I<C>; but the C<(*PRUNE)> verb will simply fail.
24b23f37 2832
fee50582 2833=item C<(*COMMIT)> C<(*COMMIT:args)>
e2e6a0f1 2834X<(*COMMIT)>
24b23f37 2835
241e7389 2836This is the Perl 6 "commit pattern" C<< <commit> >> or C<:::>. It's a
5d458dd8
YO
2837zero-width pattern similar to C<(*SKIP)>, except that when backtracked
2838into on failure it causes the match to fail outright. No further attempts
2839to find a valid match by advancing the start pointer will occur again.
2840For example,
24b23f37 2841
d1fbf752
KW
2842 'aaabaaab' =~ /a+b?(*COMMIT)(?{print "$&\n"; $count++})(*FAIL)/;
2843 print "Count=$count\n";
24b23f37
YO
2844
2845outputs
2846
2847 aaab
2848 Count=1
2849
e2e6a0f1
YO
2850In other words, once the C<(*COMMIT)> has been entered, and if the pattern
2851does not match, the regex engine will not try any further matching on the
2852rest of the string.
c277df42 2853
fee50582 2854=item C<(*FAIL)> C<(*F)> C<(*FAIL:arg)>
e2e6a0f1 2855X<(*FAIL)> X<(*F)>
9af228c6 2856
e2e6a0f1
YO
2857This pattern matches nothing and always fails. It can be used to force the
2858engine to backtrack. It is equivalent to C<(?!)>, but easier to read. In
fee50582 2859fact, C<(?!)> gets optimised into C<(*FAIL)> internally. You can provide
7711f978
KW
2860an argument so that if the match fails because of this C<FAIL> directive
2861the argument can be obtained from C<$REGERROR>.
9af228c6 2862
e2e6a0f1 2863It is probably useful only when combined with C<(?{})> or C<(??{})>.
9af228c6 2864
fee50582 2865=item C<(*ACCEPT)> C<(*ACCEPT:arg)>
e2e6a0f1 2866X<(*ACCEPT)>
9af228c6 2867
e2e6a0f1
YO
2868This pattern matches nothing and causes the end of successful matching at
2869the point at which the C<(*ACCEPT)> pattern was encountered, regardless of
2870whether there is actually more to match in the string. When inside of a
0d017f4d 2871nested pattern, such as recursion, or in a subpattern dynamically generated
e2e6a0f1 2872via C<(??{})>, only the innermost pattern is ended immediately.
9af228c6 2873
c27a5cfe 2874If the C<(*ACCEPT)> is inside of capturing groups then the groups are
e2e6a0f1
YO
2875marked as ended at the point at which the C<(*ACCEPT)> was encountered.
2876For instance:
9af228c6 2877
e2e6a0f1 2878 'AB' =~ /(A (A|B(*ACCEPT)|C) D)(E)/x;
9af228c6 2879
57fbbe96 2880will match, and C<$1> will be C<AB> and C<$2> will be C<"B">, C<$3> will not
0b928c2f 2881be set. If another branch in the inner parentheses was matched, such as in the
57fbbe96 2882string 'ACDE', then the C<"D"> and C<"E"> would have to be matched as well.
9af228c6 2883
7711f978
KW
2884You can provide an argument, which will be available in the var
2885C<$REGMARK> after the match completes.
fee50582 2886
9af228c6 2887=back
c277df42 2888
a0d0e21e
LW
2889=back
2890
7711f978 2891=head2 Warning on C<\1> Instead of C<$1>
cb1a09d0 2892
5a964f20 2893Some people get too used to writing things like:
cb1a09d0
AD
2894
2895 $pattern =~ s/(\W)/\\\1/g;
2896
3ff1c45a
KW
2897This is grandfathered (for \1 to \9) for the RHS of a substitute to avoid
2898shocking the
cb1a09d0 2899B<sed> addicts, but it's a dirty habit to get into. That's because in
d1be9408 2900PerlThink, the righthand side of an C<s///> is a double-quoted string. C<\1> in
cb1a09d0
AD
2901the usual double-quoted string means a control-A. The customary Unix
2902meaning of C<\1> is kludged in for C<s///>. However, if you get into the habit
2903of doing that, you get yourself into trouble if you then add an C</e>
2904modifier.
2905
f793d64a 2906 s/(\d+)/ \1 + 1 /eg; # causes warning under -w
cb1a09d0
AD
2907
2908Or if you try to do
2909
2910 s/(\d+)/\1000/;
2911
2912You can't disambiguate that by saying C<\{1}000>, whereas you can fix it with
14218588 2913C<${1}000>. The operation of interpolation should not be confused
cb1a09d0
AD
2914with the operation of matching a backreference. Certainly they mean two
2915different things on the I<left> side of the C<s///>.
9fa51da4 2916
0d017f4d 2917=head2 Repeated Patterns Matching a Zero-length Substring
c84d73f1 2918
19799a22 2919B<WARNING>: Difficult material (and prose) ahead. This section needs a rewrite.
c84d73f1
IZ
2920
2921Regular expressions provide a terse and powerful programming language. As
2922with most other power tools, power comes together with the ability
2923to wreak havoc.
2924
2925A common abuse of this power stems from the ability to make infinite
628afcb5 2926loops using regular expressions, with something as innocuous as:
c84d73f1
IZ
2927
2928 'foo' =~ m{ ( o? )* }x;
2929
57fbbe96 2930The C<o?> matches at the beginning of "C<foo>", and since the position
c84d73f1 2931in the string is not moved by the match, C<o?> would match again and again
7711f978 2932because of the C<"*"> quantifier. Another common way to create a similar cycle
f1dc5bb2 2933is with the looping modifier C</g>:
c84d73f1
IZ
2934
2935 @matches = ( 'foo' =~ m{ o? }xg );
2936
2937or
2938
2939 print "match: <$&>\n" while 'foo' =~ m{ o? }xg;
2940
7711f978 2941or the loop implied by C<split()>.
c84d73f1
IZ
2942
2943However, long experience has shown that many programming tasks may
14218588
GS
2944be significantly simplified by using repeated subexpressions that
2945may match zero-length substrings. Here's a simple example being:
c84d73f1 2946
d1fbf752 2947 @chars = split //, $string; # // is not magic in split
c84d73f1
IZ
2948 ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /
2949
9da458fc 2950Thus Perl allows such constructs, by I<forcefully breaking
c84d73f1 2951the infinite loop>. The rules for this are different for lower-level
527e91da 2952loops given by the greedy quantifiers C<*+{}>, and for higher-level
7711f978 2953ones like the C</g> modifier or C<split()> operator.
c84d73f1 2954
19799a22
GS
2955The lower-level loops are I<interrupted> (that is, the loop is
2956broken) when Perl detects that a repeated expression matched a
2957zero-length substring. Thus
c84d73f1
IZ
2958
2959 m{ (?: NON_ZERO_LENGTH | ZERO_LENGTH )* }x;
2960
5d458dd8 2961is made equivalent to
c84d73f1 2962
0b928c2f
FC
2963 m{ (?: NON_ZERO_LENGTH )* (?: ZERO_LENGTH )? }x;
2964
2965For example, this program
2966
2967 #!perl -l
2968 "aaaaab" =~ /
2969 (?:
2970 a # non-zero
2971 | # or
2972 (?{print "hello"}) # print hello whenever this
2973 # branch is tried
2974 (?=(b)) # zero-width assertion
2975 )* # any number of times
2976 /x;
2977 print $&;
2978 print $1;
c84d73f1 2979
0b928c2f
FC
2980prints
2981
2982 hello
2983 aaaaa
2984 b
2985
2986Notice that "hello" is only printed once, as when Perl sees that the sixth
2987iteration of the outermost C<(?:)*> matches a zero-length string, it stops
7711f978 2988the C<"*">.
0b928c2f
FC
2989
2990The higher-level loops preserve an additional state between iterations:
5d458dd8 2991whether the last match was zero-length. To break the loop, the following
c84d73f1 2992match after a zero-length match is prohibited to have a length of zero.
5a0de581 2993This prohibition interacts with backtracking (see L</"Backtracking">),
c84d73f1
IZ
2994and so the I<second best> match is chosen if the I<best> match is of
2995zero length.
2996
19799a22 2997For example:
c84d73f1
IZ
2998
2999 $_ = 'bar';
3000 s/\w??/<$&>/g;
3001
20fb949f 3002results in C<< <><b><><a><><r><> >>. At each position of the string the best
5d458dd8 3003match given by non-greedy C<??> is the zero-length match, and the I<second
c84d73f1
IZ
3004best> match is what is matched by C<\w>. Thus zero-length matches
3005alternate with one-character-long matches.
3006
5d458dd8 3007Similarly, for repeated C<m/()/g> the second-best match is the match at the
c84d73f1
IZ
3008position one notch further in the string.
3009
19799a22 3010The additional state of being I<matched with zero-length> is associated with
7711f978 3011the matched string, and is reset by each assignment to C<pos()>.
9da458fc
IZ
3012Zero-length matches at the end of the previous match are ignored
3013during C<split>.
c84d73f1 3014
0d017f4d 3015=head2 Combining RE Pieces
35a734be
IZ
3016
3017Each of the elementary pieces of regular expressions which were described
3018before (such as C<ab> or C<\Z>) could match at most one substring
3019at the given position of the input string. However, in a typical regular
3020expression these elementary pieces are combined into more complicated
57fbbe96
KW
3021patterns using combining operators C<ST>, C<S|T>, C<S*> I<etc>.
3022(in these examples C<"S"> and C<"T"> are regular subexpressions).
35a734be
IZ
3023
3024Such combinations can include alternatives, leading to a problem of choice:
3025if we match a regular expression C<a|ab> against C<"abc">, will it match
3026substring C<"a"> or C<"ab">? One way to describe which substring is
5a0de581 3027actually matched is the concept of backtracking (see L</"Backtracking">).
35a734be
IZ
3028However, this description is too low-level and makes you think
3029in terms of a particular implementation.
3030
3031Another description starts with notions of "better"/"worse". All the
3032substrings which may be matched by the given regular expression can be
3033sorted from the "best" match to the "worst" match, and it is the "best"
3034match which is chosen. This substitutes the question of "what is chosen?"
3035by the question of "which matches are better, and which are worse?".
3036
3037Again, for elementary pieces there is no such question, since at most
3038one match at a given position is possible. This section describes the
3039notion of better/worse for combining operators. In the description
57fbbe96 3040below C<"S"> and C<"T"> are regular subexpressions.
35a734be 3041
13a2d996 3042=over 4
35a734be
IZ
3043
3044=item C<ST>
3045
57fbbe96
KW
3046Consider two possible matches, C<AB> and C<A'B'>, C<"A"> and C<A'> are
3047substrings which can be matched by C<"S">, C<"B"> and C<B'> are substrings
3048which can be matched by C<"T">.
35a734be 3049
57fbbe96 3050If C<"A"> is a better match for C<"S"> than C<A'>, C<AB> is a better
35a734be
IZ
3051match than C<A'B'>.
3052
57fbbe96
KW
3053If C<"A"> and C<A'> coincide: C<AB> is a better match than C<AB'> if
3054C<"B"> is a better match for C<"T"> than C<B'>.
35a734be
IZ
3055
3056=item C<S|T>
3057
57fbbe96 3058When C<"S"> can match, it is a better match than when only C<"T"> can match.
35a734be 3059
57fbbe96
KW
3060Ordering of two matches for C<"S"> is the same as for C<"S">. Similar for
3061two matches for C<"T">.
35a734be
IZ
3062
3063=item C<S{REPEAT_COUNT}>
3064
3065Matches as C<SSS...S> (repeated as many times as necessary).
3066
3067=item C<S{min,max}>
3068
3069Matches as C<S{max}|S{max-1}|...|S{min+1}|S{min}>.
3070
3071=item C<S{min,max}?>
3072
3073Matches as C<S{min}|S{min+1}|...|S{max-1}|S{max}>.
3074
3075=item C<S?>, C<S*>, C<S+>
3076
3077Same as C<S{0,1}>, C<S{0,BIG_NUMBER}>, C<S{1,BIG_NUMBER}> respectively.
3078
3079=item C<S??>, C<S*?>, C<S+?>
3080
3081Same as C<S{0,1}?>, C<S{0,BIG_NUMBER}?>, C<S{1,BIG_NUMBER}?> respectively.
3082
c47ff5f1 3083=item C<< (?>S) >>
35a734be 3084
57fbbe96 3085Matches the best match for C<"S"> and only that.
35a734be
IZ
3086
3087=item C<(?=S)>, C<(?<=S)>
3088
57fbbe96
KW
3089Only the best match for C<"S"> is considered. (This is important only if
3090C<"S"> has capturing parentheses, and backreferences are used somewhere
35a734be
IZ
3091else in the whole regular expression.)
3092
3093=item C<(?!S)>, C<(?<!S)>
3094
3095For this grouping operator there is no need to describe the ordering, since
57fbbe96 3096only whether or not C<"S"> can match is important.
35a734be 3097
93f313ef 3098=item C<(??{ EXPR })>, C<(?I<PARNO>)>
35a734be
IZ
3099
3100The ordering is the same as for the regular expression which is
93f313ef 3101the result of EXPR, or the pattern contained by capture group I<PARNO>.
35a734be
IZ
3102
3103=item C<(?(condition)yes-pattern|no-pattern)>
3104
3105Recall that which of C<yes-pattern> or C<no-pattern> actually matches is
3106already determined. The ordering of the matches is the same as for the
3107chosen subexpression.
3108
3109=back
3110
3111The above recipes describe the ordering of matches I<at a given position>.
3112One more rule is needed to understand how a match is determined for the
3113whole regular expression: a match at an earlier position is always better
3114than a match at a later position.
3115
0d017f4d 3116=head2 Creating Custom RE Engines
c84d73f1 3117
0b928c2f
FC
3118As of Perl 5.10.0, one can create custom regular expression engines. This
3119is not for the faint of heart, as they have to plug in at the C level. See
3120L<perlreapi> for more details.
3121
3122As an alternative, overloaded constants (see L<overload>) provide a simple
3123way to extend the functionality of the RE engine, by substituting one
3124pattern for another.
c84d73f1
IZ
3125
3126Suppose that we want to enable a new RE escape-sequence C<\Y|> which
0d017f4d 3127matches at a boundary between whitespace characters and non-whitespace
c84d73f1
IZ
3128characters. Note that C<(?=\S)(?<!\S)|(?!\S)(?<=\S)> matches exactly
3129at these positions, so we want to have each C<\Y|> in the place of the
3130more complicated version. We can create a module C<customre> to do
3131this:
3132
3133 package customre;
3134 use overload;
3135
3136 sub import {
3137 shift;
3138 die "No argument to customre::import allowed" if @_;
3139 overload::constant 'qr' => \&convert;
3140 }
3141
3142 sub invalid { die "/$_[0]/: invalid escape '\\$_[1]'"}
3143
580a9fe1
RGS
3144 # We must also take care of not escaping the legitimate \\Y|
3145 # sequence, hence the presence of '\\' in the conversion rules.
5d458dd8 3146 my %rules = ( '\\' => '\\\\',
f793d64a 3147 'Y|' => qr/(?=\S)(?<!\S)|(?!\S)(?<=\S)/ );
c84d73f1
IZ
3148 sub convert {
3149 my $re = shift;
5d458dd8 3150 $re =~ s{
c84d73f1
IZ
3151 \\ ( \\ | Y . )
3152 }
5d458dd8 3153 { $rules{$1} or invalid($re,$1) }sgex;
c84d73f1
IZ
3154 return $re;
3155 }
3156
3157Now C<use customre> enables the new escape in constant regular
57fbbe96 3158expressions, I<i.e.>, those without any runtime variable interpolations.
c84d73f1
IZ
3159As documented in L<overload>, this conversion will work only over
3160literal parts of regular expressions. For C<\Y|$re\Y|> the variable
3161part of this regular expression needs to be converted explicitly
7711f978 3162(but only if the special meaning of C<\Y|> should be enabled inside C<$re>):
c84d73f1
IZ
3163
3164 use customre;
3165 $re = <>;
3166 chomp $re;
3167 $re = customre::convert $re;
3168 /\Y|$re\Y|/;
3169
83f32aba
RS
3170=head2 Embedded Code Execution Frequency
3171
57fbbe96 3172The exact rules for how often C<(??{})> and C<(?{})> are executed in a pattern
83f32aba
RS
3173are unspecified. In the case of a successful match you can assume that
3174they DWIM and will be executed in left to right order the appropriate
3175number of times in the accepting path of the pattern as would any other
3176meta-pattern. How non-accepting pathways and match failures affect the
3177number of times a pattern is executed is specifically unspecified and
3178may vary depending on what optimizations can be applied to the pattern
3179and is likely to change from version to version.
3180
3181For instance in
3182
3183 "aaabcdeeeee"=~/a(?{print "a"})b(?{print "b"})cde/;
3184
3185the exact number of times "a" or "b" are printed out is unspecified for
3186failure, but you may assume they will be printed at least once during
3187a successful match, additionally you may assume that if "b" is printed,
3188it will be preceded by at least one "a".
3189
3190In the case of branching constructs like the following:
3191
3192 /a(b|(?{ print "a" }))c(?{ print "c" })/;
3193
3194you can assume that the input "ac" will output "ac", and that "abc"
3195will output only "c".
3196
3197When embedded code is quantified, successful matches will call the
3198code once for each matched iteration of the quantifier. For
3199example:
3200
3201 "good" =~ /g(?:o(?{print "o"}))*d/;
3202
3203will output "o" twice.
3204
0b928c2f 3205=head2 PCRE/Python Support
1f1031fe 3206
0b928c2f 3207As of Perl 5.10.0, Perl supports several Python/PCRE-specific extensions
1f1031fe 3208to the regex syntax. While Perl programmers are encouraged to use the
0b928c2f 3209Perl-specific syntax, the following are also accepted:
1f1031fe
YO
3210
3211=over 4
3212
ae5648b3 3213=item C<< (?PE<lt>NAMEE<gt>pattern) >>
1f1031fe 3214
c27a5cfe 3215Define a named capture group. Equivalent to C<< (?<NAME>pattern) >>.
1f1031fe
YO
3216
3217=item C<< (?P=NAME) >>
3218
c27a5cfe 3219Backreference to a named capture group. Equivalent to C<< \g{NAME} >>.
1f1031fe
YO
3220
3221=item C<< (?P>NAME) >>
3222
c27a5cfe 3223Subroutine call to a named capture group. Equivalent to C<< (?&NAME) >>.
1f1031fe 3224
ee9b8eae 3225=back
1f1031fe 3226
19799a22
GS
3227=head1 BUGS
3228
ed7efc79 3229There are a number of issues with regard to case-insensitive matching
57fbbe96 3230in Unicode rules. See C<"i"> under L</Modifiers> above.
ed7efc79 3231
9da458fc
IZ
3232This document varies from difficult to understand to completely
3233and utterly opaque. The wandering prose riddled with jargon is
3234hard to fathom in several places.
3235
3236This document needs a rewrite that separates the tutorial content
3237from the reference content.
19799a22
GS
3238
3239=head1 SEE ALSO
9fa51da4 3240
c57a3350
KW
3241The syntax of patterns used in Perl pattern matching evolved from those
3242supplied in the Bell Labs Research Unix 8th Edition (Version 8) regex
3243routines. (The code is actually derived (distantly) from Henry
3244Spencer's freely redistributable reimplementation of those V8 routines.)
3245
91e0c79e
MJD
3246L<perlrequick>.
3247
3248L<perlretut>.
3249
9b599b2a
GS
3250L<perlop/"Regexp Quote-Like Operators">.
3251
1e66bd83
PP
3252L<perlop/"Gory details of parsing quoted constructs">.
3253
14218588
GS
3254L<perlfaq6>.
3255
9b599b2a
GS
3256L<perlfunc/pos>.
3257
3258L<perllocale>.
3259
fb55449c
JH
3260L<perlebcdic>.
3261
14218588
GS
3262I<Mastering Regular Expressions> by Jeffrey Friedl, published
3263by O'Reilly and Associates.