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