X</m> X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
Treat string as multiple lines. That is, change "^" and "$" from matching
-the start or end of line only at the left and right ends of the string to
-matching them anywhere within the string.
+the start of the string's first line and the end of its last line to
+matching the start and end of each line within the string.
=item s
X</s> X<regex, single-line> X<regexp, single-line>
# be even if it did!!
"\N{LATIN SMALL LIGATURE FI}" =~ /(f)(i)/i; # Doesn't match!
-Perl doesn't match multiple characters in an inverted bracketed
-character class, which otherwise could be highly confusing. See
+Perl doesn't match multiple characters in a bracketed
+character class unless the character that maps to them is explicitly
+mentioned, and it doesn't match them at all if the character class is
+inverted, which otherwise could be highly confusing. See
+L<perlrecharclass/Bracketed Character Classes>, and
L<perlrecharclass/Negation>.
-Another bug involves character classes that match both a sequence of
-multiple characters, and an initial sub-string of that sequence. For
-example,
-
- /[s\xDF]/i
-
-should match both a single and a double "s", since C<\xDF> (on ASCII
-platforms) matches "ss". However, this bug
-(L<[perl #89774]|https://rt.perl.org/rt3/Ticket/Display.html?id=89774>)
-causes it to only match a single "s", even if the final larger match
-fails, and matching the double "ss" would have succeeded.
-
-Also, Perl matching doesn't fully conform to the current Unicode C</i>
-recommendations, which ask that the matching be made upon the NFD
-(Normalization Form Decomposed) of the text. However, Unicode is
-in the process of reconsidering and revising their recommendations.
-
=item x
X</x>
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.
+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 a, d, l and u
X</a> X</d> X</l> X</u>
-These modifiers, all new in 5.14, affect which character-set semantics
+These modifiers, all new in 5.14, affect which character-set rules
(Unicode, etc.) are used, as described below in
L</Character set modifiers>.
+=item Other Modifiers
+
+There are a number of flags that can be found at the end of regular
+expression constructs that are I<not> generic regular expression flags, but
+apply to the operation being performed, like matching or substitution (C<m//>
+or C<s///> respectively).
+
+Flags described further in
+L<perlretut/"Using regular expressions in Perl"> are:
+
+ c - keep the current position during repeated matching
+ g - globally match the pattern repeatedly in the string
+
+Substitution-specific modifiers described in
+
+L<perlop/"s/PATTERN/REPLACEMENT/msixpodualgcer"> are:
+
+ e - evaluate the right-hand side as an expression
+ ee - evaluate the right side as a string then eval the result
+ o - pretend to optimize your code, but actually introduce bugs
+ r - perform non-destructive substitution and return the new value
+
=back
Regular expression modifiers are usually written in documentation
C</x> tells
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
+backslashed nor within a bracketed character class. You can use this to
+break up your regular expression into (slightly) more readable parts.
+Also, the C<#> character is treated as a metacharacter introducing a
+comment that runs up to the pattern's closing delimiter, or to the end
+of the current line if the pattern extends onto the next line. Hence,
+this is very much like an ordinary Perl code comment. (You can include
+the closing delimiter within the comment only if you precede it with a
+backslash, so be careful!)
+
+Use of C</x> means that if you want real
+whitespace or C<#> characters in the pattern (outside a bracketed character
+class, which is unaffected by C</x>), then you'll either have to
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
+hex, or C<\N{}> escapes.
+It is ineffective to try to continue a comment onto the next line by
+escaping the C<\n> with a backslash or C<\Q>.
+
+You can use L</(?#text)> to create a comment that ends earlier than the
+end of the current line, but C<text> also can't contain the closing
+delimiter unless escaped with a backslash.
+
+Taken together, these features go a long way towards
+making Perl's regular expressions more readable. Here's an example:
+
+ # Delete (most) C comments.
+ $program =~ s {
+ /\* # Match the opening delimiter.
+ .*? # Match a minimal number of characters.
+ \*/ # Match the closing delimiter.
+ } []gsx;
+
+Note that anything inside
a C<\Q...\E> stays unaffected by C</x>. And note that C</x> doesn't affect
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
+C<{5,}>. Similarly, C<(?:...)> can't have a space between the C<(>,
+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
=head3 Character set modifiers
C</d>, C</u>, C</a>, and C</l>, available starting in 5.14, are called
-the character set modifiers; they affect the character set semantics
+the character set modifiers; they affect the character set rules
used for the regular expression.
The C</d>, C</u>, and C</l> modifiers are not likely to be of much use
to another if there is an intervening call of the
L<setlocale() function|perllocale/The setlocale function>.
-Perl only supports single-byte locales. This means that code points
-above 255 are treated as Unicode no matter what locale is in effect.
+The only non-single-byte locale Perl supports is (starting in v5.20)
+UTF-8. This means that code points above 255 are treated as Unicode no
+matter what locale is in effect (since UTF-8 implies Unicode).
+
Under Unicode rules, there are a few case-insensitive matches that cross
-the 255/256 boundary. These are disallowed under C</l>. For example,
-0xFF (on ASCII platforms) does not caselessly match the character at
-0x178, C<LATIN CAPITAL LETTER Y WITH DIAERESIS>, because 0xFF may not be
-C<LATIN SMALL LETTER Y WITH DIAERESIS> in the current locale, and Perl
-has no way of knowing if that character even exists in the locale, much
-less what code point it is.
+the 255/256 boundary. Except for UTF-8 locales in Perls v5.20 and
+later, these are disallowed under C</l>. For example, 0xFF (on ASCII
+platforms) does not caselessly match the character at 0x178, C<LATIN
+CAPITAL LETTER Y WITH DIAERESIS>, because 0xFF may not be C<LATIN SMALL
+LETTER Y WITH DIAERESIS> in the current locale, and Perl has no way of
+knowing if that character even exists in the locale, much less what code
+point it is.
+
+In a UTF-8 locale in v5.20 and later, the only visible difference
+between locale and non-locale in regular expressions should be tainting
+(see L<perlsec>).
This modifier may be specified to be the default by C<use locale>, but
see L</Which character set modifier is in effect?>.
L<http://unicode.org/reports/tr36> for a detailed discussion of Unicode
security issues.
-On the EBCDIC platforms that Perl handles, the native character set is
-equivalent to Latin-1. Thus this modifier changes behavior only when
-the C<"/i"> modifier is also specified, and it turns out it affects only
-two characters, giving them full Unicode semantics: the C<MICRO SIGN>
-will match the Greek capital and small letters C<MU>, otherwise not; and
-the C<LATIN CAPITAL LETTER SHARP S> will match any of C<SS>, C<Ss>,
-C<sS>, and C<ss>, otherwise not.
-
This modifier may be specified to be the default by C<use feature
'unicode_strings>, C<use locale ':not_characters'>, or
C<L<use 5.012|perlfunc/use VERSION>> (or higher),
=item 5
-the pattern uses a Unicode property (C<\p{...}>)
+the pattern uses a Unicode property (C<\p{...}>); or
+
+=item 6
+
+the pattern uses L</C<(?[ ])>>
=back
become rather infamous, leading to yet another (printable) name for this
modifier, "Dodgy".
-On ASCII platforms, the native rules are ASCII, and on EBCDIC platforms
-(at least the ones that Perl handles), they are Latin-1.
+Unless the pattern or string are encoded in UTF-8, only ASCII characters
+can match positively.
Here are some examples of how that works on an ASCII platform:
the Posix character classes to match only in the ASCII range. They thus
revert to their pre-5.6, pre-Unicode meanings. Under C</a>, C<\d>
always means precisely the digits C<"0"> to C<"9">; C<\s> means the five
-characters C<[ \f\n\r\t]>; C<\w> means the 63 characters
+characters C<[ \f\n\r\t]>, and starting in Perl v5.18, experimentally,
+the vertical tab; C<\w> means the 63 characters
C<[A-Za-z0-9_]>; and likewise, all the Posix classes such as
C<[[:print:]]> match only the appropriate ASCII-range characters.
for C<\B>).
Otherwise, C</a> behaves like the C</u> modifier, in that
-case-insensitive matching uses Unicode semantics; for example, "k" will
+case-insensitive matching uses Unicode rules; for example, "k" will
match the Unicode C<\N{KELVIN SIGN}> under C</i> matching, and code
points in the Latin1 range, above ASCII will have Unicode rules when it
comes to case-insensitive matching.
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
\ Quote the next metacharacter
^ Match the beginning of the line
. Match any character (except newline)
- $ Match the end of the line (or before newline at the end)
+ $ Match the end of the string (or before newline at the end
+ of the string)
| Alternation
() Grouping
[] Bracketed Character class
{n,m} Match at least n but not more than m times
(If a curly bracket occurs in any other context and does not form part of
-a backslashed sequence like C<\x{...}>, it is treated
-as a regular character. In particular, the lower quantifier bound
-is not optional. However, in Perl v5.18, it is planned to issue a
-deprecation warning for all such occurrences, and in Perl v5.20 to
-require literal uses of a curly bracket to be escaped, say by preceding
-them with a backslash or enclosing them within square brackets, (C<"\{">
-or C<"[{]">). This change will allow for future syntax extensions (like
-making the lower bound of a quantifier optional), and better error
-checking of quantifiers. Now, a typo in a quantifier silently causes
-it to be treated as the literal characters. For example,
-
- /o{4,3}/
-
-looks like a quantifier that matches 0 times, since 4 is greater than 3,
-but it really means to match the sequence of six characters
-S<C<"o { 4 , 3 }">>.)
+a backslashed sequence like C<\x{...}>, it is treated as a regular
+character. In particular, the lower quantifier bound is not optional,
+and a typo in a quantifier silently causes it to be treated as the
+literal characters. For example,
+
+ /o{4,a}/
+
+compiles to match the sequence of six characters
+S<C<"o { 4 , a }">>. It is planned to eventually require literal uses
+of curly brackets to be escaped, say by preceding them with a backslash
+or enclosing them within square brackets, (C<"\{"> or C<"[{]">). This
+change will allow for future syntax extensions (like making the lower
+bound of a quantifier optional), and better error checking. In the
+meantime, you should get in the habit of escaping all instances where
+you mean a literal "{".)
The "*" quantifier is equivalent to C<{0,}>, the "+"
quantifier to C<{1,}>, and the "?" quantifier to C<{0,1}>. n and m are limited
{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
character class "..." within the outer bracketed
character class. Example: [[:upper:]] matches any
uppercase character.
+ (?[...]) [8] Extended bracketed character class
\w [3] Match a "word" character (alphanumeric plus "_", plus
other connector punctuation chars plus Unicode
marks)
part of a larger UTF-8 character. Thus it breaks up
characters into their UTF-8 bytes, so you may end up
with malformed pieces of UTF-8. Unsupported in
- lookbehind.
+ lookbehind. (Deprecated.)
\1 [5] Backreference to a specific capture group or buffer.
'1' may actually be any positive integer.
\g1 [5] Backreference to a specific or previous group,
\g{name} [5] Named backreference
\k<name> [5] Named backreference
\K [6] Keep the stuff left of the \K, don't include it in $&
- \N [7] Any character but \n (experimental). Not affected by
- /s modifier
+ \N [7] Any character but \n. Not affected by /s modifier
\v [3] Vertical whitespace
\V [3] Not vertical whitespace
\h [3] Horizontal whitespace
when of the form C<\N{U+I<hex>}>, it matches the character whose Unicode
code point is I<hex>. Otherwise it matches any character but C<\n>.
+=item [8]
+
+See L<perlrecharclass/Extended Bracketed Character Classes> for details.
+
=back
=head3 Assertions
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
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
+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. 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. As of 5.17.4, the presence of each of the three
-variables in a program is recorded separately, and depending on
-circumstances, perl may be able be more efficient knowing that only C<$&>
-rather than all three have been seen, for example.
+already paid the price.
X<$&> X<$`> X<$'>
-As a workaround for this problem, Perl 5.10.0 introduces 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.
+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>
=head2 Quoting metacharacters
Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
C<\w>, C<\n>. Unlike some other regular expression languages, there
are no backslashed symbols that aren't alphanumeric. So anything
-that looks like \\, \(, \), \<, \>, \{, or \} is always
+that looks like \\, \(, \), \[, \], \{, or \} is always
interpreted as a literal character, not a metacharacter. This was
once used in a common idiom to disable or quote the special meanings
of regular expression metacharacters in a string that you want to
=item C<(?#text)>
X<(?#)>
-A comment. The text is ignored. If the C</x> modifier enables
-whitespace formatting, a simple C<#> will suffice. Note that Perl closes
+A comment. The text is ignored.
+Note that Perl closes
the comment as soon as it sees a C<)>, so there is no way to put a literal
-C<)> in the comment.
+C<)> in the comment. The pattern's closing delimiter must be escaped by
+a backslash if it appears in the comment.
+
+See L</E<sol>x> for another way to have comments in patterns.
=item C<(?adlupimsx-imsx)>
=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>.
In particular, braces do not need to be balanced:
- /abc(?{ f('{'); })/def/
+ s/abc(?{ f('{'); })/def/
Even in a pattern that is interpolated and compiled at run-time, literal
code blocks will be compiled once, at perl compile time; the following
In patterns where the text of the code is derived from run-time
information rather than appearing literally in a source code /pattern/,
the code is compiled at the same time that the pattern is compiled, and
-fro reasons of security, C<use re 'eval'> must be in scope. This is to
+for reasons of security, C<use re 'eval'> must be in scope. This is to
stop user-supplied patterns containing code snippets from being
executable.
-In situations where you need enable this with C<use re 'eval'>, you should
+In situations where you need to enable this with C<use re 'eval'>, you should
also have taint checking enabled. Better yet, use the carefully
constrained evaluation within a Safe compartment. See L<perlsec> for
details about both these mechanisms.
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
\)
}x;
-See also C<(?PARNO)> for a different, more efficient way to accomplish
+See also
+L<C<(?I<PARNO>)>|/(?PARNO) (?-PARNO) (?+PARNO) (?R) (?0)>
+for a different, more efficient way to accomplish
the same task.
Executing a postponed regular expression 50 times without consuming any
input string will result in a fatal error. The maximum depth is compiled
into perl, so changing it requires a custom build.
-=item C<(?PARNO)> C<(?-PARNO)> C<(?+PARNO)> C<(?R)> C<(?0)>
+=item C<(?I<PARNO>)> C<(?-I<PARNO>)> C<(?+I<PARNO>)> C<(?R)> C<(?0)>
X<(?PARNO)> X<(?1)> X<(?R)> X<(?0)> X<(?-1)> X<(?+1)> X<(?-PARNO)> X<(?+PARNO)>
X<regex, recursive> X<regexp, recursive> X<regular expression, recursive>
-X<regex, relative recursion>
+X<regex, relative recursion> X<GOSUB> X<GOSTART>
+
+Recursive subpattern. Treat the contents of a given capture buffer in the
+current pattern as an independent subpattern and attempt to match it at
+the current position in the string. Information about capture state from
+the caller for things like backreferences is available to the subpattern,
+but capture buffers set by the subpattern are not visible to the caller.
Similar to C<(??{ code })> except that it does not involve executing any
code or potentially compiling a returned pattern string; instead it treats
the part of the current pattern contained within a specified capture group
-as an independent pattern that must match at the current position.
-Capture groups contained by the pattern will have the value as determined
-by the outermost recursion.
+as an independent pattern that must match at the current position. Also
+different is the treatment of capture buffers, unlike C<(??{ code })>
+recursive patterns have access to their callers match state, so one can
+use backreferences safely.
-PARNO is a sequence of digits (not starting with 0) whose value reflects
+I<PARNO> is a sequence of digits (not starting with 0) whose value reflects
the paren-number of the capture group to recurse to. C<(?R)> recurses to
the beginning of the whole pattern. C<(?0)> is an alternate syntax for
-C<(?R)>. If PARNO is preceded by a plus or minus sign then it is assumed
+C<(?R)>. If I<PARNO> is preceded by a plus or minus sign then it is assumed
to be relative, with negative numbers indicating preceding capture groups
and positive ones following. Thus C<(?-1)> refers to the most recently
declared group, and C<(?+1)> indicates the next group to be declared.
=item C<(?&NAME)>
X<(?&NAME)>
-Recurse to a named subpattern. Identical to C<(?PARNO)> except that the
+Recurse to a named subpattern. Identical to C<(?I<PARNO>)> except that the
parenthesis to recurse to is determined by name. If multiple parentheses have
the same name, then it recurses to the leftmost.
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:
PAT?+ (?>PAT?)
PAT{min,max}+ (?>PAT{min,max})
+=item C<(?[ ])>
+
+See L<perlrecharclass/Extended Bracketed Character Classes>.
+
=back
=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
For this grouping operator there is no need to describe the ordering, since
only whether or not C<S> can match is important.
-=item C<(??{ EXPR })>, C<(?PARNO)>
+=item C<(??{ EXPR })>, C<(?I<PARNO>)>
The ordering is the same as for the regular expression which is
-the result of EXPR, or the pattern contained by capture group PARNO.
+the result of EXPR, or the pattern contained by capture group I<PARNO>.
=item C<(?(condition)yes-pattern|no-pattern)>
$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