mg.c - add support for ${^LAST_SUCCESSFUL_PATTERN}

This exposes the "last successful pattern" as a variable that can be
printed, or used in patterns, or tested for definedness, etc. Many regex
magical variables relate to PL_curpm, which contains the last successful
match.  We never exposed the *pattern* directly, although it was
implicitly available via the "empty pattern".  With this patch it is
exposed explicitly.  This means that if someone embeds a pattern as a
match operator it can then be accessed after the fact much like a qr//
variable would be.

@ether asked if we had this, and I had to say "no", which was a shame as
obviously the code involved isn't very complicated (the docs from this
patch are far larger than the code involved!).  At the very least
this can be useful for debugging and probably testing. It can also
be useful to test if the /is/ a "last successful pattern", by checking
if the var is defined.

1 files changed, 19 insertions, 0 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index ce1a2adec5..4183474c53 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -43,6 +43,25 @@ have a constant target label, and that label is found within the block.
     LABEL: print "This does\n";
   }
 
+=head2 New regexp variable ${^LAST_SUCCESSFUL_PATTERN}
+
+This allows access to the last succesful pattern that matched in the current scope.
+Many aspects of the regex engine refer to the "last successful pattern". The empty
+pattern reuses it, and all of the magic regex vars relate to it. This allows
+access to its pattern. The following code
+
+    if (m/foo/ || m/bar/) {
+        s//PQR/;
+    }
+
+can be rewritten as follows
+
+    if (m/foo/ || m/bar/) {
+        s/${^LAST_SUCCESSFUL_PATTERN}/PQR/;
+    }
+
+and it will do the exactly same thing.
+
 =head1 Security
 
 XXX Any security-related notices go here.  In particular, any security