This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Mention EPOC and SOCKS.
[perl5.git] / pod / perlre.pod
CommitLineData
a0d0e21e
LW
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
GS
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
PP
18=over 4
19
20=item i
21
22Do case-insensitive pattern matching.
23
a034a98d
DD
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
PP
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
PP
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
GS
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
PP
47
48Extend your pattern's legibility by permitting whitespace and comments.
49
50=back
a0d0e21e
LW
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
PP
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
PP
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
HS
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
LW
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
GS
76(distantly) from Henry Spencer's freely redistributable reimplementation
77of the V8 routines.) See L<Version 8 Regular Expressions> for
78details.
a0d0e21e
LW
79
80In particular the following metacharacters have their standard I<egrep>-ish
81meanings:
82
54310121 83 \ Quote the next metacharacter
a0d0e21e
LW
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
LW
87 | Alternation
88 () Grouping
89 [] Character class
90
14218588
GS
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
LW
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
LW
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
LW
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
GS
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
124 $_ **= $_ , / {$_} / for 2 .. 42;
a0d0e21e 125
54310121
PP
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
LW
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
LW
140also work:
141
0f36ee90
PP
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
AD
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
cb1a09d0
AD
152 \l lowercase next char (think vi)
153 \u uppercase next char (think vi)
154 \L lowercase till \E (think vi)
155 \U uppercase till \E (think vi)
156 \E end case modification (think vi)
5a964f20 157 \Q quote (disable) pattern metacharacters till \E
a0d0e21e 158
a034a98d 159If C<use locale> is in effect, the case map used by C<\l>, C<\L>, C<\u>
7b8d334a 160and C<\U> is taken from the current locale. See L<perllocale>.
a034a98d 161
1d2dff63
GS
162You cannot include a literal C<$> or C<@> within a C<\Q> sequence.
163An unescaped C<$> or C<@> interpolates the corresponding variable,
164while escaping will cause the literal string C<\$> to be matched.
165You'll need to write something like C<m/\Quser\E\@\Qhost/>.
166
a0d0e21e
LW
167In addition, Perl defines the following:
168
169 \w Match a "word" character (alphanumeric plus "_")
170 \W Match a non-word character
171 \s Match a whitespace character
172 \S Match a non-whitespace character
173 \d Match a digit character
174 \D Match a non-digit character
a0ed51b3
LW
175 \pP Match P, named property. Use \p{Prop} for longer names.
176 \PP Match non-P
f244e06d
GS
177 \X Match eXtended Unicode "combining character sequence",
178 equivalent to C<(?:\PM\pM*)>
a0ed51b3 179 \C Match a single C char (octet) even under utf8.
a0d0e21e 180
19799a22 181A C<\w> matches a single alphanumeric character, not a whole word.
14218588
GS
182Use C<\w+> to match a string of Perl-identifier characters (which isn't
183the same as matching an English word). If C<use locale> is in effect, the
184list of alphabetic characters generated by C<\w> is taken from the
185current locale. See L<perllocale>. You may use C<\w>, C<\W>, C<\s>, C<\S>,
186C<\d>, and C<\D> within character classes (though not as either end of
187a range). See L<utf8> for details about C<\pP>, C<\PP>, and C<\X>.
a0d0e21e
LW
188
189Perl defines the following zero-width assertions:
190
191 \b Match a word boundary
192 \B Match a non-(word boundary)
b85d18e9
IZ
193 \A Match only at beginning of string
194 \Z Match only at end of string, or before newline at the end
195 \z Match only at end of string
a99df21c 196 \G Match only where previous m//g left off (works only with /g)
a0d0e21e 197
14218588 198A word boundary (C<\b>) is a spot between two characters
19799a22
GS
199that has a C<\w> on one side of it and a C<\W> on the other side
200of it (in either order), counting the imaginary characters off the
201beginning and end of the string as matching a C<\W>. (Within
202character classes C<\b> represents backspace rather than a word
203boundary, just as it normally does in any double-quoted string.)
204The C<\A> and C<\Z> are just like "^" and "$", except that they
205won't match multiple times when the C</m> modifier is used, while
206"^" and "$" will match at every internal line boundary. To match
207the actual end of the string and not ignore an optional trailing
208newline, use C<\z>.
209
210The C<\G> assertion can be used to chain global matches (using
211C<m//g>), as described in L<perlop/"Regexp Quote-Like Operators">.
212It is also useful when writing C<lex>-like scanners, when you have
213several patterns that you want to match against consequent substrings
214of your string, see the previous reference. The actual location
215where C<\G> will match can also be influenced by using C<pos()> as
216an lvalue. See L<perlfunc/pos>.
14218588
GS
217
218The bracketing construct C<( ... )> creates capture buffers. To
219refer to the digit'th buffer use \E<lt>digitE<gt> within the
220match. Outside the match use "$" instead of "\". (The
221\E<lt>digitE<gt> notation works in certain circumstances outside
222the match. See the warning below about \1 vs $1 for details.)
223Referring back to another part of the match is called a
224I<backreference>.
225
226There is no limit to the number of captured substrings that you may
227use. However Perl also uses \10, \11, etc. as aliases for \010,
228\011, etc. (Recall that 0 means octal, so \011 is the 9'th ASCII
229character, a tab.) Perl resolves this ambiguity by interpreting
230\10 as a backreference only if at least 10 left parentheses have
231opened before it. Likewise \11 is a backreference only if at least
23211 left parentheses have opened before it. And so on. \1 through
233\9 are always interpreted as backreferences."
234
235Examples:
a0d0e21e
LW
236
237 s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words
238
14218588
GS
239 if (/(.)\1/) { # find first doubled char
240 print "'$1' is the first doubled character\n";
241 }
242
243 if (/Time: (..):(..):(..)/) { # parse out values
a0d0e21e
LW
244 $hours = $1;
245 $minutes = $2;
246 $seconds = $3;
247 }
14218588
GS
248
249Several special variables also refer back to portions of the previous
250match. C<$+> returns whatever the last bracket match matched.
251C<$&> returns the entire matched string. (At one point C<$0> did
252also, but now it returns the name of the program.) C<$`> returns
253everything before the matched string. And C<$'> returns everything
254after the matched string.
255
256The numbered variables ($1, $2, $3, etc.) and the related punctuation
257set (C<<$+>, C<$&>, C<$`>, and C<$'>) are all dynamically scoped
258until the end of the enclosing block or until the next successful
259match, whichever comes first. (See L<perlsyn/"Compound Statements">.)
260
261B<WARNING>: Once Perl sees that you need one of C<$&>, C<$`>, or
262C<$'> anywhere in the program, it has to provide them for every
263pattern match. This may substantially slow your program. Perl
264uses the same mechanism to produce $1, $2, etc, so you also pay a
265price for each pattern that contains capturing parentheses. (To
266avoid this cost while retaining the grouping behaviour, use the
267extended regular expression C<(?: ... )> instead.) But if you never
268use C<$&>, C<$`> or C<$'>, then patterns I<without> capturing
269parentheses will not be penalized. So avoid C<$&>, C<$'>, and C<$`>
270if you can, but if you can't (and some algorithms really appreciate
271them), once you've used them once, use them at will, because you've
272already paid the price. As of 5.005, C<$&> is not so costly as the
273other two.
68dc0745 274
19799a22
GS
275Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
276C<\w>, C<\n>. Unlike some other regular expression languages, there
277are no backslashed symbols that aren't alphanumeric. So anything
278that looks like \\, \(, \), \E<lt>, \E<gt>, \{, or \} is always
279interpreted as a literal character, not a metacharacter. This was
280once used in a common idiom to disable or quote the special meanings
281of regular expression metacharacters in a string that you want to
282use for a pattern. Simply quote all non-alphanumeric characters:
a0d0e21e
LW
283
284 $pattern =~ s/(\W)/\\$1/g;
285
14218588
GS
286Today it is more common to use the quotemeta() function or the C<\Q>
287metaquoting escape sequence to disable all metacharacters' special
288meanings like this:
a0d0e21e
LW
289
290 /$unquoted\Q$quoted\E$unquoted/
291
19799a22
GS
292=head2 Extended Patterns
293
14218588
GS
294Perl also defines a consistent extension syntax for features not
295found in standard tools like B<awk> and B<lex>. The syntax is a
296pair of parentheses with a question mark as the first thing within
297the parentheses. The character after the question mark indicates
298the extension.
19799a22 299
14218588
GS
300The stability of these extensions varies widely. Some have been
301part of the core language for many years. Others are experimental
302and may change without warning or be completely removed. Check
303the documentation on an individual feature to verify its current
304status.
19799a22 305
14218588
GS
306A question mark was chosen for this and for the minimal-matching
307construct because 1) question marks are rare in older regular
308expressions, and 2) whenever you see one, you should stop and
309"question" exactly what is going on. That's psychology...
a0d0e21e
LW
310
311=over 10
312
cc6b7395 313=item C<(?#text)>
a0d0e21e 314
14218588 315A comment. The text is ignored. If the C</x> modifier enables
19799a22 316whitespace formatting, a simple C<#> will suffice. Note that Perl closes
259138e3
GS
317the comment as soon as it sees a C<)>, so there is no way to put a literal
318C<)> in the comment.
a0d0e21e 319
19799a22
GS
320=item C<(?imsx-imsx)>
321
322One or more embedded pattern-match modifiers. This is particularly
323useful for dynamic patterns, such as those read in from a configuration
324file, read in as an argument, are specified in a table somewhere,
325etc. Consider the case that some of which want to be case sensitive
326and some do not. The case insensitive ones need to include merely
327C<(?i)> at the front of the pattern. For example:
328
329 $pattern = "foobar";
330 if ( /$pattern/i ) { }
331
332 # more flexible:
333
334 $pattern = "(?i)foobar";
335 if ( /$pattern/ ) { }
336
337Letters after a C<-> turn those modifiers off. These modifiers are
338localized inside an enclosing group (if any). For example,
339
340 ( (?i) blah ) \s+ \1
341
342will match a repeated (I<including the case>!) word C<blah> in any
14218588 343case, assuming C<x> modifier, and no C<i> modifier outside this
19799a22
GS
344group.
345
5a964f20 346=item C<(?:pattern)>
a0d0e21e 347
ca9dfc88
IZ
348=item C<(?imsx-imsx:pattern)>
349
5a964f20
TC
350This is for clustering, not capturing; it groups subexpressions like
351"()", but doesn't make backreferences as "()" does. So
a0d0e21e 352
5a964f20 353 @fields = split(/\b(?:a|b|c)\b/)
a0d0e21e
LW
354
355is like
356
5a964f20 357 @fields = split(/\b(a|b|c)\b/)
a0d0e21e 358
19799a22
GS
359but doesn't spit out extra fields. It's also cheaper not to capture
360characters if you don't need to.
a0d0e21e 361
19799a22
GS
362Any letters between C<?> and C<:> act as flags modifiers as with
363C<(?imsx-imsx)>. For example,
ca9dfc88
IZ
364
365 /(?s-i:more.*than).*million/i
366
14218588 367is equivalent to the more verbose
ca9dfc88
IZ
368
369 /(?:(?s-i)more.*than).*million/i
370
5a964f20 371=item C<(?=pattern)>
a0d0e21e 372
19799a22 373A zero-width positive look-ahead assertion. For example, C</\w+(?=\t)/>
a0d0e21e
LW
374matches a word followed by a tab, without including the tab in C<$&>.
375
5a964f20 376=item C<(?!pattern)>
a0d0e21e 377
19799a22 378A zero-width negative look-ahead assertion. For example C</foo(?!bar)/>
a0d0e21e 379matches any occurrence of "foo" that isn't followed by "bar". Note
19799a22
GS
380however that look-ahead and look-behind are NOT the same thing. You cannot
381use this for look-behind.
7b8d334a 382
5a964f20 383If you are looking for a "bar" that isn't preceded by a "foo", C</(?!foo)bar/>
7b8d334a
GS
384will not do what you want. That's because the C<(?!foo)> is just saying that
385the next thing cannot be "foo"--and it's not, it's a "bar", so "foobar" will
386match. You would have to do something like C</(?!foo)...bar/> for that. We
387say "like" because there's the case of your "bar" not having three characters
388before it. You could cover that this way: C</(?:(?!foo)...|^.{0,2})bar/>.
389Sometimes it's still easier just to say:
a0d0e21e 390
a3cb178b 391 if (/bar/ && $` !~ /foo$/)
a0d0e21e 392
19799a22 393For look-behind see below.
c277df42 394
5a964f20 395=item C<(?E<lt>=pattern)>
c277df42 396
19799a22
GS
397A zero-width positive look-behind assertion. For example, C</(?E<lt>=\t)\w+/>
398matches a word that follows a tab, without including the tab in C<$&>.
399Works only for fixed-width look-behind.
c277df42 400
5a964f20 401=item C<(?<!pattern)>
c277df42 402
19799a22
GS
403A zero-width negative look-behind assertion. For example C</(?<!bar)foo/>
404matches any occurrence of "foo" that does not follow "bar". Works
405only for fixed-width look-behind.
c277df42 406
cc6b7395 407=item C<(?{ code })>
c277df42 408
19799a22
GS
409B<WARNING>: This extended regular expression feature is considered
410highly experimental, and may be changed or deleted without notice.
c277df42 411
19799a22
GS
412This zero-width assertion evaluate any embedded Perl code. It
413always succeeds, and its C<code> is not interpolated. Currently,
414the rules to determine where the C<code> ends are somewhat convoluted.
415
416The C<code> is properly scoped in the following sense: If the assertion
417is backtracked (compare L<"Backtracking">), all changes introduced after
418C<local>ization are undone, so that
b9ac3b5b
GS
419
420 $_ = 'a' x 8;
421 m<
422 (?{ $cnt = 0 }) # Initialize $cnt.
423 (
424 a
425 (?{
426 local $cnt = $cnt + 1; # Update $cnt, backtracking-safe.
427 })
428 )*
429 aaaa
430 (?{ $res = $cnt }) # On success copy to non-localized
431 # location.
432 >x;
433
19799a22 434will set C<$res = 4>. Note that after the match, $cnt returns to the globally
14218588 435introduced value, because the scopes that restrict C<local> operators
b9ac3b5b
GS
436are unwound.
437
19799a22
GS
438This assertion may be used as a C<(?(condition)yes-pattern|no-pattern)>
439switch. If I<not> used in this way, the result of evaluation of
440C<code> is put into the special variable C<$^R>. This happens
441immediately, so C<$^R> can be used from other C<(?{ code })> assertions
442inside the same regular expression.
b9ac3b5b 443
19799a22
GS
444The assignment to C<$^R> above is properly localized, so the old
445value of C<$^R> is restored if the assertion is backtracked; compare
446L<"Backtracking">.
b9ac3b5b 447
19799a22
GS
448For reasons of security, this construct is forbidden if the regular
449expression involves run-time interpolation of variables, unless the
450perilous C<use re 'eval'> pragma has been used (see L<re>), or the
451variables contain results of C<qr//> operator (see
452L<perlop/"qr/STRING/imosx">).
871b0233 453
14218588 454This restriction is because of the wide-spread and remarkably convenient
19799a22 455custom of using run-time determined strings as patterns. For example:
871b0233
IZ
456
457 $re = <>;
458 chomp $re;
459 $string =~ /$re/;
460
14218588
GS
461Before Perl knew how to execute interpolated code within a pattern,
462this operation was completely safe from a security point of view,
463although it could raise an exception from an illegal pattern. If
464you turn on the C<use re 'eval'>, though, it is no longer secure,
465so you should only do so if you are also using taint checking.
466Better yet, use the carefully constrained evaluation within a Safe
467module. See L<perlsec> for details about both these mechanisms.
871b0233 468
0f5d15d6
IZ
469=item C<(?p{ code })>
470
19799a22
GS
471B<WARNING>: This extended regular expression feature is considered
472highly experimental, and may be changed or deleted without notice.
0f5d15d6 473
19799a22
GS
474This is a "postponed" regular subexpression. The C<code> is evaluated
475at run time, at the moment this subexpression may match. The result
476of evaluation is considered as a regular expression and matched as
477if it were inserted instead of this construct.
0f5d15d6 478
19799a22
GS
479C<code> is not interpolated. As before, the rules to determine
480where the C<code> ends are currently somewhat convoluted.
481
482The following pattern matches a parenthesized group:
0f5d15d6
IZ
483
484 $re = qr{
485 \(
486 (?:
487 (?> [^()]+ ) # Non-parens without backtracking
488 |
489 (?p{ $re }) # Group with matching parens
490 )*
491 \)
492 }x;
493
5a964f20
TC
494=item C<(?E<gt>pattern)>
495
19799a22
GS
496B<WARNING>: This extended regular expression feature is considered
497highly experimental, and may be changed or deleted without notice.
498
499An "independent" subexpression, one which matches the substring
500that a I<standalone> C<pattern> would match if anchored at the given
14218588 501position--but it matches no more than this substring. This
19799a22
GS
502construct is useful for optimizations of what would otherwise be
503"eternal" matches, because it will not backtrack (see L<"Backtracking">).
504
505For example: C<^(?E<gt>a*)ab> will never match, since C<(?E<gt>a*)>
506(anchored at the beginning of string, as above) will match I<all>
507characters C<a> at the beginning of string, leaving no C<a> for
508C<ab> to match. In contrast, C<a*ab> will match the same as C<a+b>,
509since the match of the subgroup C<a*> is influenced by the following
510group C<ab> (see L<"Backtracking">). In particular, C<a*> inside
511C<a*ab> will match fewer characters than a standalone C<a*>, since
512this makes the tail match.
513
514An effect similar to C<(?E<gt>pattern)> may be achieved by writing
515C<(?=(pattern))\1>. This matches the same substring as a standalone
516C<a+>, and the following C<\1> eats the matched string; it therefore
517makes a zero-length assertion into an analogue of C<(?E<gt>...)>.
518(The difference between these two constructs is that the second one
519uses a capturing group, thus shifting ordinals of backreferences
520in the rest of a regular expression.)
521
522Consider this pattern:
c277df42 523
871b0233
IZ
524 m{ \(
525 (
526 [^()]+
527 |
528 \( [^()]* \)
529 )+
530 \)
531 }x
5a964f20 532
19799a22
GS
533That will efficiently match a nonempty group with matching parentheses
534two levels deep or less. However, if there is no such group, it
535will take virtually forever on a long string. That's because there
536are so many different ways to split a long string into several
537substrings. This is what C<(.+)+> is doing, and C<(.+)+> is similar
538to a subpattern of the above pattern. Consider how the pattern
539above detects no-match on C<((()aaaaaaaaaaaaaaaaaa> in several
540seconds, but that each extra letter doubles this time. This
541exponential performance will make it appear that your program has
14218588 542hung. However, a tiny change to this pattern
5a964f20 543
871b0233
IZ
544 m{ \(
545 (
546 (?> [^()]+ )
547 |
548 \( [^()]* \)
549 )+
550 \)
551 }x
c277df42 552
5a964f20
TC
553which uses C<(?E<gt>...)> matches exactly when the one above does (verifying
554this yourself would be a productive exercise), but finishes in a fourth
555the time when used on a similar string with 1000000 C<a>s. Be aware,
556however, that this pattern currently triggers a warning message under
557B<-w> saying it C<"matches the null string many times">):
c277df42 558
8d300b32 559On simple groups, such as the pattern C<(?E<gt> [^()]+ )>, a comparable
19799a22 560effect may be achieved by negative look-ahead, as in C<[^()]+ (?! [^()] )>.
c277df42
IZ
561This was only 4 times slower on a string with 1000000 C<a>s.
562
5a964f20 563=item C<(?(condition)yes-pattern|no-pattern)>
c277df42 564
5a964f20 565=item C<(?(condition)yes-pattern)>
c277df42 566
19799a22
GS
567B<WARNING>: This extended regular expression feature is considered
568highly experimental, and may be changed or deleted without notice.
569
c277df42
IZ
570Conditional expression. C<(condition)> should be either an integer in
571parentheses (which is valid if the corresponding pair of parentheses
19799a22 572matched), or look-ahead/look-behind/evaluate zero-width assertion.
c277df42 573
19799a22 574For example:
c277df42 575
5a964f20 576 m{ ( \( )?
871b0233 577 [^()]+
5a964f20 578 (?(1) \) )
871b0233 579 }x
c277df42
IZ
580
581matches a chunk of non-parentheses, possibly included in parentheses
582themselves.
a0d0e21e 583
a0d0e21e
LW
584=back
585
c07a80fd
PP
586=head2 Backtracking
587
c277df42 588A fundamental feature of regular expression matching involves the
5a964f20 589notion called I<backtracking>, which is currently used (when needed)
c277df42
IZ
590by all regular expression quantifiers, namely C<*>, C<*?>, C<+>,
591C<+?>, C<{n,m}>, and C<{n,m}?>.
c07a80fd
PP
592
593For a regular expression to match, the I<entire> regular expression must
594match, not just part of it. So if the beginning of a pattern containing a
595quantifier succeeds in a way that causes later parts in the pattern to
596fail, the matching engine backs up and recalculates the beginning
597part--that's why it's called backtracking.
598
599Here is an example of backtracking: Let's say you want to find the
600word following "foo" in the string "Food is on the foo table.":
601
602 $_ = "Food is on the foo table.";
603 if ( /\b(foo)\s+(\w+)/i ) {
604 print "$2 follows $1.\n";
605 }
606
607When the match runs, the first part of the regular expression (C<\b(foo)>)
608finds a possible match right at the beginning of the string, and loads up
609$1 with "Foo". However, as soon as the matching engine sees that there's
610no whitespace following the "Foo" that it had saved in $1, it realizes its
68dc0745 611mistake and starts over again one character after where it had the
c07a80fd
PP
612tentative match. This time it goes all the way until the next occurrence
613of "foo". The complete regular expression matches this time, and you get
614the expected output of "table follows foo."
615
616Sometimes minimal matching can help a lot. Imagine you'd like to match
617everything between "foo" and "bar". Initially, you write something
618like this:
619
620 $_ = "The food is under the bar in the barn.";
621 if ( /foo(.*)bar/ ) {
622 print "got <$1>\n";
623 }
624
625Which perhaps unexpectedly yields:
626
627 got <d is under the bar in the >
628
629That's because C<.*> was greedy, so you get everything between the
14218588 630I<first> "foo" and the I<last> "bar". Here it's more effective
c07a80fd
PP
631to use minimal matching to make sure you get the text between a "foo"
632and the first "bar" thereafter.
633
634 if ( /foo(.*?)bar/ ) { print "got <$1>\n" }
635 got <d is under the >
636
637Here's another example: let's say you'd like to match a number at the end
638of a string, and you also want to keep the preceding part the match.
639So you write this:
640
641 $_ = "I have 2 numbers: 53147";
642 if ( /(.*)(\d*)/ ) { # Wrong!
643 print "Beginning is <$1>, number is <$2>.\n";
644 }
645
646That won't work at all, because C<.*> was greedy and gobbled up the
647whole string. As C<\d*> can match on an empty string the complete
648regular expression matched successfully.
649
8e1088bc 650 Beginning is <I have 2 numbers: 53147>, number is <>.
c07a80fd
PP
651
652Here are some variants, most of which don't work:
653
654 $_ = "I have 2 numbers: 53147";
655 @pats = qw{
656 (.*)(\d*)
657 (.*)(\d+)
658 (.*?)(\d*)
659 (.*?)(\d+)
660 (.*)(\d+)$
661 (.*?)(\d+)$
662 (.*)\b(\d+)$
663 (.*\D)(\d+)$
664 };
665
666 for $pat (@pats) {
667 printf "%-12s ", $pat;
668 if ( /$pat/ ) {
669 print "<$1> <$2>\n";
670 } else {
671 print "FAIL\n";
672 }
673 }
674
675That will print out:
676
677 (.*)(\d*) <I have 2 numbers: 53147> <>
678 (.*)(\d+) <I have 2 numbers: 5314> <7>
679 (.*?)(\d*) <> <>
680 (.*?)(\d+) <I have > <2>
681 (.*)(\d+)$ <I have 2 numbers: 5314> <7>
682 (.*?)(\d+)$ <I have 2 numbers: > <53147>
683 (.*)\b(\d+)$ <I have 2 numbers: > <53147>
684 (.*\D)(\d+)$ <I have 2 numbers: > <53147>
685
686As you see, this can be a bit tricky. It's important to realize that a
687regular expression is merely a set of assertions that gives a definition
688of success. There may be 0, 1, or several different ways that the
689definition might succeed against a particular string. And if there are
5a964f20
TC
690multiple ways it might succeed, you need to understand backtracking to
691know which variety of success you will achieve.
c07a80fd 692
19799a22 693When using look-ahead assertions and negations, this can all get even
54310121 694tricker. Imagine you'd like to find a sequence of non-digits not
c07a80fd
PP
695followed by "123". You might try to write that as
696
871b0233
IZ
697 $_ = "ABC123";
698 if ( /^\D*(?!123)/ ) { # Wrong!
699 print "Yup, no 123 in $_\n";
700 }
c07a80fd
PP
701
702But that isn't going to match; at least, not the way you're hoping. It
703claims that there is no 123 in the string. Here's a clearer picture of
704why it that pattern matches, contrary to popular expectations:
705
706 $x = 'ABC123' ;
707 $y = 'ABC445' ;
708
709 print "1: got $1\n" if $x =~ /^(ABC)(?!123)/ ;
710 print "2: got $1\n" if $y =~ /^(ABC)(?!123)/ ;
711
712 print "3: got $1\n" if $x =~ /^(\D*)(?!123)/ ;
713 print "4: got $1\n" if $y =~ /^(\D*)(?!123)/ ;
714
715This prints
716
717 2: got ABC
718 3: got AB
719 4: got ABC
720
5f05dabc 721You might have expected test 3 to fail because it seems to a more
c07a80fd
PP
722general purpose version of test 1. The important difference between
723them is that test 3 contains a quantifier (C<\D*>) and so can use
724backtracking, whereas test 1 will not. What's happening is
725that you've asked "Is it true that at the start of $x, following 0 or more
5f05dabc 726non-digits, you have something that's not 123?" If the pattern matcher had
c07a80fd 727let C<\D*> expand to "ABC", this would have caused the whole pattern to
54310121 728fail.
14218588 729
c07a80fd 730The search engine will initially match C<\D*> with "ABC". Then it will
14218588 731try to match C<(?!123> with "123", which fails. But because
c07a80fd
PP
732a quantifier (C<\D*>) has been used in the regular expression, the
733search engine can backtrack and retry the match differently
54310121 734in the hope of matching the complete regular expression.
c07a80fd 735
5a964f20
TC
736The pattern really, I<really> wants to succeed, so it uses the
737standard pattern back-off-and-retry and lets C<\D*> expand to just "AB" this
c07a80fd 738time. Now there's indeed something following "AB" that is not
14218588 739"123". It's "C123", which suffices.
c07a80fd 740
14218588
GS
741We can deal with this by using both an assertion and a negation.
742We'll say that the first part in $1 must be followed both by a digit
743and by something that's not "123". Remember that the look-aheads
744are zero-width expressions--they only look, but don't consume any
745of the string in their match. So rewriting this way produces what
c07a80fd
PP
746you'd expect; that is, case 5 will fail, but case 6 succeeds:
747
748 print "5: got $1\n" if $x =~ /^(\D*)(?=\d)(?!123)/ ;
749 print "6: got $1\n" if $y =~ /^(\D*)(?=\d)(?!123)/ ;
750
751 6: got ABC
752
5a964f20 753In other words, the two zero-width assertions next to each other work as though
19799a22 754they're ANDed together, just as you'd use any built-in assertions: C</^$/>
c07a80fd
PP
755matches only if you're at the beginning of the line AND the end of the
756line simultaneously. The deeper underlying truth is that juxtaposition in
757regular expressions always means AND, except when you write an explicit OR
758using the vertical bar. C</ab/> means match "a" AND (then) match "b",
759although the attempted matches are made at different positions because "a"
760is not a zero-width assertion, but a one-width assertion.
761
19799a22 762B<WARNING>: particularly complicated regular expressions can take
14218588 763exponential time to solve because of the immense number of possible
19799a22 764ways they can use backtracking to try match. For example, this will
14218588 765take a painfully long time to run
c07a80fd
PP
766
767 /((a{0,5}){0,5}){0,5}/
768
14218588
GS
769And if you used C<*>'s instead of limiting it to 0 through 5 matches,
770then it would take forever--or until you ran out of stack space.
c07a80fd 771
c277df42 772A powerful tool for optimizing such beasts is "independent" groups,
5a964f20 773which do not backtrace (see L<C<(?E<gt>pattern)>>). Note also that
19799a22 774zero-length look-ahead/look-behind assertions will not backtrace to make
14218588
GS
775the tail match, since they are in "logical" context: only
776whether they match is considered relevant. For an example
19799a22 777where side-effects of a look-ahead I<might> have influenced the
5a964f20 778following match, see L<C<(?E<gt>pattern)>>.
c277df42 779
a0d0e21e
LW
780=head2 Version 8 Regular Expressions
781
5a964f20 782In case you're not familiar with the "regular" Version 8 regex
a0d0e21e
LW
783routines, here are the pattern-matching rules not described above.
784
54310121 785Any single character matches itself, unless it is a I<metacharacter>
a0d0e21e 786with a special meaning described here or above. You can cause
5a964f20 787characters that normally function as metacharacters to be interpreted
5f05dabc 788literally by prefixing them with a "\" (e.g., "\." matches a ".", not any
a0d0e21e
LW
789character; "\\" matches a "\"). A series of characters matches that
790series of characters in the target string, so the pattern C<blurfl>
791would match "blurfl" in the target string.
792
793You can specify a character class, by enclosing a list of characters
5a964f20 794in C<[]>, which will match any one character from the list. If the
a0d0e21e 795first character after the "[" is "^", the class matches any character not
14218588 796in the list. Within a list, the "-" character specifies a
5a964f20 797range, so that C<a-z> represents all characters between "a" and "z",
84850974
DD
798inclusive. If you want "-" itself to be a member of a class, put it
799at the start or end of the list, or escape it with a backslash. (The
800following all specify the same class of three characters: C<[-az]>,
801C<[az-]>, and C<[a\-z]>. All are different from C<[a-z]>, which
802specifies a class containing twenty-six characters.)
a0d0e21e 803
8ada0baa
JH
804Note also that the whole range idea is rather unportable between
805character sets--and even within character sets they may cause results
806you probably didn't expect. A sound principle is to use only ranges
807that begin from and end at either alphabets of equal case ([a-e],
808[A-E]), or digits ([0-9]). Anything else is unsafe. If in doubt,
809spell out the character sets in full.
810
54310121 811Characters may be specified using a metacharacter syntax much like that
a0d0e21e
LW
812used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return,
813"\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string
814of octal digits, matches the character whose ASCII value is I<nnn>.
0f36ee90 815Similarly, \xI<nn>, where I<nn> are hexadecimal digits, matches the
a0d0e21e 816character whose ASCII value is I<nn>. The expression \cI<x> matches the
54310121 817ASCII character control-I<x>. Finally, the "." metacharacter matches any
a0d0e21e
LW
818character except "\n" (unless you use C</s>).
819
820You can specify a series of alternatives for a pattern using "|" to
821separate them, so that C<fee|fie|foe> will match any of "fee", "fie",
5a964f20 822or "foe" in the target string (as would C<f(e|i|o)e>). The
a0d0e21e
LW
823first alternative includes everything from the last pattern delimiter
824("(", "[", or the beginning of the pattern) up to the first "|", and
825the last alternative contains everything from the last "|" to the next
14218588
GS
826pattern delimiter. That's why it's common practice to include
827alternatives in parentheses: to minimize confusion about where they
a3cb178b
GS
828start and end.
829
5a964f20 830Alternatives are tried from left to right, so the first
a3cb178b
GS
831alternative found for which the entire expression matches, is the one that
832is chosen. This means that alternatives are not necessarily greedy. For
628afcb5 833example: when matching C<foo|foot> against "barefoot", only the "foo"
a3cb178b
GS
834part will match, as that is the first alternative tried, and it successfully
835matches the target string. (This might not seem important, but it is
836important when you are capturing matched text using parentheses.)
837
5a964f20 838Also remember that "|" is interpreted as a literal within square brackets,
a3cb178b 839so if you write C<[fee|fie|foe]> you're really only matching C<[feio|]>.
a0d0e21e 840
14218588
GS
841Within a pattern, you may designate subpatterns for later reference
842by enclosing them in parentheses, and you may refer back to the
843I<n>th subpattern later in the pattern using the metacharacter
844\I<n>. Subpatterns are numbered based on the left to right order
845of their opening parenthesis. A backreference matches whatever
846actually matched the subpattern in the string being examined, not
847the rules for that subpattern. Therefore, C<(0|0x)\d*\s\1\d*> will
848match "0x1234 0x4321", but not "0x1234 01234", because subpattern
8491 matched "0x", even though the rule C<0|0x> could potentially match
850the leading 0 in the second number.
cb1a09d0 851
19799a22 852=head2 Warning on \1 vs $1
cb1a09d0 853
5a964f20 854Some people get too used to writing things like:
cb1a09d0
AD
855
856 $pattern =~ s/(\W)/\\\1/g;
857
858This is grandfathered for the RHS of a substitute to avoid shocking the
859B<sed> addicts, but it's a dirty habit to get into. That's because in
5f05dabc 860PerlThink, the righthand side of a C<s///> is a double-quoted string. C<\1> in
cb1a09d0
AD
861the usual double-quoted string means a control-A. The customary Unix
862meaning of C<\1> is kludged in for C<s///>. However, if you get into the habit
863of doing that, you get yourself into trouble if you then add an C</e>
864modifier.
865
5a964f20 866 s/(\d+)/ \1 + 1 /eg; # causes warning under -w
cb1a09d0
AD
867
868Or if you try to do
869
870 s/(\d+)/\1000/;
871
872You can't disambiguate that by saying C<\{1}000>, whereas you can fix it with
14218588 873C<${1}000>. The operation of interpolation should not be confused
cb1a09d0
AD
874with the operation of matching a backreference. Certainly they mean two
875different things on the I<left> side of the C<s///>.
9fa51da4 876
c84d73f1
IZ
877=head2 Repeated patterns matching zero-length substring
878
19799a22 879B<WARNING>: Difficult material (and prose) ahead. This section needs a rewrite.
c84d73f1
IZ
880
881Regular expressions provide a terse and powerful programming language. As
882with most other power tools, power comes together with the ability
883to wreak havoc.
884
885A common abuse of this power stems from the ability to make infinite
628afcb5 886loops using regular expressions, with something as innocuous as:
c84d73f1
IZ
887
888 'foo' =~ m{ ( o? )* }x;
889
890The C<o?> can match at the beginning of C<'foo'>, and since the position
891in the string is not moved by the match, C<o?> would match again and again
14218588 892because of the C<*> modifier. Another common way to create a similar cycle
c84d73f1
IZ
893is with the looping modifier C<//g>:
894
895 @matches = ( 'foo' =~ m{ o? }xg );
896
897or
898
899 print "match: <$&>\n" while 'foo' =~ m{ o? }xg;
900
901or the loop implied by split().
902
903However, long experience has shown that many programming tasks may
14218588
GS
904be significantly simplified by using repeated subexpressions that
905may match zero-length substrings. Here's a simple example being:
c84d73f1
IZ
906
907 @chars = split //, $string; # // is not magic in split
908 ($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /
909
910Thus Perl allows the C</()/> construct, which I<forcefully breaks
911the infinite loop>. The rules for this are different for lower-level
912loops given by the greedy modifiers C<*+{}>, and for higher-level
913ones like the C</g> modifier or split() operator.
914
19799a22
GS
915The lower-level loops are I<interrupted> (that is, the loop is
916broken) when Perl detects that a repeated expression matched a
917zero-length substring. Thus
c84d73f1
IZ
918
919 m{ (?: NON_ZERO_LENGTH | ZERO_LENGTH )* }x;
920
921is made equivalent to
922
923 m{ (?: NON_ZERO_LENGTH )*
924 |
925 (?: ZERO_LENGTH )?
926 }x;
927
928The higher level-loops preserve an additional state between iterations:
929whether the last match was zero-length. To break the loop, the following
930match after a zero-length match is prohibited to have a length of zero.
931This prohibition interacts with backtracking (see L<"Backtracking">),
932and so the I<second best> match is chosen if the I<best> match is of
933zero length.
934
19799a22 935For example:
c84d73f1
IZ
936
937 $_ = 'bar';
938 s/\w??/<$&>/g;
939
940results in C<"<><b><><a><><r><>">. At each position of the string the best
941match given by non-greedy C<??> is the zero-length match, and the I<second
942best> match is what is matched by C<\w>. Thus zero-length matches
943alternate with one-character-long matches.
944
945Similarly, for repeated C<m/()/g> the second-best match is the match at the
946position one notch further in the string.
947
19799a22 948The additional state of being I<matched with zero-length> is associated with
c84d73f1
IZ
949the matched string, and is reset by each assignment to pos().
950
951=head2 Creating custom RE engines
952
953Overloaded constants (see L<overload>) provide a simple way to extend
954the functionality of the RE engine.
955
956Suppose that we want to enable a new RE escape-sequence C<\Y|> which
957matches at boundary between white-space characters and non-whitespace
958characters. Note that C<(?=\S)(?<!\S)|(?!\S)(?<=\S)> matches exactly
959at these positions, so we want to have each C<\Y|> in the place of the
960more complicated version. We can create a module C<customre> to do
961this:
962
963 package customre;
964 use overload;
965
966 sub import {
967 shift;
968 die "No argument to customre::import allowed" if @_;
969 overload::constant 'qr' => \&convert;
970 }
971
972 sub invalid { die "/$_[0]/: invalid escape '\\$_[1]'"}
973
974 my %rules = ( '\\' => '\\',
975 'Y|' => qr/(?=\S)(?<!\S)|(?!\S)(?<=\S)/ );
976 sub convert {
977 my $re = shift;
978 $re =~ s{
979 \\ ( \\ | Y . )
980 }
981 { $rules{$1} or invalid($re,$1) }sgex;
982 return $re;
983 }
984
985Now C<use customre> enables the new escape in constant regular
986expressions, i.e., those without any runtime variable interpolations.
987As documented in L<overload>, this conversion will work only over
988literal parts of regular expressions. For C<\Y|$re\Y|> the variable
989part of this regular expression needs to be converted explicitly
990(but only if the special meaning of C<\Y|> should be enabled inside $re):
991
992 use customre;
993 $re = <>;
994 chomp $re;
995 $re = customre::convert $re;
996 /\Y|$re\Y|/;
997
19799a22
GS
998=head1 BUGS
999
1000This manpage is varies from difficult to understand to completely
1001and utterly opaque.
1002
1003=head1 SEE ALSO
9fa51da4 1004
9b599b2a
GS
1005L<perlop/"Regexp Quote-Like Operators">.
1006
1e66bd83
PP
1007L<perlop/"Gory details of parsing quoted constructs">.
1008
14218588
GS
1009L<perlfaq6>.
1010
9b599b2a
GS
1011L<perlfunc/pos>.
1012
1013L<perllocale>.
1014
14218588
GS
1015I<Mastering Regular Expressions> by Jeffrey Friedl, published
1016by O'Reilly and Associates.