This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
final touches to 5.004_68
[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
75e14d17
IZ
9operations, plus various examples of the same, see discussion
10of C<m//>, C<s///>, and C<??> in L<perlop/Regexp Quote-Like Operators>.
cb1a09d0 11
68dc0745 12The matching operations can have various modifiers. The modifiers
5a964f20 13that relate to the interpretation of the regular expression inside
75e14d17
IZ
14are listed below. For the modifiers that alter the way regular expression
15is used by Perl, see L<perlop/Regexp Quote-Like Operators>.
a0d0e21e 16
55497cff
PP
17=over 4
18
19=item i
20
21Do case-insensitive pattern matching.
22
a034a98d
DD
23If C<use locale> is in effect, the case map is taken from the current
24locale. See L<perllocale>.
25
54310121 26=item m
55497cff
PP
27
28Treat string as multiple lines. That is, change "^" and "$" from matching
5f05dabc 29at only the very start or end of the string to the start or end of any
55497cff
PP
30line anywhere within the string,
31
54310121 32=item s
55497cff
PP
33
34Treat string as single line. That is, change "." to match any character
35whatsoever, even a newline, which it normally would not match.
36
5a964f20
TC
37The C</s> and C</m> modifiers both override the C<$*> setting. That is, no matter
38what C<$*> contains, C</s> without C</m> will force "^" to match only at the
7b8d334a
GS
39beginning of the string and "$" to match only at the end (or just before a
40newline at the end) of the string. Together, as /ms, they let the "." match
41any character whatsoever, while yet allowing "^" and "$" to match,
42respectively, just after and just before newlines within the string.
43
54310121 44=item x
55497cff
PP
45
46Extend your pattern's legibility by permitting whitespace and comments.
47
48=back
a0d0e21e
LW
49
50These are usually written as "the C</x> modifier", even though the delimiter
51in question might not actually be a slash. In fact, any of these
52modifiers may also be embedded within the regular expression itself using
53the new C<(?...)> construct. See below.
54
4633a7c4 55The C</x> modifier itself needs a little more explanation. It tells
55497cff
PP
56the regular expression parser to ignore whitespace that is neither
57backslashed nor within a character class. You can use this to break up
4633a7c4 58your regular expression into (slightly) more readable parts. The C<#>
54310121 59character is also treated as a metacharacter introducing a comment,
55497cff 60just as in ordinary Perl code. This also means that if you want real
5a964f20
TC
61whitespace or C<#> characters in the pattern (outside of a character
62class, where they are unaffected by C</x>), that you'll either have to
55497cff
PP
63escape them or encode them using octal or hex escapes. Taken together,
64these features go a long way towards making Perl's regular expressions
0c815be9
HS
65more readable. Note that you have to be careful not to include the
66pattern delimiter in the comment--perl has no way of knowing you did
5a964f20 67not intend to close the pattern early. See the C-comment deletion code
0c815be9 68in L<perlop>.
a0d0e21e
LW
69
70=head2 Regular Expressions
71
72The patterns used in pattern matching are regular expressions such as
5a964f20 73those supplied in the Version 8 regex routines. (In fact, the
a0d0e21e
LW
74routines are derived (distantly) from Henry Spencer's freely
75redistributable reimplementation of the V8 routines.)
76See L<Version 8 Regular Expressions> for details.
77
78In particular the following metacharacters have their standard I<egrep>-ish
79meanings:
80
54310121 81 \ Quote the next metacharacter
a0d0e21e
LW
82 ^ Match the beginning of the line
83 . Match any character (except newline)
c07a80fd 84 $ Match the end of the line (or before newline at the end)
a0d0e21e
LW
85 | Alternation
86 () Grouping
87 [] Character class
88
5f05dabc
PP
89By default, the "^" character is guaranteed to match at only the
90beginning of the string, the "$" character at only the end (or before the
a0d0e21e
LW
91newline at the end) and Perl does certain optimizations with the
92assumption that the string contains only one line. Embedded newlines
93will not be matched by "^" or "$". You may, however, wish to treat a
4a6725af 94string as a multi-line buffer, such that the "^" will match after any
a0d0e21e
LW
95newline within the string, and "$" will match before any newline. At the
96cost of a little more overhead, you can do this by using the /m modifier
97on the pattern match operator. (Older programs did this by setting C<$*>,
5f05dabc 98but this practice is now deprecated.)
a0d0e21e 99
4a6725af 100To facilitate multi-line substitutions, the "." character never matches a
55497cff 101newline unless you use the C</s> modifier, which in effect tells Perl to pretend
a0d0e21e
LW
102the string is a single line--even if it isn't. The C</s> modifier also
103overrides the setting of C<$*>, in case you have some (badly behaved) older
104code that sets it in another module.
105
106The following standard quantifiers are recognized:
107
108 * Match 0 or more times
109 + Match 1 or more times
110 ? Match 1 or 0 times
111 {n} Match exactly n times
112 {n,} Match at least n times
113 {n,m} Match at least n but not more than m times
114
115(If a curly bracket occurs in any other context, it is treated
116as a regular character.) The "*" modifier is equivalent to C<{0,}>, the "+"
25f94b33 117modifier to C<{1,}>, and the "?" modifier to C<{0,1}>. n and m are limited
c07a80fd 118to integral values less than 65536.
a0d0e21e 119
54310121
PP
120By default, a quantified subpattern is "greedy", that is, it will match as
121many times as possible (given a particular starting location) while still
122allowing the rest of the pattern to match. If you want it to match the
123minimum number of times possible, follow the quantifier with a "?". Note
124that the meanings don't change, just the "greediness":
a0d0e21e
LW
125
126 *? Match 0 or more times
127 +? Match 1 or more times
128 ?? Match 0 or 1 time
129 {n}? Match exactly n times
130 {n,}? Match at least n times
131 {n,m}? Match at least n but not more than m times
132
5f05dabc 133Because patterns are processed as double quoted strings, the following
a0d0e21e
LW
134also work:
135
0f36ee90
PP
136 \t tab (HT, TAB)
137 \n newline (LF, NL)
138 \r return (CR)
139 \f form feed (FF)
140 \a alarm (bell) (BEL)
141 \e escape (think troff) (ESC)
cb1a09d0
AD
142 \033 octal char (think of a PDP-11)
143 \x1B hex char
a0d0e21e 144 \c[ control char
cb1a09d0
AD
145 \l lowercase next char (think vi)
146 \u uppercase next char (think vi)
147 \L lowercase till \E (think vi)
148 \U uppercase till \E (think vi)
149 \E end case modification (think vi)
5a964f20 150 \Q quote (disable) pattern metacharacters till \E
a0d0e21e 151
a034a98d 152If C<use locale> is in effect, the case map used by C<\l>, C<\L>, C<\u>
7b8d334a 153and C<\U> is taken from the current locale. See L<perllocale>.
a034a98d 154
1d2dff63
GS
155You cannot include a literal C<$> or C<@> within a C<\Q> sequence.
156An unescaped C<$> or C<@> interpolates the corresponding variable,
157while escaping will cause the literal string C<\$> to be matched.
158You'll need to write something like C<m/\Quser\E\@\Qhost/>.
159
a0d0e21e
LW
160In addition, Perl defines the following:
161
162 \w Match a "word" character (alphanumeric plus "_")
163 \W Match a non-word character
164 \s Match a whitespace character
165 \S Match a non-whitespace character
166 \d Match a digit character
167 \D Match a non-digit character
168
5a964f20 169A C<\w> matches a single alphanumeric character, not a whole
a034a98d
DD
170word. To match a word you'd need to say C<\w+>. If C<use locale> is in
171effect, the list of alphabetic characters generated by C<\w> is taken
172from the current locale. See L<perllocale>. You may use C<\w>, C<\W>,
173C<\s>, C<\S>, C<\d>, and C<\D> within character classes (though not as
174either end of a range).
a0d0e21e
LW
175
176Perl defines the following zero-width assertions:
177
178 \b Match a word boundary
179 \B Match a non-(word boundary)
5f05dabc
PP
180 \A Match at only beginning of string
181 \Z Match at only end of string (or before newline at the end)
a99df21c 182 \G Match only where previous m//g left off (works only with /g)
a0d0e21e
LW
183
184A word boundary (C<\b>) is defined as a spot between two characters that
68dc0745 185has a C<\w> on one side of it and a C<\W> on the other side of it (in
a0d0e21e
LW
186either order), counting the imaginary characters off the beginning and
187end of the string as matching a C<\W>. (Within character classes C<\b>
188represents backspace rather than a word boundary.) The C<\A> and C<\Z> are
5a964f20 189just like "^" and "$", except that they won't match multiple times when the
a0d0e21e 190C</m> modifier is used, while "^" and "$" will match at every internal line
c07a80fd 191boundary. To match the actual end of the string, not ignoring newline,
a99df21c
GS
192you can use C<\Z(?!\n)>. The C<\G> assertion can be used to chain global
193matches (using C<m//g>), as described in
e7ea3e70 194L<perlop/"Regexp Quote-Like Operators">.
a99df21c 195
e7ea3e70 196It is also useful when writing C<lex>-like scanners, when you have several
5a964f20 197patterns that you want to match against consequent substrings of your
e7ea3e70 198string, see the previous reference.
44a8e56a
PP
199The actual location where C<\G> will match can also be influenced
200by using C<pos()> as an lvalue. See L<perlfunc/pos>.
a0d0e21e 201
0f36ee90 202When the bracketing construct C<( ... )> is used, \E<lt>digitE<gt> matches the
cb1a09d0 203digit'th substring. Outside of the pattern, always use "$" instead of "\"
0f36ee90 204in front of the digit. (While the \E<lt>digitE<gt> notation can on rare occasion work
cb1a09d0 205outside the current pattern, this should not be relied upon. See the
0f36ee90 206WARNING below.) The scope of $E<lt>digitE<gt> (and C<$`>, C<$&>, and C<$'>)
cb1a09d0
AD
207extends to the end of the enclosing BLOCK or eval string, or to the next
208successful pattern match, whichever comes first. If you want to use
5f05dabc 209parentheses to delimit a subpattern (e.g., a set of alternatives) without
84dc3c4d 210saving it as a subpattern, follow the ( with a ?:.
cb1a09d0
AD
211
212You may have as many parentheses as you wish. If you have more
a0d0e21e
LW
213than 9 substrings, the variables $10, $11, ... refer to the
214corresponding substring. Within the pattern, \10, \11, etc. refer back
5f05dabc 215to substrings if there have been at least that many left parentheses before
c07a80fd 216the backreference. Otherwise (for backward compatibility) \10 is the
a0d0e21e
LW
217same as \010, a backspace, and \11 the same as \011, a tab. And so
218on. (\1 through \9 are always backreferences.)
219
220C<$+> returns whatever the last bracket match matched. C<$&> returns the
0f36ee90 221entire matched string. (C<$0> used to return the same thing, but not any
a0d0e21e
LW
222more.) C<$`> returns everything before the matched string. C<$'> returns
223everything after the matched string. Examples:
224
225 s/^([^ ]*) *([^ ]*)/$2 $1/; # swap first two words
226
227 if (/Time: (..):(..):(..)/) {
228 $hours = $1;
229 $minutes = $2;
230 $seconds = $3;
231 }
232
68dc0745
PP
233Once perl sees that you need one of C<$&>, C<$`> or C<$'> anywhere in
234the program, it has to provide them on each and every pattern match.
235This can slow your program down. The same mechanism that handles
236these provides for the use of $1, $2, etc., so you pay the same price
5a964f20
TC
237for each pattern that contains capturing parentheses. But if you never
238use $&, etc., in your script, then patterns I<without> capturing
68dc0745
PP
239parentheses won't be penalized. So avoid $&, $', and $` if you can,
240but if you can't (and some algorithms really appreciate them), once
241you've used them once, use them at will, because you've already paid
5a964f20 242the price. As of 5.005, $& is not so costly as the other two.
68dc0745 243
5a964f20 244Backslashed metacharacters in Perl are
201ecf35
AL
245alphanumeric, such as C<\b>, C<\w>, C<\n>. Unlike some other regular
246expression languages, there are no backslashed symbols that aren't
247alphanumeric. So anything that looks like \\, \(, \), \E<lt>, \E<gt>,
248\{, or \} is always interpreted as a literal character, not a
249metacharacter. This was once used in a common idiom to disable or
250quote the special meanings of regular expression metacharacters in a
5a964f20 251string that you want to use for a pattern. Simply quote all
a0d0e21e
LW
252non-alphanumeric characters:
253
254 $pattern =~ s/(\W)/\\$1/g;
255
201ecf35 256Now it is much more common to see either the quotemeta() function or
7b8d334a 257the C<\Q> escape sequence used to disable all metacharacters' special
201ecf35 258meanings like this:
a0d0e21e
LW
259
260 /$unquoted\Q$quoted\E$unquoted/
261
5f05dabc
PP
262Perl defines a consistent extension syntax for regular expressions.
263The syntax is a pair of parentheses with a question mark as the first
264thing within the parentheses (this was a syntax error in older
265versions of Perl). The character after the question mark gives the
266function of the extension. Several extensions are already supported:
a0d0e21e
LW
267
268=over 10
269
cc6b7395 270=item C<(?#text)>
a0d0e21e 271
cb1a09d0 272A comment. The text is ignored. If the C</x> switch is used to enable
259138e3
GS
273whitespace formatting, a simple C<#> will suffice. Note that perl closes
274the comment as soon as it sees a C<)>, so there is no way to put a literal
275C<)> in the comment.
a0d0e21e 276
5a964f20 277=item C<(?:pattern)>
a0d0e21e 278
5a964f20
TC
279This is for clustering, not capturing; it groups subexpressions like
280"()", but doesn't make backreferences as "()" does. So
a0d0e21e 281
5a964f20 282 @fields = split(/\b(?:a|b|c)\b/)
a0d0e21e
LW
283
284is like
285
5a964f20 286 @fields = split(/\b(a|b|c)\b/)
a0d0e21e
LW
287
288but doesn't spit out extra fields.
289
5a964f20 290=item C<(?=pattern)>
a0d0e21e
LW
291
292A zero-width positive lookahead assertion. For example, C</\w+(?=\t)/>
293matches a word followed by a tab, without including the tab in C<$&>.
294
5a964f20 295=item C<(?!pattern)>
a0d0e21e
LW
296
297A zero-width negative lookahead assertion. For example C</foo(?!bar)/>
298matches any occurrence of "foo" that isn't followed by "bar". Note
299however that lookahead and lookbehind are NOT the same thing. You cannot
7b8d334a
GS
300use this for lookbehind.
301
5a964f20 302If you are looking for a "bar" that isn't preceded by a "foo", C</(?!foo)bar/>
7b8d334a
GS
303will not do what you want. That's because the C<(?!foo)> is just saying that
304the next thing cannot be "foo"--and it's not, it's a "bar", so "foobar" will
305match. You would have to do something like C</(?!foo)...bar/> for that. We
306say "like" because there's the case of your "bar" not having three characters
307before it. You could cover that this way: C</(?:(?!foo)...|^.{0,2})bar/>.
308Sometimes it's still easier just to say:
a0d0e21e 309
a3cb178b 310 if (/bar/ && $` !~ /foo$/)
a0d0e21e 311
c277df42
IZ
312For lookbehind see below.
313
5a964f20 314=item C<(?E<lt>=pattern)>
c277df42 315
5a964f20 316A zero-width positive lookbehind assertion. For example, C</(?E<lt>=\t)\w+/>
c277df42
IZ
317matches a word following a tab, without including the tab in C<$&>.
318Works only for fixed-width lookbehind.
319
5a964f20 320=item C<(?<!pattern)>
c277df42
IZ
321
322A zero-width negative lookbehind assertion. For example C</(?<!bar)foo/>
323matches any occurrence of "foo" that isn't following "bar".
324Works only for fixed-width lookbehind.
325
cc6b7395 326=item C<(?{ code })>
c277df42
IZ
327
328Experimental "evaluate any Perl code" zero-width assertion. Always
cc6b7395
IZ
329succeeds. C<code> is not interpolated. Currently the rules to
330determine where the C<code> ends are somewhat convoluted.
c277df42 331
5a964f20
TC
332B<WARNING>: This is a grave security risk for arbitrarily interpolated
333patterns. It introduces security holes in previously safe programs.
334A fix to Perl, and to this documentation, will be forthcoming prior
335to the actual 5.005 release.
c277df42 336
5a964f20
TC
337=item C<(?E<gt>pattern)>
338
339An "independent" subexpression. Matches the substring that a
340I<standalone> C<pattern> would match if anchored at the given position,
c277df42
IZ
341B<and only this substring>.
342
343Say, C<^(?E<gt>a*)ab> will never match, since C<(?E<gt>a*)> (anchored
5a964f20 344at the beginning of string, as above) will match I<all> characters
c277df42
IZ
345C<a> at the beginning of string, leaving no C<a> for C<ab> to match.
346In contrast, C<a*ab> will match the same as C<a+b>, since the match of
347the subgroup C<a*> is influenced by the following group C<ab> (see
348L<"Backtracking">). In particular, C<a*> inside C<a*ab> will match
349less characters that a standalone C<a*>, since this makes the tail match.
350
5a964f20 351An effect similar to C<(?E<gt>pattern)> may be achieved by
c277df42 352
5a964f20 353 (?=(pattern))\1
c277df42
IZ
354
355since the lookahead is in I<"logical"> context, thus matches the same
356substring as a standalone C<a+>. The following C<\1> eats the matched
357string, thus making a zero-length assertion into an analogue of
5a964f20
TC
358C<(?>...)>. (The difference between these two constructs is that the
359second one uses a catching group, thus shifting ordinals of
c277df42
IZ
360backreferences in the rest of a regular expression.)
361
5a964f20
TC
362This construct is useful for optimizations of "eternal"
363matches, because it will not backtrack (see L<"Backtracking">).
c277df42 364
5a964f20 365 m{ \( (
c277df42
IZ
366 [^()]+
367 |
368 \( [^()]* \)
369 )+
5a964f20
TC
370 \)
371 }x
372
373That will efficiently match a nonempty group with matching
374two-or-less-level-deep parentheses. However, if there is no such group,
375it will take virtually forever on a long string. That's because there are
376so many different ways to split a long string into several substrings.
377This is essentially what C<(.+)+> is doing, and this is a subpattern
378of the above pattern. Consider that C<((()aaaaaaaaaaaaaaaaaa> on the
379pattern above detects no-match in several seconds, but that each extra
380letter doubles this time. This exponential performance will make it
381appear that your program has hung.
382
383However, a tiny modification of this pattern
384
385 m{ \( (
c277df42
IZ
386 (?> [^()]+ )
387 |
388 \( [^()]* \)
389 )+
5a964f20
TC
390 \)
391 }x
c277df42 392
5a964f20
TC
393which uses C<(?E<gt>...)> matches exactly when the one above does (verifying
394this yourself would be a productive exercise), but finishes in a fourth
395the time when used on a similar string with 1000000 C<a>s. Be aware,
396however, that this pattern currently triggers a warning message under
397B<-w> saying it C<"matches the null string many times">):
c277df42 398
5a964f20 399On simple groups, such as the pattern C<(?> [^()]+ )>, a comparable
c277df42
IZ
400effect may be achieved by negative lookahead, as in C<[^()]+ (?! [^()] )>.
401This was only 4 times slower on a string with 1000000 C<a>s.
402
5a964f20 403=item C<(?(condition)yes-pattern|no-pattern)>
c277df42 404
5a964f20 405=item C<(?(condition)yes-pattern)>
c277df42
IZ
406
407Conditional expression. C<(condition)> should be either an integer in
408parentheses (which is valid if the corresponding pair of parentheses
409matched), or lookahead/lookbehind/evaluate zero-width assertion.
410
411Say,
412
5a964f20 413 m{ ( \( )?
c277df42 414 [^()]+
5a964f20
TC
415 (?(1) \) )
416 }x
c277df42
IZ
417
418matches a chunk of non-parentheses, possibly included in parentheses
419themselves.
a0d0e21e 420
5a964f20 421=item C<(?imsx)>
a0d0e21e
LW
422
423One or more embedded pattern-match modifiers. This is particularly
424useful for patterns that are specified in a table somewhere, some of
425which want to be case sensitive, and some of which don't. The case
5f05dabc 426insensitive ones need to include merely C<(?i)> at the front of the
a0d0e21e
LW
427pattern. For example:
428
429 $pattern = "foobar";
5a964f20 430 if ( /$pattern/i ) { }
a0d0e21e
LW
431
432 # more flexible:
433
434 $pattern = "(?i)foobar";
5a964f20 435 if ( /$pattern/ ) { }
a0d0e21e 436
5a964f20 437These modifiers are localized inside an enclosing group (if any). Say,
c277df42
IZ
438
439 ( (?i) blah ) \s+ \1
440
441(assuming C<x> modifier, and no C<i> modifier outside of this group)
442will match a repeated (I<including the case>!) word C<blah> in any
443case.
444
a0d0e21e
LW
445=back
446
5a964f20
TC
447A question mark was chosen for this and for the new minimal-matching
448construct because 1) question mark is pretty rare in older regular
449expressions, and 2) whenever you see one, you should stop and "question"
450exactly what is going on. That's psychology...
a0d0e21e 451
c07a80fd
PP
452=head2 Backtracking
453
c277df42 454A fundamental feature of regular expression matching involves the
5a964f20 455notion called I<backtracking>, which is currently used (when needed)
c277df42
IZ
456by all regular expression quantifiers, namely C<*>, C<*?>, C<+>,
457C<+?>, C<{n,m}>, and C<{n,m}?>.
c07a80fd
PP
458
459For a regular expression to match, the I<entire> regular expression must
460match, not just part of it. So if the beginning of a pattern containing a
461quantifier succeeds in a way that causes later parts in the pattern to
462fail, the matching engine backs up and recalculates the beginning
463part--that's why it's called backtracking.
464
465Here is an example of backtracking: Let's say you want to find the
466word following "foo" in the string "Food is on the foo table.":
467
468 $_ = "Food is on the foo table.";
469 if ( /\b(foo)\s+(\w+)/i ) {
470 print "$2 follows $1.\n";
471 }
472
473When the match runs, the first part of the regular expression (C<\b(foo)>)
474finds a possible match right at the beginning of the string, and loads up
475$1 with "Foo". However, as soon as the matching engine sees that there's
476no whitespace following the "Foo" that it had saved in $1, it realizes its
68dc0745 477mistake and starts over again one character after where it had the
c07a80fd
PP
478tentative match. This time it goes all the way until the next occurrence
479of "foo". The complete regular expression matches this time, and you get
480the expected output of "table follows foo."
481
482Sometimes minimal matching can help a lot. Imagine you'd like to match
483everything between "foo" and "bar". Initially, you write something
484like this:
485
486 $_ = "The food is under the bar in the barn.";
487 if ( /foo(.*)bar/ ) {
488 print "got <$1>\n";
489 }
490
491Which perhaps unexpectedly yields:
492
493 got <d is under the bar in the >
494
495That's because C<.*> was greedy, so you get everything between the
496I<first> "foo" and the I<last> "bar". In this case, it's more effective
497to use minimal matching to make sure you get the text between a "foo"
498and the first "bar" thereafter.
499
500 if ( /foo(.*?)bar/ ) { print "got <$1>\n" }
501 got <d is under the >
502
503Here's another example: let's say you'd like to match a number at the end
504of a string, and you also want to keep the preceding part the match.
505So you write this:
506
507 $_ = "I have 2 numbers: 53147";
508 if ( /(.*)(\d*)/ ) { # Wrong!
509 print "Beginning is <$1>, number is <$2>.\n";
510 }
511
512That won't work at all, because C<.*> was greedy and gobbled up the
513whole string. As C<\d*> can match on an empty string the complete
514regular expression matched successfully.
515
8e1088bc 516 Beginning is <I have 2 numbers: 53147>, number is <>.
c07a80fd
PP
517
518Here are some variants, most of which don't work:
519
520 $_ = "I have 2 numbers: 53147";
521 @pats = qw{
522 (.*)(\d*)
523 (.*)(\d+)
524 (.*?)(\d*)
525 (.*?)(\d+)
526 (.*)(\d+)$
527 (.*?)(\d+)$
528 (.*)\b(\d+)$
529 (.*\D)(\d+)$
530 };
531
532 for $pat (@pats) {
533 printf "%-12s ", $pat;
534 if ( /$pat/ ) {
535 print "<$1> <$2>\n";
536 } else {
537 print "FAIL\n";
538 }
539 }
540
541That will print out:
542
543 (.*)(\d*) <I have 2 numbers: 53147> <>
544 (.*)(\d+) <I have 2 numbers: 5314> <7>
545 (.*?)(\d*) <> <>
546 (.*?)(\d+) <I have > <2>
547 (.*)(\d+)$ <I have 2 numbers: 5314> <7>
548 (.*?)(\d+)$ <I have 2 numbers: > <53147>
549 (.*)\b(\d+)$ <I have 2 numbers: > <53147>
550 (.*\D)(\d+)$ <I have 2 numbers: > <53147>
551
552As you see, this can be a bit tricky. It's important to realize that a
553regular expression is merely a set of assertions that gives a definition
554of success. There may be 0, 1, or several different ways that the
555definition might succeed against a particular string. And if there are
5a964f20
TC
556multiple ways it might succeed, you need to understand backtracking to
557know which variety of success you will achieve.
c07a80fd
PP
558
559When using lookahead assertions and negations, this can all get even
54310121 560tricker. Imagine you'd like to find a sequence of non-digits not
c07a80fd
PP
561followed by "123". You might try to write that as
562
563 $_ = "ABC123";
564 if ( /^\D*(?!123)/ ) { # Wrong!
565 print "Yup, no 123 in $_\n";
566 }
567
568But that isn't going to match; at least, not the way you're hoping. It
569claims that there is no 123 in the string. Here's a clearer picture of
570why it that pattern matches, contrary to popular expectations:
571
572 $x = 'ABC123' ;
573 $y = 'ABC445' ;
574
575 print "1: got $1\n" if $x =~ /^(ABC)(?!123)/ ;
576 print "2: got $1\n" if $y =~ /^(ABC)(?!123)/ ;
577
578 print "3: got $1\n" if $x =~ /^(\D*)(?!123)/ ;
579 print "4: got $1\n" if $y =~ /^(\D*)(?!123)/ ;
580
581This prints
582
583 2: got ABC
584 3: got AB
585 4: got ABC
586
5f05dabc 587You might have expected test 3 to fail because it seems to a more
c07a80fd
PP
588general purpose version of test 1. The important difference between
589them is that test 3 contains a quantifier (C<\D*>) and so can use
590backtracking, whereas test 1 will not. What's happening is
591that you've asked "Is it true that at the start of $x, following 0 or more
5f05dabc 592non-digits, you have something that's not 123?" If the pattern matcher had
c07a80fd 593let C<\D*> expand to "ABC", this would have caused the whole pattern to
54310121 594fail.
c07a80fd 595The search engine will initially match C<\D*> with "ABC". Then it will
5a964f20 596try to match C<(?!123> with "123", which of course fails. But because
c07a80fd
PP
597a quantifier (C<\D*>) has been used in the regular expression, the
598search engine can backtrack and retry the match differently
54310121 599in the hope of matching the complete regular expression.
c07a80fd 600
5a964f20
TC
601The pattern really, I<really> wants to succeed, so it uses the
602standard pattern back-off-and-retry and lets C<\D*> expand to just "AB" this
c07a80fd
PP
603time. Now there's indeed something following "AB" that is not
604"123". It's in fact "C123", which suffices.
605
606We can deal with this by using both an assertion and a negation. We'll
607say that the first part in $1 must be followed by a digit, and in fact, it
608must also be followed by something that's not "123". Remember that the
609lookaheads are zero-width expressions--they only look, but don't consume
610any of the string in their match. So rewriting this way produces what
611you'd expect; that is, case 5 will fail, but case 6 succeeds:
612
613 print "5: got $1\n" if $x =~ /^(\D*)(?=\d)(?!123)/ ;
614 print "6: got $1\n" if $y =~ /^(\D*)(?=\d)(?!123)/ ;
615
616 6: got ABC
617
5a964f20 618In other words, the two zero-width assertions next to each other work as though
c07a80fd
PP
619they're ANDed together, just as you'd use any builtin assertions: C</^$/>
620matches only if you're at the beginning of the line AND the end of the
621line simultaneously. The deeper underlying truth is that juxtaposition in
622regular expressions always means AND, except when you write an explicit OR
623using the vertical bar. C</ab/> means match "a" AND (then) match "b",
624although the attempted matches are made at different positions because "a"
625is not a zero-width assertion, but a one-width assertion.
626
627One warning: particularly complicated regular expressions can take
628exponential time to solve due to the immense number of possible ways they
629can use backtracking to try match. For example this will take a very long
630time to run
631
632 /((a{0,5}){0,5}){0,5}/
633
634And if you used C<*>'s instead of limiting it to 0 through 5 matches, then
635it would take literally forever--or until you ran out of stack space.
636
c277df42 637A powerful tool for optimizing such beasts is "independent" groups,
5a964f20 638which do not backtrace (see L<C<(?E<gt>pattern)>>). Note also that
c277df42
IZ
639zero-length lookahead/lookbehind assertions will not backtrace to make
640the tail match, since they are in "logical" context: only the fact
641whether they match or not is considered relevant. For an example
642where side-effects of a lookahead I<might> have influenced the
5a964f20 643following match, see L<C<(?E<gt>pattern)>>.
c277df42 644
a0d0e21e
LW
645=head2 Version 8 Regular Expressions
646
5a964f20 647In case you're not familiar with the "regular" Version 8 regex
a0d0e21e
LW
648routines, here are the pattern-matching rules not described above.
649
54310121 650Any single character matches itself, unless it is a I<metacharacter>
a0d0e21e 651with a special meaning described here or above. You can cause
5a964f20 652characters that normally function as metacharacters to be interpreted
5f05dabc 653literally by prefixing them with a "\" (e.g., "\." matches a ".", not any
a0d0e21e
LW
654character; "\\" matches a "\"). A series of characters matches that
655series of characters in the target string, so the pattern C<blurfl>
656would match "blurfl" in the target string.
657
658You can specify a character class, by enclosing a list of characters
5a964f20 659in C<[]>, which will match any one character from the list. If the
a0d0e21e
LW
660first character after the "[" is "^", the class matches any character not
661in the list. Within a list, the "-" character is used to specify a
5a964f20 662range, so that C<a-z> represents all characters between "a" and "z",
84850974
DD
663inclusive. If you want "-" itself to be a member of a class, put it
664at the start or end of the list, or escape it with a backslash. (The
665following all specify the same class of three characters: C<[-az]>,
666C<[az-]>, and C<[a\-z]>. All are different from C<[a-z]>, which
667specifies a class containing twenty-six characters.)
a0d0e21e 668
54310121 669Characters may be specified using a metacharacter syntax much like that
a0d0e21e
LW
670used in C: "\n" matches a newline, "\t" a tab, "\r" a carriage return,
671"\f" a form feed, etc. More generally, \I<nnn>, where I<nnn> is a string
672of octal digits, matches the character whose ASCII value is I<nnn>.
0f36ee90 673Similarly, \xI<nn>, where I<nn> are hexadecimal digits, matches the
a0d0e21e 674character whose ASCII value is I<nn>. The expression \cI<x> matches the
54310121 675ASCII character control-I<x>. Finally, the "." metacharacter matches any
a0d0e21e
LW
676character except "\n" (unless you use C</s>).
677
678You can specify a series of alternatives for a pattern using "|" to
679separate them, so that C<fee|fie|foe> will match any of "fee", "fie",
5a964f20 680or "foe" in the target string (as would C<f(e|i|o)e>). The
a0d0e21e
LW
681first alternative includes everything from the last pattern delimiter
682("(", "[", or the beginning of the pattern) up to the first "|", and
683the last alternative contains everything from the last "|" to the next
684pattern delimiter. For this reason, it's common practice to include
685alternatives in parentheses, to minimize confusion about where they
a3cb178b
GS
686start and end.
687
5a964f20 688Alternatives are tried from left to right, so the first
a3cb178b
GS
689alternative found for which the entire expression matches, is the one that
690is chosen. This means that alternatives are not necessarily greedy. For
691example: when mathing C<foo|foot> against "barefoot", only the "foo"
692part will match, as that is the first alternative tried, and it successfully
693matches the target string. (This might not seem important, but it is
694important when you are capturing matched text using parentheses.)
695
5a964f20 696Also remember that "|" is interpreted as a literal within square brackets,
a3cb178b 697so if you write C<[fee|fie|foe]> you're really only matching C<[feio|]>.
a0d0e21e 698
54310121 699Within a pattern, you may designate subpatterns for later reference by
a0d0e21e 700enclosing them in parentheses, and you may refer back to the I<n>th
54310121
PP
701subpattern later in the pattern using the metacharacter \I<n>.
702Subpatterns are numbered based on the left to right order of their
5a964f20 703opening parenthesis. A backreference matches whatever
54310121
PP
704actually matched the subpattern in the string being examined, not the
705rules for that subpattern. Therefore, C<(0|0x)\d*\s\1\d*> will
5a964f20 706match "0x1234 0x4321", but not "0x1234 01234", because subpattern 1
748a9306 707actually matched "0x", even though the rule C<0|0x> could
a0d0e21e 708potentially match the leading 0 in the second number.
cb1a09d0
AD
709
710=head2 WARNING on \1 vs $1
711
5a964f20 712Some people get too used to writing things like:
cb1a09d0
AD
713
714 $pattern =~ s/(\W)/\\\1/g;
715
716This is grandfathered for the RHS of a substitute to avoid shocking the
717B<sed> addicts, but it's a dirty habit to get into. That's because in
5f05dabc 718PerlThink, the righthand side of a C<s///> is a double-quoted string. C<\1> in
cb1a09d0
AD
719the usual double-quoted string means a control-A. The customary Unix
720meaning of C<\1> is kludged in for C<s///>. However, if you get into the habit
721of doing that, you get yourself into trouble if you then add an C</e>
722modifier.
723
5a964f20 724 s/(\d+)/ \1 + 1 /eg; # causes warning under -w
cb1a09d0
AD
725
726Or if you try to do
727
728 s/(\d+)/\1000/;
729
730You can't disambiguate that by saying C<\{1}000>, whereas you can fix it with
731C<${1}000>. Basically, the operation of interpolation should not be confused
732with the operation of matching a backreference. Certainly they mean two
733different things on the I<left> side of the C<s///>.
9fa51da4
CS
734
735=head2 SEE ALSO
736
9b599b2a
GS
737L<perlop/"Regexp Quote-Like Operators">.
738
739L<perlfunc/pos>.
740
741L<perllocale>.
742
5a964f20 743I<Mastering Regular Expressions> (see L<perlbook>) by Jeffrey Friedl.