This page describes the syntax of regular expressions in Perl.
-if you haven't used regular expressions before, a quick-start
+If you haven't used regular expressions before, a quick-start
introduction is available in L<perlrequick>, and a longer tutorial
introduction is available in L<perlretut>.
Treat string as single line. That is, change "." to match any character
whatsoever, even a newline, which normally it would not match.
-The C</s> and C</m> modifiers both override the C<$*> setting. That
-is, no matter what C<$*> contains, C</s> without C</m> will force
-"^" to match only at the beginning of the string and "$" to match
-only at the end (or just before a newline at the end) of the string.
-Together, as /ms, they let the "." match any character whatsoever,
+Used together, as /ms, they let the "." match any character whatsoever,
while still allowing "^" and "$" to match, respectively, just after
and just before newlines within the string.
newline within the string, and "$" will match before any newline. At the
cost of a little more overhead, you can do this by using the /m modifier
on the pattern match operator. (Older programs did this by setting C<$*>,
-but this practice is now deprecated.)
+but this practice has been removed in perl 5.9.)
To simplify multi-line substitutions, the "." character never matches a
newline unless you use the C</s> modifier, which in effect tells Perl to pretend
-the string is a single line--even if it isn't. The C</s> modifier also
-overrides the setting of C<$*>, in case you have some (badly behaved) older
-code that sets it in another module.
+the string is a single line--even if it isn't.
The following standard quantifiers are recognized:
{n,m} Match at least n but not more than m times
(If a curly bracket occurs in any other context, it is treated
-as a regular character.) The "*" modifier is equivalent to C<{0,}>, the "+"
+as a regular character. In particular, the lower bound
+is not optional.) The "*" modifier is equivalent to C<{0,}>, the "+"
modifier to C<{1,}>, and the "?" modifier to C<{0,1}>. n and m are limited
to integral values less than a preset limit defined when perl is built.
This is usually 32766 on the most common platforms. The actual limit can
\C Match a single C char (octet) even under Unicode.
NOTE: breaks up characters into their UTF-8 bytes,
so you may end up with malformed pieces of UTF-8.
-
-A C<\w> matches a single alphanumeric character or C<_>, not a whole word.
-Use C<\w+> to match a string of Perl-identifier characters (which isn't
-the same as matching an English word). If C<use locale> is in effect, the
-list of alphabetic characters generated by C<\w> is taken from the
-current locale. See L<perllocale>. You may use C<\w>, C<\W>, C<\s>, C<\S>,
+ Unsupported in lookbehind.
+
+A C<\w> matches a single alphanumeric character (an alphabetic
+character, or a decimal digit) or C<_>, not a whole word. Use C<\w+>
+to match a string of Perl-identifier characters (which isn't the same
+as matching an English word). If C<use locale> is in effect, the list
+of alphabetic characters generated by C<\w> is taken from the current
+locale. See L<perllocale>. You may use C<\w>, C<\W>, C<\s>, C<\S>,
C<\d>, and C<\D> within character classes, but if you try to use them
-as endpoints of a range, that's not a range, the "-" is understood literally.
-See L<perlunicode> for details about C<\pP>, C<\PP>, and C<\X>.
+as endpoints of a range, that's not a range, the "-" is understood
+literally. If Unicode is in effect, C<\s> matches also "\x{85}",
+"\x{2028}, and "\x{2029}", see L<perlunicode> for more details about
+C<\pP>, C<\PP>, and C<\X>, and L<perluniintro> about Unicode in general.
+You can define your own C<\p> and C<\P> properties, see L<perlunicode>.
The POSIX character class syntax
=item [2]
Not exactly equivalent to C<\s> since the C<[[:space:]]> includes
-also the (very rare) `vertical tabulator', \ck", chr(11).
+also the (very rare) `vertical tabulator', "\ck", chr(11).
=item [3]
-A Perl extension.
+A Perl extension, see above.
=back
[:^space:] \S \P{IsSpace}
[:^word:] \W \P{IsWord}
-The POSIX character classes [.cc.] and [=cc=] are recognized but
-B<not> supported and trying to use them will cause an error.
+Perl respects the POSIX standard in that POSIX character classes are
+only supported within a character class. The POSIX character classes
+[.cc.] and [=cc=] are recognized but B<not> supported and trying to
+use them will cause an error.
Perl defines the following zero-width assertions:
several patterns that you want to match against consequent substrings
of your string, see the previous reference. The actual location
where C<\G> will match can also be influenced by using C<pos()> as
-an lvalue. See L<perlfunc/pos>.
+an lvalue: see L<perlfunc/pos>. Currently C<\G> is only fully
+supported when anchored to the start of the pattern; while it
+is permitted to use it elsewhere, as in C</(?<=\G..)./g>, some
+such uses (C</.\G/g>, for example) currently cause problems, and
+it is recommended that you avoid such usage for now.
The bracketing construct C<( ... )> creates capture buffers. To
refer to the digit'th buffer use \<digit> within the
match. C<$+> returns whatever the last bracket match matched.
C<$&> returns the entire matched string. (At one point C<$0> did
also, but now it returns the name of the program.) C<$`> returns
-everything before the matched string. And C<$'> returns everything
-after the matched string.
-
-The numbered variables ($1, $2, $3, etc.) and the related punctuation
-set (C<$+>, C<$&>, C<$`>, and C<$'>) are all dynamically scoped
+everything before the matched string. C<$'> returns everything
+after the matched string. And C<$^N> contains whatever was matched by
+the most-recently closed group (submatch). C<$^N> can be used in
+extended patterns (see below), for example to assign a submatch to a
+variable.
+
+The numbered match variables ($1, $2, $3, etc.) and the related punctuation
+set (C<$+>, C<$&>, C<$`>, C<$'>, and C<$^N>) are all dynamically scoped
until the end of the enclosing block or until the next successful
match, whichever comes first. (See L<perlsyn/"Compound Statements">.)
+B<NOTE>: failed matches in Perl do not reset the match variables,
+which makes it easier to write code that tests for a series of more
+specific cases and remembers the best match.
+
B<WARNING>: Once Perl sees that you need one of C<$&>, C<$`>, or
C<$'> anywhere in the program, it has to provide them for every
pattern match. This may substantially slow your program. Perl
=item C<(?imsx-imsx)>
-One or more embedded pattern-match modifiers. This is particularly
-useful for dynamic patterns, such as those read in from a configuration
-file, read in as an argument, are specified in a table somewhere,
-etc. Consider the case that some of which want to be case sensitive
-and some do not. The case insensitive ones need to include merely
-C<(?i)> at the front of the pattern. For example:
+One or more embedded pattern-match modifiers, to be turned on (or
+turned off, if preceded by C<->) for the remainder of the pattern or
+the remainder of the enclosing pattern group (if any). This is
+particularly useful for dynamic patterns, such as those read in from a
+configuration file, read in as an argument, are specified in a table
+somewhere, etc. Consider the case that some of which want to be case
+sensitive and some do not. The case insensitive ones need to include
+merely C<(?i)> at the front of the pattern. For example:
$pattern = "foobar";
if ( /$pattern/i ) { }
$pattern = "(?i)foobar";
if ( /$pattern/ ) { }
-Letters after a C<-> turn those modifiers off. These modifiers are
-localized inside an enclosing group (if any). For example,
+These modifiers are restored at the end of the enclosing group. For example,
( (?i) blah ) \s+ \1
B<WARNING>: This extended regular expression feature is considered
highly experimental, and may be changed or deleted without notice.
-This zero-width assertion evaluate any embedded Perl code. It
+This zero-width assertion evaluates any embedded Perl code. It
always succeeds, and its C<code> is not interpolated. Currently,
the rules to determine where the C<code> ends are somewhat convoluted.
+This feature can be used together with the special variable C<$^N> to
+capture the results of submatches in variables without having to keep
+track of the number of nested parentheses. For example:
+
+ $_ = "The brown fox jumps over the lazy dog";
+ /the (\S+)(?{ $color = $^N }) (\S+)(?{ $animal = $^N })/i;
+ print "color = $color, animal = $animal\n";
+
+Inside the C<(?{...})> block, C<$_> refers to the string the regular
+expression is matching against. You can also use C<pos()> to know what is
+the current position of matching within this string.
+
The C<code> is properly scoped in the following sense: If the assertion
is backtracked (compare L<"Backtracking">), all changes introduced after
C<local>ization are undone, so that
you turn on the C<use re 'eval'>, though, it is no longer secure,
so you should only do so if you are also using taint checking.
Better yet, use the carefully constrained evaluation within a Safe
-module. See L<perlsec> for details about both these mechanisms.
+compartment. See L<perlsec> for details about both these mechanisms.
=item C<(??{ code })>
know which variety of success you will achieve.
When using look-ahead assertions and negations, this can all get even
-tricker. Imagine you'd like to find a sequence of non-digits not
+trickier. Imagine you'd like to find a sequence of non-digits not
followed by "123". You might try to write that as
$_ = "ABC123";
the functionality of the RE engine.
Suppose that we want to enable a new RE escape-sequence C<\Y|> which
-matches at boundary between white-space characters and non-whitespace
+matches at boundary between whitespace characters and non-whitespace
characters. Note that C<(?=\S)(?<!\S)|(?!\S)(?<=\S)> matches exactly
at these positions, so we want to have each C<\Y|> in the place of the
more complicated version. We can create a module C<customre> to do
sub invalid { die "/$_[0]/: invalid escape '\\$_[1]'"}
- my %rules = ( '\\' => '\\',
+ # We must also take care of not escaping the legitimate \\Y|
+ # sequence, hence the presence of '\\' in the conversion rules.
+ my %rules = ( '\\' => '\\\\',
'Y|' => qr/(?=\S)(?<!\S)|(?!\S)(?<=\S)/ );
sub convert {
my $re = shift;
projects / p5sagit/p5-mst-13.2.git / blobdiff