Preserve the string matched such that ${^PREMATCH}, ${^MATCH}, and
${^POSTMATCH} are available for use after matching.
-In Perl 5.18 and higher this is ignored. ${^PREMATCH}, ${^MATCH}, and
-${^POSTMATCH} will be available after the match regardless of the modifier.
+In Perl 5.20 and higher this is ignored. Due to a new copy-on-write
+mechanism, ${^PREMATCH}, ${^MATCH}, and ${^POSTMATCH} will be available
+after the match regardless of the modifier.
=item g and c
X</g> X</c>
(Unicode, etc.) are used, as described below in
L</Character set modifiers>.
+=item r
+X</r>
+
+Non-destructive substitution. Unlike regular substitution, the entity to
+which the substitution is bound is B<not> modified in place. Rather, the
+B<result> of the substitution is returned as a plain string. See
+L<perlop/"s/PATTERN/REPLACEMENT/msixpodualgcer"> for further explanation of
+the C</r> modifier.
+
=back
Regular expression modifiers are usually written in documentation
This modifier may be specified to be the default by C<use re '/a'>
or C<use re '/aa'>. If you do so, you may actually have occasion to use
-the C</u> modifier explictly if there are a few regular expressions
+the C</u> modifier explicitly if there are a few regular expressions
where you do want full Unicode rules (but even here, it's best if
everything were under feature C<"unicode_strings">, along with the
C<use re '/aa'>). Also see L</Which character set modifier is in
{n,}? Match at least n times, not greedily
{n,m}? Match at least n but not more than m times, not greedily
-By default, when a quantified subpattern does not allow the rest of the
+Normally when a quantified subpattern does not allow the rest of the
overall pattern to match, Perl will backtrack. However, this behaviour is
sometimes undesirable. Thus Perl provides the "possessive" quantifier form
as well.
/"(?>(?:(?>[^"\\]+)|\\.)*)"/
+Note that the possessive quantifier modifier can not be be combined
+with the non-greedy modifier. This is because it would make no sense.
+Consider the follow equivalency table:
+
+ Illegal Legal
+ ------------ ------
+ X??+ X{0}
+ X+?+ X{1}
+ X{min,max}?+ X{min}
+
=head3 Escape sequences
Because patterns are processed as double-quoted strings, the following
It is worth noting that C<\G> improperly used can result in an infinite
loop. Take care when using patterns that include C<\G> in an alternation.
+Note also that C<s///> will refuse to overwrite part of a substitution
+that has already been replaced; so for example this will stop after the
+first iteration, rather than iterating its way backwards through the
+string:
+
+ $_ = "123456789";
+ pos = 6;
+ s/.(?=.\G)/X/g;
+ print; # prints 1234X6789, not XXXXX6789
+
+
=head3 Capture groups
The bracketing construct C<( ... )> creates capture groups (also referred to as
B<WARNING>: If your code is to run on Perl 5.16 or earlier,
beware that 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. (In Perl 5.18 a
-more efficient mechanism is used, eliminating any slowdown.) Perl
-uses the same mechanism to produce C<$1>, C<$2>, etc, so you also pay a
-price for each pattern that contains capturing parentheses. (To
-avoid this cost while retaining the grouping behaviour, use the
+pattern match. This may substantially slow your program.
+
+Perl uses the same mechanism to produce C<$1>, C<$2>, etc, so you also
+pay a price for each pattern that contains capturing parentheses.
+(To avoid this cost while retaining the grouping behaviour, use the
extended regular expression C<(?: ... )> instead.) But if you never
use C<$&>, C<$`> or C<$'>, then patterns I<without> capturing
parentheses will not be penalized. So avoid C<$&>, C<$'>, and C<$`>
if you can, but if you can't (and some algorithms really appreciate
them), once you've used them once, use them at will, because you've
-already paid the price.
+already paid the price.
X<$&> X<$`> X<$'>
-As a workaround for this problem, Perl 5.10.0 introduced C<${^PREMATCH}>,
+Perl 5.16 introduced a slightly more efficient mechanism that notes
+separately whether each of C<$`>, C<$&>, and C<$'> have been seen, and
+thus may only need to copy part of the string. Perl 5.20 introduced a
+much more efficient copy-on-write mechanism which eliminates any slowdown.
+
+As another workaround for this problem, Perl 5.10.0 introduced 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.
The use of these variables incurs no global performance penalty, unlike
their punctuation char equivalents, however at the trade-off that you
-have to tell perl when you want to use them. As of Perl 5.18, these three
+have to tell perl when you want to use them. As of Perl 5.20, these three
variables are equivalent to C<$`>, C<$&> and C<$'>, and C</p> is ignored.
X</p> X<p modifier>
=item C<(?{ code })>
X<(?{})> X<regex, code in> X<regexp, code in> X<regular expression, code in>
-B<WARNING>: This extended regular expression feature is considered
-experimental, and may be changed without notice. Code executed that
-has side effects may not perform identically from version to version
-due to the effect of future optimisations in the regex engine. The
-implementation of this feature was radically overhauled for the 5.18.0
-release, and its behaviour in earlier versions of perl was much buggier,
-especially in relation to parsing, lexical vars, scoping, recursion and
-reentrancy.
+B<WARNING>: Using this feature safely requires that you understand its
+limitations. Code executed that has side effects may not perform identically
+from version to version due to the effect of future optimisations in the regex
+engine. For more information on this, see L</Embedded Code Execution
+Frequency>.
This zero-width assertion executes any embedded Perl code. It always
succeeds, and its return value is set as C<$^R>.
X<(??{})>
X<regex, postponed> X<regexp, postponed> X<regular expression, postponed>
-B<WARNING>: This extended regular expression feature is considered
-experimental, and may be changed without notice. Code executed that
-has side effects may not perform identically from version to version
-due to the effect of future optimisations in the regex engine.
+B<WARNING>: Using this feature safely requires that you understand its
+limitations. Code executed that has side effects may not perform
+identically from version to version due to the effect of future
+optimisations in the regex engine. For more information on this, see
+L</Embedded Code Execution Frequency>.
This is a "postponed" regular subexpression. It behaves in I<exactly> the
same way as a C<(?{ code })> code block as described above, except that
end of the pattern, and that you name any subpatterns defined within it.
Also, it's worth noting that patterns defined this way probably will
-not be as efficient, as the optimiser is not very clever about
+not be as efficient, as the optimizer is not very clever about
handling them.
An example of how this might be used is as follows:
=head2 Special Backtracking Control Verbs
-B<WARNING:> These patterns are experimental and subject to change or
-removal in a future version of Perl. Their usage in production code should
-be noted to avoid problems during upgrades.
-
These special patterns are generally of the form C<(*VERB:ARG)>. Unless
otherwise stated the ARG argument is optional; in some cases, it is
forbidden.
=item C<(*ACCEPT)>
X<(*ACCEPT)>
-B<WARNING:> This feature is highly experimental. It is not recommended
-for production code.
-
This pattern matches nothing and causes the end of successful matching at
the point at which the C<(*ACCEPT)> pattern was encountered, regardless of
whether there is actually more to match in the string. When inside of a
$re = customre::convert $re;
/\Y|$re\Y|/;
+=head2 Embedded Code Execution Frequency
+
+The exact rules for how often (??{}) and (?{}) are executed in a pattern
+are unspecified. In the case of a successful match you can assume that
+they DWIM and will be executed in left to right order the appropriate
+number of times in the accepting path of the pattern as would any other
+meta-pattern. How non-accepting pathways and match failures affect the
+number of times a pattern is executed is specifically unspecified and
+may vary depending on what optimizations can be applied to the pattern
+and is likely to change from version to version.
+
+For instance in
+
+ "aaabcdeeeee"=~/a(?{print "a"})b(?{print "b"})cde/;
+
+the exact number of times "a" or "b" are printed out is unspecified for
+failure, but you may assume they will be printed at least once during
+a successful match, additionally you may assume that if "b" is printed,
+it will be preceded by at least one "a".
+
+In the case of branching constructs like the following:
+
+ /a(b|(?{ print "a" }))c(?{ print "c" })/;
+
+you can assume that the input "ac" will output "ac", and that "abc"
+will output only "c".
+
+When embedded code is quantified, successful matches will call the
+code once for each matched iteration of the quantifier. For
+example:
+
+ "good" =~ /g(?:o(?{print "o"}))*d/;
+
+will output "o" twice.
+
=head2 PCRE/Python Support
As of Perl 5.10.0, Perl supports several Python/PCRE-specific extensions