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