Integrate perlio:
[p5sagit/p5-mst-13.2.git] / pod / perlre.pod
CommitLineData
a0d0e21e 1=head1 NAME
2
3perlre - Perl regular expressions
4
5=head1 DESCRIPTION
6
91e0c79e 7This page describes the syntax of regular expressions in Perl.
8
9if you haven't used regular expressions before, a quick-start
10introduction is available in L<perlrequick>, and a longer tutorial
11introduction is available in L<perlretut>.
12
13For reference on how regular expressions are used in matching
14operations, plus various examples of the same, see discussions of
15C<m//>, C<s///>, C<qr//> and C<??> in L<perlop/"Regexp Quote-Like
16Operators">.
cb1a09d0 17
19799a22 18Matching operations can have various modifiers. Modifiers
5a964f20 19that relate to the interpretation of the regular expression inside
19799a22 20are listed below. Modifiers that alter the way a regular expression
21is used by Perl are detailed in L<perlop/"Regexp Quote-Like Operators"> and
1e66bd83 22L<perlop/"Gory details of parsing quoted constructs">.
a0d0e21e 23
55497cff 24=over 4
25
26=item i
27
28Do case-insensitive pattern matching.
29
a034a98d 30If C<use locale> is in effect, the case map is taken from the current
31locale. See L<perllocale>.
32
54310121 33=item m
55497cff 34
35Treat string as multiple lines. That is, change "^" and "$" from matching
14218588 36the start or end of the string to matching the start or end of any
7f761169 37line anywhere within the string.
55497cff 38
54310121 39=item s
55497cff 40
41Treat string as single line. That is, change "." to match any character
19799a22 42whatsoever, even a newline, which normally it would not match.
55497cff 43
19799a22 44The C</s> and C</m> modifiers both override the C<$*> setting. That
45is, no matter what C<$*> contains, C</s> without C</m> will force
46"^" to match only at the beginning of the string and "$" to match
47only at the end (or just before a newline at the end) of the string.
48Together, as /ms, they let the "." match any character whatsoever,
fb55449c 49while still allowing "^" and "$" to match, respectively, just after
19799a22 50and just before newlines within the string.
7b8d334a 51
54310121 52=item x
55497cff 53
54Extend your pattern's legibility by permitting whitespace and comments.
55
56=back
a0d0e21e 57
58These are usually written as "the C</x> modifier", even though the delimiter
14218588 59in question might not really be a slash. Any of these
a0d0e21e 60modifiers may also be embedded within the regular expression itself using
14218588 61the C<(?...)> construct. See below.
a0d0e21e 62
4633a7c4 63The C</x> modifier itself needs a little more explanation. It tells
55497cff 64the regular expression parser to ignore whitespace that is neither
65backslashed nor within a character class. You can use this to break up
4633a7c4 66your regular expression into (slightly) more readable parts. The C<#>
54310121 67character is also treated as a metacharacter introducing a comment,
55497cff 68just as in ordinary Perl code. This also means that if you want real
14218588 69whitespace or C<#> characters in the pattern (outside a character
5a964f20 70class, where they are unaffected by C</x>), that you'll either have to
55497cff 71escape them or encode them using octal or hex escapes. Taken together,
72these features go a long way towards making Perl's regular expressions
0c815be9 73more readable. Note that you have to be careful not to include the
74pattern delimiter in the comment--perl has no way of knowing you did
5a964f20 75not intend to close the pattern early. See the C-comment deletion code
0c815be9 76in L<perlop>.
a0d0e21e 77
78=head2 Regular Expressions
79
19799a22 80The patterns used in Perl pattern matching derive from supplied in
14218588 81the Version 8 regex routines. (The routines are derived
19799a22 82(distantly) from Henry Spencer's freely redistributable reimplementation
83of the V8 routines.) See L<Version 8 Regular Expressions> for
84details.
a0d0e21e 85
86In particular the following metacharacters have their standard I<egrep>-ish
87meanings:
88
54310121 89 \ Quote the next metacharacter
a0d0e21e 90 ^ Match the beginning of the line
91 . Match any character (except newline)
c07a80fd 92 $ Match the end of the line (or before newline at the end)
a0d0e21e 93 | Alternation
94 () Grouping
95 [] Character class
96
14218588 97By default, the "^" character is guaranteed to match only the
98beginning of the string, the "$" character only the end (or before the
99newline at the end), and Perl does certain optimizations with the
a0d0e21e 100assumption that the string contains only one line. Embedded newlines
101will not be matched by "^" or "$". You may, however, wish to treat a
4a6725af 102string as a multi-line buffer, such that the "^" will match after any
a0d0e21e 103newline within the string, and "$" will match before any newline. At the
104cost of a little more overhead, you can do this by using the /m modifier
105on the pattern match operator. (Older programs did this by setting C<$*>,
5f05dabc 106but this practice is now deprecated.)
a0d0e21e 107
14218588 108To simplify multi-line substitutions, the "." character never matches a
55497cff 109newline unless you use the C</s> modifier, which in effect tells Perl to pretend
a0d0e21e 110the string is a single line--even if it isn't. The C</s> modifier also
111overrides the setting of C<$*>, in case you have some (badly behaved) older
112code that sets it in another module.
113
114The following standard quantifiers are recognized:
115
116 * Match 0 or more times
117 + Match 1 or more times
118 ? Match 1 or 0 times
119 {n} Match exactly n times
120 {n,} Match at least n times
121 {n,m} Match at least n but not more than m times
122
123(If a curly bracket occurs in any other context, it is treated
124as a regular character.) The "*" modifier is equivalent to C<{0,}>, the "+"
25f94b33 125modifier to C<{1,}>, and the "?" modifier to C<{0,1}>. n and m are limited
9c79236d 126to integral values less than a preset limit defined when perl is built.
127This is usually 32766 on the most common platforms. The actual limit can
128be seen in the error message generated by code such as this:
129
820475bd 130 $_ **= $_ , / {$_} / for 2 .. 42;
a0d0e21e 131
54310121 132By default, a quantified subpattern is "greedy", that is, it will match as
133many times as possible (given a particular starting location) while still
134allowing the rest of the pattern to match. If you want it to match the
135minimum number of times possible, follow the quantifier with a "?". Note
136that the meanings don't change, just the "greediness":
a0d0e21e 137
138 *? Match 0 or more times
139 +? Match 1 or more times
140 ?? Match 0 or 1 time
141 {n}? Match exactly n times
142 {n,}? Match at least n times
143 {n,m}? Match at least n but not more than m times
144
5f05dabc 145Because patterns are processed as double quoted strings, the following
a0d0e21e 146also work:
147
0f36ee90 148 \t tab (HT, TAB)
149 \n newline (LF, NL)
150 \r return (CR)
151 \f form feed (FF)
152 \a alarm (bell) (BEL)
153 \e escape (think troff) (ESC)
cb1a09d0 154 \033 octal char (think of a PDP-11)
155 \x1B hex char
a0ed51b3 156 \x{263a} wide hex char (Unicode SMILEY)
a0d0e21e 157 \c[ control char
4a2d328f 158 \N{name} named char
cb1a09d0 159 \l lowercase next char (think vi)
160 \u uppercase next char (think vi)
161 \L lowercase till \E (think vi)
162 \U uppercase till \E (think vi)
163 \E end case modification (think vi)
5a964f20 164 \Q quote (disable) pattern metacharacters till \E
a0d0e21e 165
a034a98d 166If C<use locale> is in effect, the case map used by C<\l>, C<\L>, C<\u>
423cee85 167and C<\U> is taken from the current locale. See L<perllocale>. For
4a2d328f 168documentation of C<\N{name}>, see L<charnames>.
a034a98d 169
1d2dff63 170You cannot include a literal C<$> or C<@> within a C<\Q> sequence.
171An unescaped C<$> or C<@> interpolates the corresponding variable,
172while escaping will cause the literal string C<\$> to be matched.
173You'll need to write something like C<m/\Quser\E\@\Qhost/>.
174
a0d0e21e 175In addition, Perl defines the following:
176
177 \w Match a "word" character (alphanumeric plus "_")
36bbe248 178 \W Match a non-"word" character
a0d0e21e 179 \s Match a whitespace character
180 \S Match a non-whitespace character
181 \d Match a digit character
182 \D Match a non-digit character
a0ed51b3 183 \pP Match P, named property. Use \p{Prop} for longer names.
184 \PP Match non-P
f244e06d 185 \X Match eXtended Unicode "combining character sequence",
07698885 186 equivalent to (?:\PM\pM*)
72ff2908 187 \C Match a single C char (octet) even under Unicode.
07698885 188 NOTE: breaks up characters into their UTF-8 bytes,
72ff2908 189 so you may end up with malformed pieces of UTF-8.
a0d0e21e 190
08ce8fc6 191A C<\w> matches a single alphanumeric character (an alphabetic
192character, or a decimal digit) or C<_>, not a whole word. Use C<\w+>
193to match a string of Perl-identifier characters (which isn't the same
194as matching an English word). If C<use locale> is in effect, the list
195of alphabetic characters generated by C<\w> is taken from the current
196locale. See L<perllocale>. You may use C<\w>, C<\W>, C<\s>, C<\S>,
1209ba90 197C<\d>, and C<\D> within character classes, but if you try to use them
08ce8fc6 198as endpoints of a range, that's not a range, the "-" is understood
199literally. If Unicode is in effect, C<\s> matches also "\x{85}",
200"\x{2028}, and "\x{2029}", see L<perlunicode> for more details about
201C<\pP>, C<\PP>, and C<\X>, and L<perluniintro> about Unicode in
202general.
a0d0e21e 203
b8c5462f 204The POSIX character class syntax
205
820475bd 206 [:class:]
b8c5462f 207
26b44a0a 208is also available. The available classes and their backslash
209equivalents (if available) are as follows:
b8c5462f 210
211 alpha
212 alnum
213 ascii
aaa51d5e 214 blank [1]
b8c5462f 215 cntrl
216 digit \d
217 graph
218 lower
219 print
220 punct
aaa51d5e 221 space \s [2]
b8c5462f 222 upper
aaa51d5e 223 word \w [3]
b8c5462f 224 xdigit
225
07698885 226=over
227
228=item [1]
229
230A GNU extension equivalent to C<[ \t]>, `all horizontal whitespace'.
231
232=item [2]
233
234Not exactly equivalent to C<\s> since the C<[[:space:]]> includes
08ce8fc6 235also the (very rare) `vertical tabulator', "\ck", chr(11).
07698885 236
237=item [3]
238
08ce8fc6 239A Perl extension, see above.
07698885 240
241=back
aaa51d5e 242
26b44a0a 243For example use C<[:upper:]> to match all the uppercase characters.
aaa51d5e 244Note that the C<[]> are part of the C<[::]> construct, not part of the
245whole character class. For example:
b8c5462f 246
820475bd 247 [01[:alpha:]%]
b8c5462f 248
593df60c 249matches zero, one, any alphabetic character, and the percentage sign.
b8c5462f 250
72ff2908 251The following equivalences to Unicode \p{} constructs and equivalent
252backslash character classes (if available), will hold:
253
254 [:...:] \p{...} backslash
b8c5462f 255
256 alpha IsAlpha
257 alnum IsAlnum
258 ascii IsASCII
aaa51d5e 259 blank IsSpace
b8c5462f 260 cntrl IsCntrl
3bec3564 261 digit IsDigit \d
b8c5462f 262 graph IsGraph
263 lower IsLower
264 print IsPrint
265 punct IsPunct
266 space IsSpace
3bec3564 267 IsSpacePerl \s
b8c5462f 268 upper IsUpper
269 word IsWord
270 xdigit IsXDigit
271
26b44a0a 272For example C<[:lower:]> and C<\p{IsLower}> are equivalent.
b8c5462f 273
274If the C<utf8> pragma is not used but the C<locale> pragma is, the
aaa51d5e 275classes correlate with the usual isalpha(3) interface (except for
276`word' and `blank').
b8c5462f 277
278The assumedly non-obviously named classes are:
279
280=over 4
281
282=item cntrl
283
820475bd 284Any control character. Usually characters that don't produce output as
285such but instead control the terminal somehow: for example newline and
286backspace are control characters. All characters with ord() less than
593df60c 28732 are most often classified as control characters (assuming ASCII,
7be5a6cf 288the ISO Latin character sets, and Unicode), as is the character with
289the ord() value of 127 (C<DEL>).
b8c5462f 290
291=item graph
292
f1cbbd6e 293Any alphanumeric or punctuation (special) character.
b8c5462f 294
295=item print
296
f79b3095 297Any alphanumeric or punctuation (special) character or the space character.
b8c5462f 298
299=item punct
300
f1cbbd6e 301Any punctuation (special) character.
b8c5462f 302
303=item xdigit
304
593df60c 305Any hexadecimal digit. Though this may feel silly ([0-9A-Fa-f] would
820475bd 306work just fine) it is included for completeness.
b8c5462f 307
b8c5462f 308=back
309
310You can negate the [::] character classes by prefixing the class name
311with a '^'. This is a Perl extension. For example:
312
72ff2908 313 POSIX traditional Unicode
93733859 314
315 [:^digit:] \D \P{IsDigit}
316 [:^space:] \S \P{IsSpace}
317 [:^word:] \W \P{IsWord}
b8c5462f 318
26b44a0a 319The POSIX character classes [.cc.] and [=cc=] are recognized but
320B<not> supported and trying to use them will cause an error.
b8c5462f 321
a0d0e21e 322Perl defines the following zero-width assertions:
323
324 \b Match a word boundary
325 \B Match a non-(word boundary)
b85d18e9 326 \A Match only at beginning of string
327 \Z Match only at end of string, or before newline at the end
328 \z Match only at end of string
9da458fc 329 \G Match only at pos() (e.g. at the end-of-match position
330 of prior m//g)
a0d0e21e 331
14218588 332A word boundary (C<\b>) is a spot between two characters
19799a22 333that has a C<\w> on one side of it and a C<\W> on the other side
334of it (in either order), counting the imaginary characters off the
335beginning and end of the string as matching a C<\W>. (Within
336character classes C<\b> represents backspace rather than a word
337boundary, just as it normally does in any double-quoted string.)
338The C<\A> and C<\Z> are just like "^" and "$", except that they
339won't match multiple times when the C</m> modifier is used, while
340"^" and "$" will match at every internal line boundary. To match
341the actual end of the string and not ignore an optional trailing
342newline, use C<\z>.
343
344The C<\G> assertion can be used to chain global matches (using
345C<m//g>), as described in L<perlop/"Regexp Quote-Like Operators">.
346It is also useful when writing C<lex>-like scanners, when you have
347several patterns that you want to match against consequent substrings
348of your string, see the previous reference. The actual location
349where C<\G> will match can also be influenced by using C<pos()> as
350an lvalue. See L<perlfunc/pos>.
c47ff5f1 351
14218588 352The bracketing construct C<( ... )> creates capture buffers. To
c47ff5f1 353refer to the digit'th buffer use \<digit> within the
14218588 354match. Outside the match use "$" instead of "\". (The
c47ff5f1 355\<digit> notation works in certain circumstances outside
14218588 356the match. See the warning below about \1 vs $1 for details.)
357Referring back to another part of the match is called a
358I<backreference>.
359
360There is no limit to the number of captured substrings that you may
361use. However Perl also uses \10, \11, etc. as aliases for \010,
fb55449c 362\011, etc. (Recall that 0 means octal, so \011 is the character at
363number 9 in your coded character set; which would be the 10th character,
364a horizontal tab under ASCII.) Perl resolves this
365ambiguity by interpreting \10 as a backreference only if at least 10
366left parentheses have opened before it. Likewise \11 is a
367backreference only if at least 11 left parentheses have opened
368before it. And so on. \1 through \9 are always interpreted as
369backreferences.
14218588 370
371Examples:
a0d0e21e 372
373 s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words
374
14218588 375 if (/(.)\1/) { # find first doubled char
376 print "'$1' is the first doubled character\n";
377 }
c47ff5f1 378
14218588 379 if (/Time: (..):(..):(..)/) { # parse out values
a0d0e21e 380 $hours = $1;
381 $minutes = $2;
382 $seconds = $3;
383 }
c47ff5f1 384
14218588 385Several special variables also refer back to portions of the previous
386match. C<$+> returns whatever the last bracket match matched.
387C<$&> returns the entire matched string. (At one point C<$0> did
388also, but now it returns the name of the program.) C<$`> returns
389everything before the matched string. And C<$'> returns everything
390after the matched string.
391
392The numbered variables ($1, $2, $3, etc.) and the related punctuation
262ffc8b 393set (C<$+>, C<$&>, C<$`>, and C<$'>) are all dynamically scoped
14218588 394until the end of the enclosing block or until the next successful
395match, whichever comes first. (See L<perlsyn/"Compound Statements">.)
396
397B<WARNING>: Once Perl sees that you need one of C<$&>, C<$`>, or
398C<$'> anywhere in the program, it has to provide them for every
399pattern match. This may substantially slow your program. Perl
400uses the same mechanism to produce $1, $2, etc, so you also pay a
401price for each pattern that contains capturing parentheses. (To
402avoid this cost while retaining the grouping behaviour, use the
403extended regular expression C<(?: ... )> instead.) But if you never
404use C<$&>, C<$`> or C<$'>, then patterns I<without> capturing
405parentheses will not be penalized. So avoid C<$&>, C<$'>, and C<$`>
406if you can, but if you can't (and some algorithms really appreciate
407them), once you've used them once, use them at will, because you've
408already paid the price. As of 5.005, C<$&> is not so costly as the
409other two.
68dc0745 410
19799a22 411Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
412C<\w>, C<\n>. Unlike some other regular expression languages, there
413are no backslashed symbols that aren't alphanumeric. So anything
c47ff5f1 414that looks like \\, \(, \), \<, \>, \{, or \} is always
19799a22 415interpreted as a literal character, not a metacharacter. This was
416once used in a common idiom to disable or quote the special meanings
417of regular expression metacharacters in a string that you want to
36bbe248 418use for a pattern. Simply quote all non-"word" characters:
a0d0e21e 419
420 $pattern =~ s/(\W)/\\$1/g;
421
f1cbbd6e 422(If C<use locale> is set, then this depends on the current locale.)
14218588 423Today it is more common to use the quotemeta() function or the C<\Q>
424metaquoting escape sequence to disable all metacharacters' special
425meanings like this:
a0d0e21e 426
427 /$unquoted\Q$quoted\E$unquoted/
428
9da458fc 429Beware that if you put literal backslashes (those not inside
430interpolated variables) between C<\Q> and C<\E>, double-quotish
431backslash interpolation may lead to confusing results. If you
432I<need> to use literal backslashes within C<\Q...\E>,
433consult L<perlop/"Gory details of parsing quoted constructs">.
434
19799a22 435=head2 Extended Patterns
436
14218588 437Perl also defines a consistent extension syntax for features not
438found in standard tools like B<awk> and B<lex>. The syntax is a
439pair of parentheses with a question mark as the first thing within
440the parentheses. The character after the question mark indicates
441the extension.
19799a22 442
14218588 443The stability of these extensions varies widely. Some have been
444part of the core language for many years. Others are experimental
445and may change without warning or be completely removed. Check
446the documentation on an individual feature to verify its current
447status.
19799a22 448
14218588 449A question mark was chosen for this and for the minimal-matching
450construct because 1) question marks are rare in older regular
451expressions, and 2) whenever you see one, you should stop and
452"question" exactly what is going on. That's psychology...
a0d0e21e 453
454=over 10
455
cc6b7395 456=item C<(?#text)>
a0d0e21e 457
14218588 458A comment. The text is ignored. If the C</x> modifier enables
19799a22 459whitespace formatting, a simple C<#> will suffice. Note that Perl closes
259138e3 460the comment as soon as it sees a C<)>, so there is no way to put a literal
461C<)> in the comment.
a0d0e21e 462
19799a22 463=item C<(?imsx-imsx)>
464
0b6d1084 465One or more embedded pattern-match modifiers, to be turned on (or
466turned off, if preceded by C<->) for the remainder of the pattern or
467the remainder of the enclosing pattern group (if any). This is
468particularly useful for dynamic patterns, such as those read in from a
469configuration file, read in as an argument, are specified in a table
470somewhere, etc. Consider the case that some of which want to be case
471sensitive and some do not. The case insensitive ones need to include
472merely C<(?i)> at the front of the pattern. For example:
19799a22 473
474 $pattern = "foobar";
475 if ( /$pattern/i ) { }
476
477 # more flexible:
478
479 $pattern = "(?i)foobar";
480 if ( /$pattern/ ) { }
481
0b6d1084 482These modifiers are restored at the end of the enclosing group. For example,
19799a22 483
484 ( (?i) blah ) \s+ \1
485
486will match a repeated (I<including the case>!) word C<blah> in any
14218588 487case, assuming C<x> modifier, and no C<i> modifier outside this
19799a22 488group.
489
5a964f20 490=item C<(?:pattern)>
a0d0e21e 491
ca9dfc88 492=item C<(?imsx-imsx:pattern)>
493
5a964f20 494This is for clustering, not capturing; it groups subexpressions like
495"()", but doesn't make backreferences as "()" does. So
a0d0e21e 496
5a964f20 497 @fields = split(/\b(?:a|b|c)\b/)
a0d0e21e 498
499is like
500
5a964f20 501 @fields = split(/\b(a|b|c)\b/)
a0d0e21e 502
19799a22 503but doesn't spit out extra fields. It's also cheaper not to capture
504characters if you don't need to.
a0d0e21e 505
19799a22 506Any letters between C<?> and C<:> act as flags modifiers as with
507C<(?imsx-imsx)>. For example,
ca9dfc88 508
509 /(?s-i:more.*than).*million/i
510
14218588 511is equivalent to the more verbose
ca9dfc88 512
513 /(?:(?s-i)more.*than).*million/i
514
5a964f20 515=item C<(?=pattern)>
a0d0e21e 516
19799a22 517A zero-width positive look-ahead assertion. For example, C</\w+(?=\t)/>
a0d0e21e 518matches a word followed by a tab, without including the tab in C<$&>.
519
5a964f20 520=item C<(?!pattern)>
a0d0e21e 521
19799a22 522A zero-width negative look-ahead assertion. For example C</foo(?!bar)/>
a0d0e21e 523matches any occurrence of "foo" that isn't followed by "bar". Note
19799a22 524however that look-ahead and look-behind are NOT the same thing. You cannot
525use this for look-behind.
7b8d334a 526
5a964f20 527If you are looking for a "bar" that isn't preceded by a "foo", C</(?!foo)bar/>
7b8d334a 528will not do what you want. That's because the C<(?!foo)> is just saying that
529the next thing cannot be "foo"--and it's not, it's a "bar", so "foobar" will
530match. You would have to do something like C</(?!foo)...bar/> for that. We
531say "like" because there's the case of your "bar" not having three characters
532before it. You could cover that this way: C</(?:(?!foo)...|^.{0,2})bar/>.
533Sometimes it's still easier just to say:
a0d0e21e 534
a3cb178b 535 if (/bar/ && $` !~ /foo$/)
a0d0e21e 536
19799a22 537For look-behind see below.
c277df42 538
c47ff5f1 539=item C<(?<=pattern)>
c277df42 540
c47ff5f1 541A zero-width positive look-behind assertion. For example, C</(?<=\t)\w+/>
19799a22 542matches a word that follows a tab, without including the tab in C<$&>.
543Works only for fixed-width look-behind.
c277df42 544
5a964f20 545=item C<(?<!pattern)>
c277df42 546
19799a22 547A zero-width negative look-behind assertion. For example C</(?<!bar)foo/>
548matches any occurrence of "foo" that does not follow "bar". Works
549only for fixed-width look-behind.
c277df42 550
cc6b7395 551=item C<(?{ code })>
c277df42 552
19799a22 553B<WARNING>: This extended regular expression feature is considered
554highly experimental, and may be changed or deleted without notice.
c277df42 555
19799a22 556This zero-width assertion evaluate any embedded Perl code. It
557always succeeds, and its C<code> is not interpolated. Currently,
558the rules to determine where the C<code> ends are somewhat convoluted.
559
560The C<code> is properly scoped in the following sense: If the assertion
561is backtracked (compare L<"Backtracking">), all changes introduced after
562C<local>ization are undone, so that
b9ac3b5b 563
564 $_ = 'a' x 8;
565 m<
566 (?{ $cnt = 0 }) # Initialize $cnt.
567 (
568 a
569 (?{
570 local $cnt = $cnt + 1; # Update $cnt, backtracking-safe.
571 })
572 )*
573 aaaa
574 (?{ $res = $cnt }) # On success copy to non-localized
575 # location.
576 >x;
577
19799a22 578will set C<$res = 4>. Note that after the match, $cnt returns to the globally
14218588 579introduced value, because the scopes that restrict C<local> operators
b9ac3b5b 580are unwound.
581
19799a22 582This assertion may be used as a C<(?(condition)yes-pattern|no-pattern)>
583switch. If I<not> used in this way, the result of evaluation of
584C<code> is put into the special variable C<$^R>. This happens
585immediately, so C<$^R> can be used from other C<(?{ code })> assertions
586inside the same regular expression.
b9ac3b5b 587
19799a22 588The assignment to C<$^R> above is properly localized, so the old
589value of C<$^R> is restored if the assertion is backtracked; compare
590L<"Backtracking">.
b9ac3b5b 591
19799a22 592For reasons of security, this construct is forbidden if the regular
593expression involves run-time interpolation of variables, unless the
594perilous C<use re 'eval'> pragma has been used (see L<re>), or the
595variables contain results of C<qr//> operator (see
596L<perlop/"qr/STRING/imosx">).
871b0233 597
14218588 598This restriction is because of the wide-spread and remarkably convenient
19799a22 599custom of using run-time determined strings as patterns. For example:
871b0233 600
601 $re = <>;
602 chomp $re;
603 $string =~ /$re/;
604
14218588 605Before Perl knew how to execute interpolated code within a pattern,
606this operation was completely safe from a security point of view,
607although it could raise an exception from an illegal pattern. If
608you turn on the C<use re 'eval'>, though, it is no longer secure,
609so you should only do so if you are also using taint checking.
610Better yet, use the carefully constrained evaluation within a Safe
611module. See L<perlsec> for details about both these mechanisms.
871b0233 612
14455d6c 613=item C<(??{ code })>
0f5d15d6 614
19799a22 615B<WARNING>: This extended regular expression feature is considered
616highly experimental, and may be changed or deleted without notice.
9da458fc 617A simplified version of the syntax may be introduced for commonly
618used idioms.
0f5d15d6 619
19799a22 620This is a "postponed" regular subexpression. The C<code> is evaluated
621at run time, at the moment this subexpression may match. The result
622of evaluation is considered as a regular expression and matched as
623if it were inserted instead of this construct.
0f5d15d6 624
428594d9 625The C<code> is not interpolated. As before, the rules to determine
19799a22 626where the C<code> ends are currently somewhat convoluted.
627
628The following pattern matches a parenthesized group:
0f5d15d6 629
630 $re = qr{
631 \(
632 (?:
633 (?> [^()]+ ) # Non-parens without backtracking
634 |
14455d6c 635 (??{ $re }) # Group with matching parens
0f5d15d6 636 )*
637 \)
638 }x;
639
c47ff5f1 640=item C<< (?>pattern) >>
5a964f20 641
19799a22 642B<WARNING>: This extended regular expression feature is considered
643highly experimental, and may be changed or deleted without notice.
644
645An "independent" subexpression, one which matches the substring
646that a I<standalone> C<pattern> would match if anchored at the given
9da458fc 647position, and it matches I<nothing other than this substring>. This
19799a22 648construct is useful for optimizations of what would otherwise be
649"eternal" matches, because it will not backtrack (see L<"Backtracking">).
9da458fc 650It may also be useful in places where the "grab all you can, and do not
651give anything back" semantic is desirable.
19799a22 652
c47ff5f1 653For example: C<< ^(?>a*)ab >> will never match, since C<< (?>a*) >>
19799a22 654(anchored at the beginning of string, as above) will match I<all>
655characters C<a> at the beginning of string, leaving no C<a> for
656C<ab> to match. In contrast, C<a*ab> will match the same as C<a+b>,
657since the match of the subgroup C<a*> is influenced by the following
658group C<ab> (see L<"Backtracking">). In particular, C<a*> inside
659C<a*ab> will match fewer characters than a standalone C<a*>, since
660this makes the tail match.
661
c47ff5f1 662An effect similar to C<< (?>pattern) >> may be achieved by writing
19799a22 663C<(?=(pattern))\1>. This matches the same substring as a standalone
664C<a+>, and the following C<\1> eats the matched string; it therefore
c47ff5f1 665makes a zero-length assertion into an analogue of C<< (?>...) >>.
19799a22 666(The difference between these two constructs is that the second one
667uses a capturing group, thus shifting ordinals of backreferences
668in the rest of a regular expression.)
669
670Consider this pattern:
c277df42 671
871b0233 672 m{ \(
673 (
9da458fc 674 [^()]+ # x+
871b0233 675 |
676 \( [^()]* \)
677 )+
678 \)
679 }x
5a964f20 680
19799a22 681That will efficiently match a nonempty group with matching parentheses
682two levels deep or less. However, if there is no such group, it
683will take virtually forever on a long string. That's because there
684are so many different ways to split a long string into several
685substrings. This is what C<(.+)+> is doing, and C<(.+)+> is similar
686to a subpattern of the above pattern. Consider how the pattern
687above detects no-match on C<((()aaaaaaaaaaaaaaaaaa> in several
688seconds, but that each extra letter doubles this time. This
689exponential performance will make it appear that your program has
14218588 690hung. However, a tiny change to this pattern
5a964f20 691
871b0233 692 m{ \(
693 (
9da458fc 694 (?> [^()]+ ) # change x+ above to (?> x+ )
871b0233 695 |
696 \( [^()]* \)
697 )+
698 \)
699 }x
c277df42 700
c47ff5f1 701which uses C<< (?>...) >> matches exactly when the one above does (verifying
5a964f20 702this yourself would be a productive exercise), but finishes in a fourth
703the time when used on a similar string with 1000000 C<a>s. Be aware,
704however, that this pattern currently triggers a warning message under
9f1b1f2d 705the C<use warnings> pragma or B<-w> switch saying it
6bab786b 706C<"matches null string many times in regex">.
c277df42 707
c47ff5f1 708On simple groups, such as the pattern C<< (?> [^()]+ ) >>, a comparable
19799a22 709effect may be achieved by negative look-ahead, as in C<[^()]+ (?! [^()] )>.
c277df42 710This was only 4 times slower on a string with 1000000 C<a>s.
711
9da458fc 712The "grab all you can, and do not give anything back" semantic is desirable
713in many situations where on the first sight a simple C<()*> looks like
714the correct solution. Suppose we parse text with comments being delimited
715by C<#> followed by some optional (horizontal) whitespace. Contrary to
4375e838 716its appearance, C<#[ \t]*> I<is not> the correct subexpression to match
9da458fc 717the comment delimiter, because it may "give up" some whitespace if
718the remainder of the pattern can be made to match that way. The correct
719answer is either one of these:
720
721 (?>#[ \t]*)
722 #[ \t]*(?![ \t])
723
724For example, to grab non-empty comments into $1, one should use either
725one of these:
726
727 / (?> \# [ \t]* ) ( .+ ) /x;
728 / \# [ \t]* ( [^ \t] .* ) /x;
729
730Which one you pick depends on which of these expressions better reflects
731the above specification of comments.
732
5a964f20 733=item C<(?(condition)yes-pattern|no-pattern)>
c277df42 734
5a964f20 735=item C<(?(condition)yes-pattern)>
c277df42 736
19799a22 737B<WARNING>: This extended regular expression feature is considered
738highly experimental, and may be changed or deleted without notice.
739
c277df42 740Conditional expression. C<(condition)> should be either an integer in
741parentheses (which is valid if the corresponding pair of parentheses
19799a22 742matched), or look-ahead/look-behind/evaluate zero-width assertion.
c277df42 743
19799a22 744For example:
c277df42 745
5a964f20 746 m{ ( \( )?
871b0233 747 [^()]+
5a964f20 748 (?(1) \) )
871b0233 749 }x
c277df42 750
751matches a chunk of non-parentheses, possibly included in parentheses
752themselves.
a0d0e21e 753
a0d0e21e 754=back
755
c07a80fd 756=head2 Backtracking
757
35a734be 758NOTE: This section presents an abstract approximation of regular
759expression behavior. For a more rigorous (and complicated) view of
760the rules involved in selecting a match among possible alternatives,
761see L<Combining pieces together>.
762
c277df42 763A fundamental feature of regular expression matching involves the
5a964f20 764notion called I<backtracking>, which is currently used (when needed)
c277df42 765by all regular expression quantifiers, namely C<*>, C<*?>, C<+>,
9da458fc 766C<+?>, C<{n,m}>, and C<{n,m}?>. Backtracking is often optimized
767internally, but the general principle outlined here is valid.
c07a80fd 768
769For a regular expression to match, the I<entire> regular expression must
770match, not just part of it. So if the beginning of a pattern containing a
771quantifier succeeds in a way that causes later parts in the pattern to
772fail, the matching engine backs up and recalculates the beginning
773part--that's why it's called backtracking.
774
775Here is an example of backtracking: Let's say you want to find the
776word following "foo" in the string "Food is on the foo table.":
777
778 $_ = "Food is on the foo table.";
779 if ( /\b(foo)\s+(\w+)/i ) {
780 print "$2 follows $1.\n";
781 }
782
783When the match runs, the first part of the regular expression (C<\b(foo)>)
784finds a possible match right at the beginning of the string, and loads up
785$1 with "Foo". However, as soon as the matching engine sees that there's
786no whitespace following the "Foo" that it had saved in $1, it realizes its
68dc0745 787mistake and starts over again one character after where it had the
c07a80fd 788tentative match. This time it goes all the way until the next occurrence
789of "foo". The complete regular expression matches this time, and you get
790the expected output of "table follows foo."
791
792Sometimes minimal matching can help a lot. Imagine you'd like to match
793everything between "foo" and "bar". Initially, you write something
794like this:
795
796 $_ = "The food is under the bar in the barn.";
797 if ( /foo(.*)bar/ ) {
798 print "got <$1>\n";
799 }
800
801Which perhaps unexpectedly yields:
802
803 got <d is under the bar in the >
804
805That's because C<.*> was greedy, so you get everything between the
14218588 806I<first> "foo" and the I<last> "bar". Here it's more effective
c07a80fd 807to use minimal matching to make sure you get the text between a "foo"
808and the first "bar" thereafter.
809
810 if ( /foo(.*?)bar/ ) { print "got <$1>\n" }
811 got <d is under the >
812
813Here's another example: let's say you'd like to match a number at the end
b6e13d97 814of a string, and you also want to keep the preceding part of the match.
c07a80fd 815So you write this:
816
817 $_ = "I have 2 numbers: 53147";
818 if ( /(.*)(\d*)/ ) { # Wrong!
819 print "Beginning is <$1>, number is <$2>.\n";
820 }
821
822That won't work at all, because C<.*> was greedy and gobbled up the
823whole string. As C<\d*> can match on an empty string the complete
824regular expression matched successfully.
825
8e1088bc 826 Beginning is <I have 2 numbers: 53147>, number is <>.
c07a80fd 827
828Here are some variants, most of which don't work:
829
830 $_ = "I have 2 numbers: 53147";
831 @pats = qw{
832 (.*)(\d*)
833 (.*)(\d+)
834 (.*?)(\d*)
835 (.*?)(\d+)
836 (.*)(\d+)$
837 (.*?)(\d+)$
838 (.*)\b(\d+)$
839 (.*\D)(\d+)$
840 };
841
842 for $pat (@pats) {
843 printf "%-12s ", $pat;
844 if ( /$pat/ ) {
845 print "<$1> <$2>\n";
846 } else {
847 print "FAIL\n";
848 }
849 }
850
851That will print out:
852
853 (.*)(\d*) <I have 2 numbers: 53147> <>
854 (.*)(\d+) <I have 2 numbers: 5314> <7>
855 (.*?)(\d*) <> <>
856 (.*?)(\d+) <I have > <2>
857 (.*)(\d+)$ <I have 2 numbers: 5314> <7>
858 (.*?)(\d+)$ <I have 2 numbers: > <53147>
859 (.*)\b(\d+)$ <I have 2 numbers: > <53147>
860 (.*\D)(\d+)$ <I have 2 numbers: > <53147>
861
862As you see, this can be a bit tricky. It's important to realize that a
863regular expression is merely a set of assertions that gives a definition
864of success. There may be 0, 1, or several different ways that the
865definition might succeed against a particular string. And if there are
5a964f20 866multiple ways it might succeed, you need to understand backtracking to
867know which variety of success you will achieve.
c07a80fd 868
19799a22 869When using look-ahead assertions and negations, this can all get even
54310121 870tricker. Imagine you'd like to find a sequence of non-digits not
c07a80fd 871followed by "123". You might try to write that as
872
871b0233 873 $_ = "ABC123";
874 if ( /^\D*(?!123)/ ) { # Wrong!
875 print "Yup, no 123 in $_\n";
876 }
c07a80fd 877
878But that isn't going to match; at least, not the way you're hoping. It
879claims that there is no 123 in the string. Here's a clearer picture of
9b9391b2 880why that pattern matches, contrary to popular expectations:
c07a80fd 881
882 $x = 'ABC123' ;
883 $y = 'ABC445' ;
884
885 print "1: got $1\n" if $x =~ /^(ABC)(?!123)/ ;
886 print "2: got $1\n" if $y =~ /^(ABC)(?!123)/ ;
887
888 print "3: got $1\n" if $x =~ /^(\D*)(?!123)/ ;
889 print "4: got $1\n" if $y =~ /^(\D*)(?!123)/ ;
890
891This prints
892
893 2: got ABC
894 3: got AB
895 4: got ABC
896
5f05dabc 897You might have expected test 3 to fail because it seems to a more
c07a80fd 898general purpose version of test 1. The important difference between
899them is that test 3 contains a quantifier (C<\D*>) and so can use
900backtracking, whereas test 1 will not. What's happening is
901that you've asked "Is it true that at the start of $x, following 0 or more
5f05dabc 902non-digits, you have something that's not 123?" If the pattern matcher had
c07a80fd 903let C<\D*> expand to "ABC", this would have caused the whole pattern to
54310121 904fail.
14218588 905
c07a80fd 906The search engine will initially match C<\D*> with "ABC". Then it will
14218588 907try to match C<(?!123> with "123", which fails. But because
c07a80fd 908a quantifier (C<\D*>) has been used in the regular expression, the
909search engine can backtrack and retry the match differently
54310121 910in the hope of matching the complete regular expression.
c07a80fd 911
5a964f20 912The pattern really, I<really> wants to succeed, so it uses the
913standard pattern back-off-and-retry and lets C<\D*> expand to just "AB" this
c07a80fd 914time. Now there's indeed something following "AB" that is not
14218588 915"123". It's "C123", which suffices.
c07a80fd 916
14218588 917We can deal with this by using both an assertion and a negation.
918We'll say that the first part in $1 must be followed both by a digit
919and by something that's not "123". Remember that the look-aheads
920are zero-width expressions--they only look, but don't consume any
921of the string in their match. So rewriting this way produces what
c07a80fd 922you'd expect; that is, case 5 will fail, but case 6 succeeds:
923
924 print "5: got $1\n" if $x =~ /^(\D*)(?=\d)(?!123)/ ;
925 print "6: got $1\n" if $y =~ /^(\D*)(?=\d)(?!123)/ ;
926
927 6: got ABC
928
5a964f20 929In other words, the two zero-width assertions next to each other work as though
19799a22 930they're ANDed together, just as you'd use any built-in assertions: C</^$/>
c07a80fd 931matches only if you're at the beginning of the line AND the end of the
932line simultaneously. The deeper underlying truth is that juxtaposition in
933regular expressions always means AND, except when you write an explicit OR
934using the vertical bar. C</ab/> means match "a" AND (then) match "b",
935although the attempted matches are made at different positions because "a"
936is not a zero-width assertion, but a one-width assertion.
937
19799a22 938B<WARNING>: particularly complicated regular expressions can take
14218588 939exponential time to solve because of the immense number of possible
9da458fc 940ways they can use backtracking to try match. For example, without
941internal optimizations done by the regular expression engine, this will
942take a painfully long time to run:
c07a80fd 943
e1901655 944 'aaaaaaaaaaaa' =~ /((a{0,5}){0,5})*[c]/
945
946And if you used C<*>'s in the internal groups instead of limiting them
947to 0 through 5 matches, then it would take forever--or until you ran
948out of stack space. Moreover, these internal optimizations are not
949always applicable. For example, if you put C<{0,5}> instead of C<*>
950on the external group, no current optimization is applicable, and the
951match takes a long time to finish.
c07a80fd 952
9da458fc 953A powerful tool for optimizing such beasts is what is known as an
954"independent group",
c47ff5f1 955which does not backtrack (see L<C<< (?>pattern) >>>). Note also that
9da458fc 956zero-length look-ahead/look-behind assertions will not backtrack to make
14218588 957the tail match, since they are in "logical" context: only
958whether they match is considered relevant. For an example
9da458fc 959where side-effects of look-ahead I<might> have influenced the
c47ff5f1 960following match, see L<C<< (?>pattern) >>>.
c277df42 961
a0d0e21e 962=head2 Version 8 Regular Expressions
963
5a964f20 964In case you're not familiar with the "regular" Version 8 regex
a0d0e21e 965routines, here are the pattern-matching rules not described above.
966
54310121 967Any single character matches itself, unless it is a I<metacharacter>
a0d0e21e 968with a special meaning described here or above. You can cause
5a964f20 969characters that normally function as metacharacters to be interpreted
5f05dabc 970literally by prefixing them with a "\" (e.g., "\." matches a ".", not any
a0d0e21e 971character; "\\" matches a "\"). A series of characters matches that
972series of characters in the target string, so the pattern C<blurfl>
973would match "blurfl" in the target string.
974
975You can specify a character class, by enclosing a list of characters
5a964f20 976in C<[]>, which will match any one character from the list. If the
a0d0e21e 977first character after the "[" is "^", the class matches any character not
14218588 978in the list. Within a list, the "-" character specifies a
5a964f20 979range, so that C<a-z> represents all characters between "a" and "z",
8a4f6ac2 980inclusive. If you want either "-" or "]" itself to be a member of a
981class, put it at the start of the list (possibly after a "^"), or
982escape it with a backslash. "-" is also taken literally when it is
983at the end of the list, just before the closing "]". (The
84850974 984following all specify the same class of three characters: C<[-az]>,
985C<[az-]>, and C<[a\-z]>. All are different from C<[a-z]>, which
fb55449c 986specifies a class containing twenty-six characters, even on EBCDIC
987based coded character sets.) Also, if you try to use the character
988classes C<\w>, C<\W>, C<\s>, C<\S>, C<\d>, or C<\D> as endpoints of
989a range, that's not a range, the "-" is understood literally.
a0d0e21e 990
8ada0baa 991Note also that the whole range idea is rather unportable between
992character sets--and even within character sets they may cause results
993you probably didn't expect. A sound principle is to use only ranges
994that begin from and end at either alphabets of equal case ([a-e],
995[A-E]), or digits ([0-9]). Anything else is unsafe. If in doubt,
996spell out the character sets in full.
997
54310121 998Characters may be specified using a metacharacter syntax much like that
a0d0e21e 999used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return,
1000"\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string
fb55449c 1001of octal digits, matches the character whose coded character set value
1002is I<nnn>. Similarly, \xI<nn>, where I<nn> are hexadecimal digits,
1003matches the character whose numeric value is I<nn>. The expression \cI<x>
1004matches the character control-I<x>. Finally, the "." metacharacter
1005matches any character except "\n" (unless you use C</s>).
a0d0e21e 1006
1007You can specify a series of alternatives for a pattern using "|" to
1008separate them, so that C<fee|fie|foe> will match any of "fee", "fie",
5a964f20 1009or "foe" in the target string (as would C<f(e|i|o)e>). The
a0d0e21e 1010first alternative includes everything from the last pattern delimiter
1011("(", "[", or the beginning of the pattern) up to the first "|", and
1012the last alternative contains everything from the last "|" to the next
14218588 1013pattern delimiter. That's why it's common practice to include
1014alternatives in parentheses: to minimize confusion about where they
a3cb178b 1015start and end.
1016
5a964f20 1017Alternatives are tried from left to right, so the first
a3cb178b 1018alternative found for which the entire expression matches, is the one that
1019is chosen. This means that alternatives are not necessarily greedy. For
628afcb5 1020example: when matching C<foo|foot> against "barefoot", only the "foo"
a3cb178b 1021part will match, as that is the first alternative tried, and it successfully
1022matches the target string. (This might not seem important, but it is
1023important when you are capturing matched text using parentheses.)
1024
5a964f20 1025Also remember that "|" is interpreted as a literal within square brackets,
a3cb178b 1026so if you write C<[fee|fie|foe]> you're really only matching C<[feio|]>.
a0d0e21e 1027
14218588 1028Within a pattern, you may designate subpatterns for later reference
1029by enclosing them in parentheses, and you may refer back to the
1030I<n>th subpattern later in the pattern using the metacharacter
1031\I<n>. Subpatterns are numbered based on the left to right order
1032of their opening parenthesis. A backreference matches whatever
1033actually matched the subpattern in the string being examined, not
1034the rules for that subpattern. Therefore, C<(0|0x)\d*\s\1\d*> will
1035match "0x1234 0x4321", but not "0x1234 01234", because subpattern
10361 matched "0x", even though the rule C<0|0x> could potentially match
1037the leading 0 in the second number.
cb1a09d0 1038
19799a22 1039=head2 Warning on \1 vs $1
cb1a09d0 1040
5a964f20 1041Some people get too used to writing things like:
cb1a09d0 1042
1043 $pattern =~ s/(\W)/\\\1/g;
1044
1045This is grandfathered for the RHS of a substitute to avoid shocking the
1046B<sed> addicts, but it's a dirty habit to get into. That's because in
d1be9408 1047PerlThink, the righthand side of an C<s///> is a double-quoted string. C<\1> in
cb1a09d0 1048the usual double-quoted string means a control-A. The customary Unix
1049meaning of C<\1> is kludged in for C<s///>. However, if you get into the habit
1050of doing that, you get yourself into trouble if you then add an C</e>
1051modifier.
1052
5a964f20 1053 s/(\d+)/ \1 + 1 /eg; # causes warning under -w
cb1a09d0 1054
1055Or if you try to do
1056
1057 s/(\d+)/\1000/;
1058
1059You can't disambiguate that by saying C<\{1}000>, whereas you can fix it with
14218588 1060C<${1}000>. The operation of interpolation should not be confused
cb1a09d0 1061with the operation of matching a backreference. Certainly they mean two
1062different things on the I<left> side of the C<s///>.
9fa51da4 1063
c84d73f1 1064=head2 Repeated patterns matching zero-length substring
1065
19799a22 1066B<WARNING>: Difficult material (and prose) ahead. This section needs a rewrite.
c84d73f1 1067
1068Regular expressions provide a terse and powerful programming language. As
1069with most other power tools, power comes together with the ability
1070to wreak havoc.
1071
1072A common abuse of this power stems from the ability to make infinite
628afcb5 1073loops using regular expressions, with something as innocuous as:
c84d73f1 1074
1075 'foo' =~ m{ ( o? )* }x;
1076
1077The C<o?> can match at the beginning of C<'foo'>, and since the position
1078in the string is not moved by the match, C<o?> would match again and again
14218588 1079because of the C<*> modifier. Another common way to create a similar cycle
c84d73f1 1080is with the looping modifier C<//g>:
1081
1082 @matches = ( 'foo' =~ m{ o? }xg );
1083
1084or
1085
1086 print "match: <$&>\n" while 'foo' =~ m{ o? }xg;
1087
1088or the loop implied by split().
1089
1090However, long experience has shown that many programming tasks may
14218588 1091be significantly simplified by using repeated subexpressions that
1092may match zero-length substrings. Here's a simple example being:
c84d73f1 1093
1094 @chars = split //, $string; # // is not magic in split
1095 ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /
1096
9da458fc 1097Thus Perl allows such constructs, by I<forcefully breaking
c84d73f1 1098the infinite loop>. The rules for this are different for lower-level
1099loops given by the greedy modifiers C<*+{}>, and for higher-level
1100ones like the C</g> modifier or split() operator.
1101
19799a22 1102The lower-level loops are I<interrupted> (that is, the loop is
1103broken) when Perl detects that a repeated expression matched a
1104zero-length substring. Thus
c84d73f1 1105
1106 m{ (?: NON_ZERO_LENGTH | ZERO_LENGTH )* }x;
1107
1108is made equivalent to
1109
1110 m{ (?: NON_ZERO_LENGTH )*
1111 |
1112 (?: ZERO_LENGTH )?
1113 }x;
1114
1115The higher level-loops preserve an additional state between iterations:
1116whether the last match was zero-length. To break the loop, the following
1117match after a zero-length match is prohibited to have a length of zero.
1118This prohibition interacts with backtracking (see L<"Backtracking">),
1119and so the I<second best> match is chosen if the I<best> match is of
1120zero length.
1121
19799a22 1122For example:
c84d73f1 1123
1124 $_ = 'bar';
1125 s/\w??/<$&>/g;
1126
20fb949f 1127results in C<< <><b><><a><><r><> >>. At each position of the string the best
c84d73f1 1128match given by non-greedy C<??> is the zero-length match, and the I<second
1129best> match is what is matched by C<\w>. Thus zero-length matches
1130alternate with one-character-long matches.
1131
1132Similarly, for repeated C<m/()/g> the second-best match is the match at the
1133position one notch further in the string.
1134
19799a22 1135The additional state of being I<matched with zero-length> is associated with
c84d73f1 1136the matched string, and is reset by each assignment to pos().
9da458fc 1137Zero-length matches at the end of the previous match are ignored
1138during C<split>.
c84d73f1 1139
35a734be 1140=head2 Combining pieces together
1141
1142Each of the elementary pieces of regular expressions which were described
1143before (such as C<ab> or C<\Z>) could match at most one substring
1144at the given position of the input string. However, in a typical regular
1145expression these elementary pieces are combined into more complicated
1146patterns using combining operators C<ST>, C<S|T>, C<S*> etc
1147(in these examples C<S> and C<T> are regular subexpressions).
1148
1149Such combinations can include alternatives, leading to a problem of choice:
1150if we match a regular expression C<a|ab> against C<"abc">, will it match
1151substring C<"a"> or C<"ab">? One way to describe which substring is
1152actually matched is the concept of backtracking (see L<"Backtracking">).
1153However, this description is too low-level and makes you think
1154in terms of a particular implementation.
1155
1156Another description starts with notions of "better"/"worse". All the
1157substrings which may be matched by the given regular expression can be
1158sorted from the "best" match to the "worst" match, and it is the "best"
1159match which is chosen. This substitutes the question of "what is chosen?"
1160by the question of "which matches are better, and which are worse?".
1161
1162Again, for elementary pieces there is no such question, since at most
1163one match at a given position is possible. This section describes the
1164notion of better/worse for combining operators. In the description
1165below C<S> and C<T> are regular subexpressions.
1166
13a2d996 1167=over 4
35a734be 1168
1169=item C<ST>
1170
1171Consider two possible matches, C<AB> and C<A'B'>, C<A> and C<A'> are
1172substrings which can be matched by C<S>, C<B> and C<B'> are substrings
1173which can be matched by C<T>.
1174
1175If C<A> is better match for C<S> than C<A'>, C<AB> is a better
1176match than C<A'B'>.
1177
1178If C<A> and C<A'> coincide: C<AB> is a better match than C<AB'> if
1179C<B> is better match for C<T> than C<B'>.
1180
1181=item C<S|T>
1182
1183When C<S> can match, it is a better match than when only C<T> can match.
1184
1185Ordering of two matches for C<S> is the same as for C<S>. Similar for
1186two matches for C<T>.
1187
1188=item C<S{REPEAT_COUNT}>
1189
1190Matches as C<SSS...S> (repeated as many times as necessary).
1191
1192=item C<S{min,max}>
1193
1194Matches as C<S{max}|S{max-1}|...|S{min+1}|S{min}>.
1195
1196=item C<S{min,max}?>
1197
1198Matches as C<S{min}|S{min+1}|...|S{max-1}|S{max}>.
1199
1200=item C<S?>, C<S*>, C<S+>
1201
1202Same as C<S{0,1}>, C<S{0,BIG_NUMBER}>, C<S{1,BIG_NUMBER}> respectively.
1203
1204=item C<S??>, C<S*?>, C<S+?>
1205
1206Same as C<S{0,1}?>, C<S{0,BIG_NUMBER}?>, C<S{1,BIG_NUMBER}?> respectively.
1207
c47ff5f1 1208=item C<< (?>S) >>
35a734be 1209
1210Matches the best match for C<S> and only that.
1211
1212=item C<(?=S)>, C<(?<=S)>
1213
1214Only the best match for C<S> is considered. (This is important only if
1215C<S> has capturing parentheses, and backreferences are used somewhere
1216else in the whole regular expression.)
1217
1218=item C<(?!S)>, C<(?<!S)>
1219
1220For this grouping operator there is no need to describe the ordering, since
1221only whether or not C<S> can match is important.
1222
14455d6c 1223=item C<(??{ EXPR })>
35a734be 1224
1225The ordering is the same as for the regular expression which is
1226the result of EXPR.
1227
1228=item C<(?(condition)yes-pattern|no-pattern)>
1229
1230Recall that which of C<yes-pattern> or C<no-pattern> actually matches is
1231already determined. The ordering of the matches is the same as for the
1232chosen subexpression.
1233
1234=back
1235
1236The above recipes describe the ordering of matches I<at a given position>.
1237One more rule is needed to understand how a match is determined for the
1238whole regular expression: a match at an earlier position is always better
1239than a match at a later position.
1240
c84d73f1 1241=head2 Creating custom RE engines
1242
1243Overloaded constants (see L<overload>) provide a simple way to extend
1244the functionality of the RE engine.
1245
1246Suppose that we want to enable a new RE escape-sequence C<\Y|> which
1247matches at boundary between white-space characters and non-whitespace
1248characters. Note that C<(?=\S)(?<!\S)|(?!\S)(?<=\S)> matches exactly
1249at these positions, so we want to have each C<\Y|> in the place of the
1250more complicated version. We can create a module C<customre> to do
1251this:
1252
1253 package customre;
1254 use overload;
1255
1256 sub import {
1257 shift;
1258 die "No argument to customre::import allowed" if @_;
1259 overload::constant 'qr' => \&convert;
1260 }
1261
1262 sub invalid { die "/$_[0]/: invalid escape '\\$_[1]'"}
1263
1264 my %rules = ( '\\' => '\\',
1265 'Y|' => qr/(?=\S)(?<!\S)|(?!\S)(?<=\S)/ );
1266 sub convert {
1267 my $re = shift;
1268 $re =~ s{
1269 \\ ( \\ | Y . )
1270 }
1271 { $rules{$1} or invalid($re,$1) }sgex;
1272 return $re;
1273 }
1274
1275Now C<use customre> enables the new escape in constant regular
1276expressions, i.e., those without any runtime variable interpolations.
1277As documented in L<overload>, this conversion will work only over
1278literal parts of regular expressions. For C<\Y|$re\Y|> the variable
1279part of this regular expression needs to be converted explicitly
1280(but only if the special meaning of C<\Y|> should be enabled inside $re):
1281
1282 use customre;
1283 $re = <>;
1284 chomp $re;
1285 $re = customre::convert $re;
1286 /\Y|$re\Y|/;
1287
19799a22 1288=head1 BUGS
1289
9da458fc 1290This document varies from difficult to understand to completely
1291and utterly opaque. The wandering prose riddled with jargon is
1292hard to fathom in several places.
1293
1294This document needs a rewrite that separates the tutorial content
1295from the reference content.
19799a22 1296
1297=head1 SEE ALSO
9fa51da4 1298
91e0c79e 1299L<perlrequick>.
1300
1301L<perlretut>.
1302
9b599b2a 1303L<perlop/"Regexp Quote-Like Operators">.
1304
1e66bd83 1305L<perlop/"Gory details of parsing quoted constructs">.
1306
14218588 1307L<perlfaq6>.
1308
9b599b2a 1309L<perlfunc/pos>.
1310
1311L<perllocale>.
1312
fb55449c 1313L<perlebcdic>.
1314
14218588 1315I<Mastering Regular Expressions> by Jeffrey Friedl, published
1316by O'Reilly and Associates.