Add support for /k modfier for matching along with ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH}

Message-ID: <9b18b3110701111731x29b1c63i57b1698f769b3bbc@mail.gmail.com>
(with tweaks)

p4raw-id: //depot/perl@29831

3 files changed, 52 insertions, 9 deletions

diff --git a/pod/perlop.pod b/pod/perlop.pod
index 46af19b230..7b84a683ac 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -1067,7 +1067,7 @@ X<m> X<operator, match>
 X<regexp, options> X<regexp> X<regex, options> X<regex>
 X</c> X</i> X</m> X</o> X</s> X</x>
 
-=item /PATTERN/cgimosx
+=item /PATTERN/cgimosxk
 
 Searches a string for a pattern match, and in scalar context returns
 true if it succeeds, false if it fails.  If no string is specified
@@ -1080,13 +1080,15 @@ is in effect.
 
 Options are:
 
-    c	Do not reset search position on a failed match when /g is in effect.
-    g	Match globally, i.e., find all occurrences.
     i	Do case-insensitive pattern matching.
     m	Treat string as multiple lines.
-    o	Compile pattern only once.
     s	Treat string as single line.
     x	Use extended regular expressions.
+    g	Match globally, i.e., find all occurrences.
+    c	Do not reset search position on a failed match when /g is in effect.
+    o	Compile pattern only once.
+    k	Keep a copy of the matched string so that ${^MATCH} and friends
+	will be defined.
 
 If "/" is the delimiter then the initial C<m> is optional.  With the C<m>
 you can use any pair of non-alphanumeric, non-whitespace characters
@@ -1449,7 +1451,7 @@ put comments into a multi-line C<qw>-string.  For this reason, the
 C<use warnings> pragma and the B<-w> switch (that is, the C<$^W> variable)
 produces warnings if the STRING contains the "," or the "#" character.
 
-=item s/PATTERN/REPLACEMENT/egimosx
+=item s/PATTERN/REPLACEMENT/egimosxk
 X<substitute> X<substitution> X<replace> X<regexp, replace>
 X<regexp, substitute> X</e> X</g> X</i> X</m> X</o> X</s> X</x>
 
@@ -1475,13 +1477,16 @@ when C<use locale> is in effect.
 
 Options are:
 
-    e	Evaluate the right side as an expression.
-    g	Replace globally, i.e., all occurrences.
     i	Do case-insensitive pattern matching.
     m	Treat string as multiple lines.
-    o	Compile pattern only once.
     s	Treat string as single line.
     x	Use extended regular expressions.
+    g	Replace globally, i.e., all occurrences.
+    o	Compile pattern only once.
+    k	Keep a copy of the original string so ${^MATCH} and friends
+	will be defined.
+    e	Evaluate the right side as an expression.
+
 
 Any non-alphanumeric, non-whitespace delimiter may replace the
 slashes.  If single quotes are used, no interpretation is done on the
diff --git a/pod/perlre.pod b/pod/perlre.pod
index 7133a02c96..d886d094a7 100644
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -586,6 +586,15 @@ already paid the price.  As of 5.005, C<$&> is not so costly as the
 other two.
 X<$&> X<$`> X<$'>
 
+As a workaround for this problem, Perl 5.10 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</k> (keep-copy) 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.
+X</k> X<k modifier>
+
 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
@@ -639,7 +648,7 @@ whitespace formatting, a simple C<#> will suffice.  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.
 
-=item C<(?imsx-imsx)>
+=item C<(?kimsx-imsx)>
 X<(?)>
 
 One or more embedded pattern-match modifiers, to be turned on (or
@@ -667,6 +676,11 @@ will match a repeated (I<including the case>!) word C<blah> in any
 case, assuming 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,
+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
+when executed under C<use warnings>.
+
 =item C<(?:pattern)>
 X<(?:)>
 
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index a211c378ae..b4db654178 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -228,6 +228,14 @@ performance penalty on all regular expression matches.  See L</BUGS>.
 
 See L</@-> for a replacement.
 
+=item ${^MATCH}
+X<${^MATCH}>
+
+This is similar to C<$&> (C<$POSTMATCH>) except that it does not incur the
+performance penalty associated with that variable, and is only guaranteed
+to return a defined value when the pattern was compiled or executed with
+the C</k> modifier.
+
 =item $PREMATCH
 
 =item $`
@@ -243,6 +251,14 @@ performance penalty on all regular expression matches.  See L</BUGS>.
 
 See L</@-> for a replacement.
 
+=item ${^PREMATCH}
+X<${^PREMATCH}>
+
+This is similar to C<$`> ($PREMATCH) except that it does not incur the
+performance penalty associated with that variable, and is only guaranteed
+to return a defined value when the pattern was compiled or executed with
+the C</k> modifier.
+
 =item $POSTMATCH
 
 =item $'
@@ -264,6 +280,14 @@ performance penalty on all regular expression matches.  See L</BUGS>.
 
 See L</@-> for a replacement.
 
+=item ${^POSTMATCH}
+X<${^POSTMATCH}>
+
+This is similar to C<$'> (C<$POSTMATCH>) except that it does not incur the
+performance penalty associated with that variable, and is only guaranteed
+to return a defined value when the pattern was compiled or executed with
+the C</k> modifier.
+
 =item $LAST_PAREN_MATCH
 
 =item $+