Treat string as single line. That is, change "." to match any character
whatsoever, even a newline, which normally it would not match.
-Used together, as /ms, they let the "." match any character whatsoever,
+Used together, as C</ms>, they let the "." match any character whatsoever,
while still allowing "^" and "$" to match, respectively, just after
and just before newlines within the string.
=item p
X</p> X<regex, preserve> X<regexp, preserve>
-Preserve the string matched such that ${^PREMATCH}, {$^MATCH}, and
+Preserve the string matched such that ${^PREMATCH}, ${^MATCH}, and
${^POSTMATCH} are available for use after matching.
+=item g and c
+X</g> X</c>
+
+Global matching, and keep the Current position after failed matching.
+Unlike i, m, s and x, these two flags affect the way the regex is used
+rather than the regex itself. See
+L<perlretut/"Using regular expressions in Perl"> for further explanation
+of the g and c modifiers.
+
=back
These are usually written as "the C</x> modifier", even though the delimiter
the C<(?...)> construct. See below.
The C</x> modifier itself needs a little more explanation. It tells
-the regular expression parser to ignore whitespace that is neither
+the regular expression parser to ignore most whitespace that is neither
backslashed nor within a character class. You can use this to break up
your regular expression into (slightly) more readable parts. The C<#>
character is also treated as a metacharacter introducing a comment,
just as in ordinary Perl code. This also means that if you want real
whitespace or C<#> characters in the pattern (outside a character
class, where they are unaffected by C</x>), then you'll either have to
-escape them (using backslashes or C<\Q...\E>) or encode them using octal
-or hex escapes. Taken together, these features go a long way towards
+escape them (using backslashes or C<\Q...\E>) or encode them using octal,
+hex, or C<\N{}> escapes. Taken together, these features go a long way towards
making Perl's regular expressions more readable. Note that you have to
be careful not to include the pattern delimiter in the comment--perl has
no way of knowing you did not intend to close the pattern early. See
the C-comment deletion code in L<perlop>. Also note that anything inside
-a C<\Q...\E> stays unaffected by C</x>.
+a C<\Q...\E> stays unaffected by C</x>. And note that C</x> doesn't affect
+whether space interpretation within a single multi-character construct. For
+example in C<\x{...}>, regardless of the C</x> modifier, there can be no
+spaces. Same for a L<quantifier|Quantifiers> such as C<{3}> or
+C<{5,}>. Similarly, C<(?:...)> can't have a space between the C<?> and C<:>,
+but can between the C<(> and C<?>. Within any delimiters for such a
+construct, allowed spaces are not affected by C</x>, and depend on the
+construct. For example, C<\x{...}> can't have spaces because hexadecimal
+numbers don't have spaces in them. But, Unicode properties can have spaces, so
+in C<\p{...}> there can be spaces that follow the Unicode rules, for which see
+L<perluniprops.pod/Properties accessible through \p{} and \P{}>.
X</x>
=head2 Regular Expressions
=head3 Metacharacters
-The patterns used in Perl pattern matching evolved from the ones supplied in
+The patterns used in Perl pattern matching evolved from those supplied in
the Version 8 regex routines. (The routines are derived
(distantly) from Henry Spencer's freely redistributable reimplementation
of the V8 routines.) See L<Version 8 Regular Expressions> for
as a regular character. In particular, the lower bound
is not optional.) The "*" quantifier is equivalent to C<{0,}>, the "+"
quantifier to C<{1,}>, and the "?" quantifier to C<{0,1}>. n and m are limited
-to integral values less than a preset limit defined when perl is built.
+to non-negative 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
be seen in the error message generated by code such as this:
Because patterns are processed as double quoted strings, the following
also work:
X<\t> X<\n> X<\r> X<\f> X<\e> X<\a> X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q>
-X<\0> X<\c> X<\N> X<\x>
+X<\0> X<\c> X<\N{}> X<\x>
\t tab (HT, TAB)
\n newline (LF, NL)
\e escape (think troff) (ESC)
\033 octal char (example: ESC)
\x1B hex char (example: ESC)
- \x{263a} wide hex char (example: Unicode SMILEY)
+ \x{263a} long hex char (example: Unicode SMILEY)
\cK control char (example: VT)
- \N{name} named char
+ \N{name} named Unicode character
+ \N{U+263D} Unicode character (example: FIRST QUARTER MOON)
\l lowercase next char (think vi)
\u uppercase next char (think vi)
\L lowercase till \E (think vi)
=head3 Character Classes and other Special Escapes
In addition, Perl defines the following:
-X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\X> X<\p> X<\P> X<\C>
-X<\g> X<\k> X<\N> X<\K> X<\v> X<\V> X<\h> X<\H>
-X<word> X<whitespace> X<character class> X<backreference>
+X<\g> X<\k> X<\K> X<backreference>
\w Match a "word" character (alphanumeric plus "_")
\W Match a non-"word" character
\D Match a non-digit character
\pP Match P, named property. Use \p{Prop} for longer names.
\PP Match non-P
- \X Match eXtended Unicode "combining character sequence",
- equivalent to (?:\PM\pM*)
+ \X Match Unicode "eXtended grapheme cluster"
\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.
optionally be wrapped in curly brackets for safer parsing.
\g{name} Named backreference
\k<name> Named backreference
- \N{name} Named Unicode character, or Unicode escape
- \x12 Hexadecimal escape sequence
- \x{1234} Long hexadecimal escape sequence
\K Keep the stuff left of the \K, don't include it in $&
+ \N Any character but \n (experimental)
\v Vertical whitespace
\V Not vertical whitespace
\h Horizontal whitespace
\H Not horizontal whitespace
\R Linebreak
-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 they aren't usable
-as either end of a range. If any of them precedes or follows a "-",
-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>, C<\X> and the possibility of defining
-your own C<\p> and C<\P> properties, and L<perluniintro> about Unicode
-in general.
-X<\w> X<\W> X<word>
-
-C<\R> will atomically match a linebreak, including the network line-ending
-"\x0D\x0A". Specifically, X<\R> is exactly equivelent to
-
- (?>\x0D\x0A?|[\x0A-\x0C\x85\x{2028}\x{2029}])
-
-B<Note:> C<\R> has no special meaning inside of a character class;
-use C<\v> instead (vertical whitespace).
-X<\R>
+See L<perlrecharclass/Backslashed sequences> for details on
+on C<\w>, C<\W>, C<\s>, C<\S>, C<\d>, C<\D>, C<\p>, C<\P>, C<\N>, C<\v>, C<\V>,
+C<\h>, and C<\H>.
+See L<perlrebackslash/Misc> for details on C<\R> and C<\X>.
+
+Note that C<\N> has two meanings. When of the form C<\N{NAME}>, it matches the
+character whose name is C<NAME>; and similarly when of the form
+C<\N{U+I<wide hex char>}>, it matches the character whose Unicode ordinal is
+I<wide hex char>. Otherwise it matches any character but C<\n>.
The POSIX character class syntax
X<character class>
# this is not, and will generate a warning:
$string =~ /[:alpha:]/;
-The available classes and their backslash equivalents (if available) are
-as follows:
-X<character class>
-X<alpha> X<alnum> X<ascii> X<blank> X<cntrl> X<digit> X<graph>
-X<lower> X<print> X<punct> X<space> X<upper> X<word> X<xdigit>
-
- alpha
- alnum
- ascii
- blank [1]
- cntrl
- digit \d
- graph
- lower
- print
- punct
- space \s [2]
- upper
- word \w [3]
- xdigit
-
-=over
-
-=item [1]
-
-A GNU extension equivalent to C<[ \t]>, "all horizontal whitespace".
-
-=item [2]
-
-Not exactly equivalent to C<\s> since the C<[[:space:]]> includes
-also the (very rare) "vertical tabulator", "\cK" or chr(11) in ASCII.
-
-=item [3]
-
-A Perl extension, see above.
-
-=back
-
-For example use C<[:upper:]> to match all the uppercase characters.
-Note that the C<[]> are part of the C<[::]> construct, not part of the
-whole character class. For example:
-
- [01[:alpha:]%]
-
-matches zero, one, any alphabetic character, and the percent sign.
-
-The following equivalences to Unicode \p{} constructs and equivalent
-backslash character classes (if available), will hold:
-X<character class> X<\p> X<\p{}>
-
- [[:...:]] \p{...} backslash
-
- alpha IsAlpha
- alnum IsAlnum
- ascii IsASCII
- blank
- cntrl IsCntrl
- digit IsDigit \d
- graph IsGraph
- lower IsLower
- print IsPrint
- punct IsPunct
- space IsSpace
- IsSpacePerl \s
- upper IsUpper
- word IsWord
- xdigit IsXDigit
-
-For example C<[[:lower:]]> and C<\p{IsLower}> are equivalent.
-
-If the C<utf8> pragma is not used but the C<locale> pragma is, the
-classes correlate with the usual isalpha(3) interface (except for
-"word" and "blank").
-
-The assumedly non-obviously named classes are:
-
-=over 4
-
-=item cntrl
-X<cntrl>
-
-Any control character. Usually characters that don't produce output as
-such but instead control the terminal somehow: for example newline and
-backspace are control characters. All characters with ord() less than
-32 are usually classified as control characters (assuming ASCII,
-the ISO Latin character sets, and Unicode), as is the character with
-the ord() value of 127 (C<DEL>).
-
-=item graph
-X<graph>
-
-Any alphanumeric or punctuation (special) character.
-
-=item print
-X<print>
-
-Any alphanumeric or punctuation (special) character or the space character.
-
-=item punct
-X<punct>
-
-Any punctuation (special) character.
-
-=item xdigit
-X<xdigit>
-
-Any hexadecimal digit. Though this may feel silly ([0-9A-Fa-f] would
-work just fine) it is included for completeness.
-
-=back
+The following Posix-style character classes are available:
+
+ [[:alpha:]] Any alphabetical character.
+ [[:alnum:]] Any alphanumerical character.
+ [[:ascii:]] Any character in the ASCII character set.
+ [[:blank:]] A GNU extension, equal to a space or a horizontal tab
+ [[:cntrl:]] Any control character.
+ [[:digit:]] Any decimal digit, equivalent to "\d".
+ [[:graph:]] Any printable character, excluding a space.
+ [[:lower:]] Any lowercase character.
+ [[:print:]] Any printable character, including a space.
+ [[:punct:]] Any graphical character excluding "word" characters.
+ [[:space:]] Any whitespace character. "\s" plus the vertical tab ("\cK").
+ [[:upper:]] Any uppercase character.
+ [[:word:]] A Perl extension, equivalent to "\w".
+ [[:xdigit:]] Any hexadecimal digit.
You can negate the [::] character classes by prefixing the class name
-with a '^'. This is a Perl extension. For example:
-X<character class, negation>
-
- POSIX traditional Unicode
+with a '^'. This is a Perl extension.
- [[:^digit:]] \D \P{IsDigit}
- [[:^space:]] \S \P{IsSpace}
- [[:^word:]] \W \P{IsWord}
-
-Perl respects the POSIX standard in that POSIX character classes are
-only supported within a character class. The POSIX character classes
+The POSIX character classes
[.cc.] and [=cc=] are recognized but B<not> supported and trying to
use them will cause an error.
+Details on POSIX character classes are in
+L<perlrecharclass/Posix Character Classes>.
+
=head3 Assertions
Perl defines the following zero-width assertions:
backreference only if at least 11 left parentheses have opened
before it. And so on. \1 through \9 are always interpreted as
backreferences.
+If the bracketing group did not match, the associated backreference won't
+match either. (This can happen if the bracketing group is optional, or
+in a different branch of an alternation.)
X<\g{1}> X<\g{-1}> X<\g{name}> X<relative backreference> X<named backreference>
In order to provide a safer and easier way to construct patterns using
-backreferences, Perl 5.10 provides the C<\g{N}> notation. The curly
-brackets are optional, however omitting them is less safe as the meaning
-of the pattern can be changed by text (such as digits) following it.
-When N is a positive integer the C<\g{N}> notation is exactly equivalent
-to using normal backreferences. When N is a negative integer then it is
-a relative backreference referring to the previous N'th capturing group.
-When the bracket form is used and N is not an integer, it is treated as a
-reference to a named buffer.
+backreferences, Perl provides the C<\g{N}> notation (starting with perl
+5.10.0). The curly brackets are optional, however omitting them is less
+safe as the meaning of the pattern can be changed by text (such as digits)
+following it. When N is a positive integer the C<\g{N}> notation is
+exactly equivalent to using normal backreferences. When N is a negative
+integer then it is a relative backreference referring to the previous N'th
+capturing group. When the bracket form is used and N is not an integer, it
+is treated as a reference to a named buffer.
Thus C<\g{-1}> refers to the last buffer, C<\g{-2}> refers to the
buffer before that. For example:
and would match the same as C</(Y) ( (X) \3 \1 )/x>.
-Additionally, as of Perl 5.10 you may use named capture buffers and named
+Additionally, as of Perl 5.10.0 you may use named capture buffers and named
backreferences. The notation is C<< (?<name>...) >> to declare and C<< \k<name> >>
to reference. You may also use apostrophes instead of angle brackets to delimit the
name; and you may use the bracketed C<< \g{name} >> backreference syntax.
to do things with named capture buffers that would otherwise require C<(??{})>
code to accomplish.)
X<named capture buffer> X<regular expression, named capture buffer>
-X<%+> X<$+{name}> X<\k{name}>
+X<%+> X<$+{name}> X<< \k<name> >>
Examples:
other two.
X<$&> X<$`> X<$'>
-As a workaround for this problem, Perl 5.10 introduces C<${^PREMATCH}>,
+As a workaround for this problem, Perl 5.10.0 introduces C<${^PREMATCH}>,
C<${^MATCH}> and C<${^POSTMATCH}>, which are equivalent to C<$`>, C<$&>
and C<$'>, B<except> that they are only guaranteed to be defined after a
successful match that was executed with the C</p> (preserve) modifier.
repetition of the previous word, assuming the C</x> modifier, and no C</i>
modifier outside this group.
-Note that the C<k> modifier is special in that it can only be enabled,
+These modifiers do not carry over into named subpatterns called in the
+enclosing group. In other words, a pattern such as C<((?i)(&NAME))> does not
+change the case-sensitivity of the "NAME" pattern.
+
+Note that the C<p> modifier is special in that it can only be enabled,
not disabled, and that its presence anywhere in a pattern has a global
-effect. Thus C<(?-k)> and C<(?-k:...)> are meaningless and will warn
+effect. Thus C<(?-p)> and C<(?-p:...)> are meaningless and will warn
when executed under C<use warnings>.
=item C<(?:pattern)>
This is the "branch reset" pattern, which has the special property
that the capture buffers are numbered from the same starting point
-in each alternation branch. It is available starting from perl 5.10.
+in each alternation branch. It is available starting from perl 5.10.0.
Capture buffers are numbered from left to right, but inside this
construct the numbering is restarted for each branch.
/ ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x
# 1 2 2 3 2 3 4
+Be careful when using the branch reset pattern in combination with
+named captures. Named captures are implemented as being aliases to
+numbered buffers holding the captures, and that interferes with the
+implementation of the branch reset pattern. If you are using named
+captures in a branch reset pattern, it's best to use the same names,
+in the same order, in each of the alternations:
+
+ /(?| (?<a> x ) (?<b> y )
+ | (?<a> z ) (?<b> w )) /x
+
+Not doing so may lead to surprises:
+
+ "12" =~ /(?| (?<a> \d+ ) | (?<b> \D+))/x;
+ say $+ {a}; # Prints '12'
+ say $+ {b}; # *Also* prints '12'.
+
+The problem here is that both the buffer named C<< a >> and the buffer
+named C<< b >> are aliases for the buffer belonging to C<< $1 >>.
+
=item Look-Around Assertions
X<look-around assertion> X<lookaround assertion> X<look-around> X<lookaround>
X<< (?<NAME>) >> X<(?'NAME')> X<named capture> X<capture>
A named capture buffer. Identical in every respect to normal capturing
-parentheses C<()> but for the additional fact that C<%+> may be used after
-a successful match to refer to a named buffer. See C<perlvar> for more
-details on the C<%+> hash.
+parentheses C<()> but for the additional fact that C<%+> or C<%-> may be
+used after a successful match to refer to a named buffer. See C<perlvar>
+for more details on the C<%+> and C<%-> hashes.
If multiple distinct capture buffers have the same name then the
$+{NAME} will refer to the leftmost defined buffer in the match.
B<NOTE:> In order to make things easier for programmers with experience
with the Python or PCRE regex engines, the pattern C<< (?PE<lt>NAMEE<gt>pattern) >>
may be used instead of C<< (?<NAME>pattern) >>; however this form does not
-support the use of single quotes as a delimiter for the name. This is
-only available in Perl 5.10 or later.
+support the use of single quotes as a delimiter for the name.
=item C<< \k<NAME> >>
B<NOTE:> In order to make things easier for programmers with experience
with the Python or PCRE regex engines, the pattern C<< (?P=NAME) >>
-may be used instead of C<< \k<NAME> >> in Perl 5.10 or later.
+may be used instead of C<< \k<NAME> >>.
=item C<(?{ code })>
X<(?{})> X<regex, code in> X<regexp, code in> X<regular expression, code in>
value of C<$^R> is restored if the assertion is backtracked; compare
L<"Backtracking">.
-Due to an unfortunate implementation issue, the Perl code contained in these
-blocks is treated as a compile time closure that can have seemingly bizarre
-consequences when used with lexically scoped variables inside of subroutines
-or loops. There are various workarounds for this, including simply using
-global variables instead. If you are using this construct and strange results
-occur then check for the use of lexically scoped variables.
-
For reasons of security, this construct is forbidden if the regular
expression involves run-time interpolation of variables, unless the
perilous C<use re 'eval'> pragma has been used (see L<re>), or the
Better yet, use the carefully constrained evaluation within a Safe
compartment. See L<perlsec> for details about both these mechanisms.
-Because Perl's regex engine is currently not re-entrant, interpolated
-code may not invoke the regex engine either directly with C<m//> or C<s///>),
-or indirectly with functions such as C<split>.
+B<WARNING>: Use of lexical (C<my>) variables in these blocks is
+broken. The result is unpredictable and will make perl unstable. The
+workaround is to use global (C<our>) variables.
+
+B<WARNING>: Because Perl's regex engine is currently not re-entrant,
+interpolated code may not invoke the regex engine either directly with
+C<m//> or C<s///>), or indirectly with functions such as
+C<split>. Invoking the regex engine in these blocks will make perl
+unstable.
=item C<(??{ code })>
X<(??{})>
See also C<(?PARNO)> for a different, more efficient way to accomplish
the same task.
+For reasons of security, this construct is forbidden if the regular
+expression involves run-time interpolation of variables, unless the
+perilous C<use re 'eval'> pragma has been used (see L<re>), or the
+variables contain results of C<qr//> operator (see
+L<perlop/"qr/STRING/imosx">).
+
Because perl's regex engine is not currently re-entrant, delayed
code may not invoke the regex engine either directly with C<m//> or C<s///>),
or indirectly with functions such as C<split>.
B<NOTE:> In order to make things easier for programmers with experience
with the Python or PCRE regex engines the pattern C<< (?P>NAME) >>
-may be used instead of C<< (?&NAME) >> in Perl 5.10 or later.
+may be used instead of C<< (?&NAME) >>.
=item C<(?(condition)yes-pattern|no-pattern)>
X<(?()>
forbidden.
Any pattern containing a special backtracking verb that allows an argument
-has the special behaviour that when executed it sets the current packages'
+has the special behaviour that when executed it sets the current package's
C<$REGERROR> and C<$REGMARK> variables. When doing so the following
rules apply:
print "Count=$count\n";
we prevent backtracking and find the count of the longest matching
-at each matching startpoint like so:
+at each matching starting point like so:
aaab
aab
Count=2
Once the 'aaab' at the start of the string has matched, and the C<(*SKIP)>
-executed, the next startpoint will be where the cursor was when the
+executed, the next starting point will be where the cursor was when the
C<(*SKIP)> was executed.
=item C<(*MARK:NAME)> C<(*:NAME)>
when a certain part of the pattern has been successfully matched. This
mark may be given a name. A later C<(*SKIP)> pattern will then skip
forward to that point if backtracked into on failure. Any number of
-C<(*MARK)> patterns are allowed, and the NAME portion is optional and may
-be duplicated.
+C<(*MARK)> patterns are allowed, and the NAME portion may be duplicated.
In addition to interacting with the C<(*SKIP)> pattern, C<(*MARK:NAME)>
can be used to "label" a pattern branch, so that after matching, the
=item C<(*THEN)> C<(*THEN:NAME)>
-This is similar to the "cut group" operator C<::> from Perl6. Like
+This is similar to the "cut group" operator C<::> from Perl 6. Like
C<(*PRUNE)>, this verb always matches, and when backtracked into on
failure, it causes the regex engine to try the next alternation in the
innermost enclosing group (capturing or otherwise).
=item C<(*COMMIT)>
X<(*COMMIT)>
-This is the Perl6 "commit pattern" C<< <commit> >> or C<:::>. It's a
+This is the Perl 6 "commit pattern" C<< <commit> >> or C<:::>. It's a
zero-width pattern similar to C<(*SKIP)>, except that when backtracked
into on failure it causes the match to fail outright. No further attempts
to find a valid match by advancing the start pointer will occur again.
=head1 PCRE/Python Support
-As of Perl 5.10 Perl supports several Python/PCRE specific extensions
+As of Perl 5.10.0, Perl supports several Python/PCRE specific extensions
to the regex syntax. While Perl programmers are encouraged to use the
-Perl specific syntax, the following are legal in Perl 5.10:
+Perl specific syntax, the following are also accepted:
=over 4
=head1 BUGS
+There are numerous problems with case insensitive matching of characters
+outside the ASCII range, especially with those whose folds are multiple
+characters, such as ligatures like C<LATIN SMALL LIGATURE FF>.
+
+In a bracketed character class with case insensitive matching, ranges only work
+for ASCII characters. For example,
+C<m/[\N{CYRILLIC CAPITAL LETTER A}-\N{CYRILLIC CAPITAL LETTER YA}]/i>
+doesn't match all the Russian upper and lower case letters.
+
+Many regular expression constructs don't work on EBCDIC platforms.
+
This document varies from difficult to understand to completely
and utterly opaque. The wandering prose riddled with jargon is
hard to fathom in several places.
https://perl5.git.perl.org / perl5.git / blobdiff