improve regexec_flags() API documentation

In the API, rename the 'screamer' arg to be 'sv' instead;
update the description of the functions args;
improve the documentation of the REXEC_* flags for the 'flags' arg.

4 files changed, 24 insertions, 19 deletions

diff --git a/perl.h b/perl.h
index 883042413d..bdb64b3a73 100644
--- a/perl.h
+++ b/perl.h
@@ -221,9 +221,9 @@
 #define CALLREGCOMP(sv, flags) Perl_pregcomp(aTHX_ (sv),(flags))
 
 #define CALLREGCOMP_ENG(prog, sv, flags) (prog)->comp(aTHX_ sv, flags)
-#define CALLREGEXEC(prog,stringarg,strend,strbeg,minend,screamer,data,flags) \
+#define CALLREGEXEC(prog,stringarg,strend,strbeg,minend,sv,data,flags) \
     RX_ENGINE(prog)->exec(aTHX_ (prog),(stringarg),(strend), \
-        (strbeg),(minend),(screamer),(data),(flags))
+        (strbeg),(minend),(sv),(data),(flags))
 #define CALLREG_INTUIT_START(prog,sv,strbeg,strpos,strend,flags,data) \
     RX_ENGINE(prog)->intuit(aTHX_ (prog), (sv), (strbeg), (strpos), \
         (strend),(flags),(data))
diff --git a/pod/perlreapi.pod b/pod/perlreapi.pod
index 222176419f..659088e941 100644
--- a/pod/perlreapi.pod
+++ b/pod/perlreapi.pod
@@ -17,7 +17,7 @@ following format:
                          REGEXP * const rx,
                          char* stringarg,
                          char* strend, char* strbeg,
-                         I32 minend, SV* screamer,
+                         I32 minend, SV* sv,
                          void* data, U32 flags);
         char*   (*intuit) (pTHX_
                            REGEXP * const rx, SV *sv,
@@ -238,7 +238,7 @@ certain optimisations when this is set.
 
     I32 exec(pTHX_ REGEXP * const rx,
              char *stringarg, char* strend, char* strbeg,
-             I32 minend, SV* screamer,
+             I32 minend, SV* sv,
              void* data, U32 flags);
 
 Execute a regexp. The arguments are
@@ -249,9 +249,9 @@ Execute a regexp. The arguments are
 
 The regular expression to execute.
 
-=item screamer
+=item sv
 
-This strangely-named arg is the SV to be matched against.  Note that the
+This is the SV to be matched against.  Note that the
 actual char array to be matched against is supplied by the arguments
 described below; the SV is just used to determine UTF8ness, C<pos()> etc.
 
@@ -262,7 +262,7 @@ Pointer to the physical start of the string.
 =item strend
 
 Pointer to the character following the physical end of the string (i.e.
-the C<\0>).
+the C<\0>, if any).
 
 =item stringarg
 
diff --git a/regexec.c b/regexec.c
index 4a350fb090..5f142a0332 100644
--- a/regexec.c
+++ b/regexec.c
@@ -2211,7 +2211,7 @@ Perl_regexec_flags(pTHX_ REGEXP * const rx, char *stringarg, char *strend,
  *            itself is accessed via the pointers above */
 /* data:      May be used for some additional optimizations.
               Currently unused. */
-/* nosave:    For optimizations. */
+/* flags:     For optimizations. See REXEC_* in regexp.h */
 
 {
     dVAR;
diff --git a/regexp.h b/regexp.h
index 65c2d38517..9c8fd30225 100644
--- a/regexp.h
+++ b/regexp.h
@@ -155,7 +155,7 @@ typedef struct re_scream_pos_data_s
 typedef struct regexp_engine {
     REGEXP* (*comp) (pTHX_ SV * const pattern, U32 flags);
     I32     (*exec) (pTHX_ REGEXP * const rx, char* stringarg, char* strend,
-                     char* strbeg, I32 minend, SV* screamer,
+                     char* strbeg, I32 minend, SV* sv,
                      void* data, U32 flags);
     char*   (*intuit) (pTHX_
                         REGEXP * const rx,
@@ -537,16 +537,21 @@ get_regex_charset_name(const U32 flags, STRLEN* const lenp)
 /* Whether the pattern stored at RX_WRAPPED is in UTF-8  */
 #define RX_UTF8(prog)			SvUTF8(prog)
 
-#define REXEC_COPY_STR	0x01		/* Need to copy the string. */
-#define REXEC_CHECKED	0x02		/* check_substr already checked. */
-#define REXEC_SCREAM	0x04		/* use scream table. */
-#define REXEC_IGNOREPOS	0x08		/* \G matches at start. */
-#define REXEC_NOT_FIRST	0x10		/* This is another iteration of //g. */
-                                    /* under REXEC_COPY_STR, it's ok for the
-                                     * engine (modulo PL_sawamperand etc)
-                                     * to skip copying ... */
-#define REXEC_COPY_SKIP_PRE  0x20   /* ...the $` part of the string, or */
-#define REXEC_COPY_SKIP_POST 0x40   /* ...the $' part of the string */
+
+/* bits in flags arg of Perl_regexec_flags() */
+
+#define REXEC_COPY_STR  0x01    /* Need to copy the string for captures. */
+#define REXEC_CHECKED   0x02    /* re_intuit_start() already called. */
+#define REXEC_SCREAM    0x04    /* currently unused. */
+#define REXEC_IGNOREPOS 0x08    /* use stringarg, not pos(), for \G match */
+#define REXEC_NOT_FIRST 0x10    /* This is another iteration of //g:
+                                   no need to copy string again */
+
+                                     /* under REXEC_COPY_STR, it's ok for the
+                                        engine (modulo PL_sawamperand etc)
+                                        to skip copying: ... */
+#define REXEC_COPY_SKIP_PRE  0x20    /* ...the $` part of the string, or */
+#define REXEC_COPY_SKIP_POST 0x40    /* ...the $' part of the string */
 #define REXEC_FAIL_ON_UNDERFLOW 0x80 /* fail the match if $& would start before
                                         the start pos (so s/.\G// would fail
                                         on second iteration */