(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
{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
=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
=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
https://perl5.git.perl.org / perl5.git / blobdiff