perlexperiment: document the private_use experiment

[perl5.git] / pod / perlreapi.pod

diff --git a/pod/perlreapi.pod b/pod/perlreapi.pod
index c4e30cb..790e3fd 100644 (file)
--- 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,
+                         SSize_t minend, SV* sv,
                          void* data, U32 flags);
         char*   (*intuit) (pTHX_
                            REGEXP * const rx, SV *sv,
@@ -97,7 +97,7 @@ stringify everything using the snippet above, but that doesn't mean
 other engines have to.
 
 The C<flags> parameter is a bitfield which indicates which of the
-C<msixp> flags the regex was compiled with.  It also contains
+C<msixpn> flags the regex was compiled with.  It also contains
 additional info, such as if C<use locale> is in effect.
 
 The C<eogc> flags are stripped out before being passed to the comp
@@ -143,7 +143,7 @@ TODO: Document this
 
 =item Character set
 
-The character set semantics are determined by an enum that is contained
+The character set rules are determined by an enum that is contained
 in this field.  This is still experimental and subject to change, but
 the current interface returns the rules by use of the in-line function
 C<get_regex_charset(const U32 flags)>.  The only currently documented
@@ -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,
+             SSize_t 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
 
@@ -336,7 +336,7 @@ Perl will handle releasing anything else contained in the C<regexp> structure.
 =head2 Numbered capture callbacks
 
 Called to get/set the value of C<$`>, C<$'>, C<$&> and their named
-equivalents, ${^PREMATCH}, ${^POSTMATCH} and $^{MATCH}, as well as the
+equivalents, ${^PREMATCH}, ${^POSTMATCH} and ${^MATCH}, as well as the
 numbered capture groups (C<$1>, C<$2>, ...).
 
 The C<paren> parameter will be C<1> for C<$1>, C<2> for C<$2> and so
@@ -418,7 +418,7 @@ doesn't have to modify the value.  This is exactly how tied variables
 behave in the same situation:
 
     package CaptureVar;
-    use base 'Tie::Scalar';
+    use parent 'Tie::Scalar';
 
     sub TIESCALAR { bless [] }
     sub FETCH { undef }
@@ -624,7 +624,6 @@ values.
          * matching*/
         U32 lastparen;            /* highest close paren matched ($+) */
         U32 lastcloseparen;       /* last close paren matched ($^N) */
-        regexp_paren_pair *swap;  /* Swap copy of *offs */
         regexp_paren_pair *offs;  /* Array of offsets for (@-) and
                                      (@+) */
 
@@ -666,7 +665,7 @@ pointed to by C<RE_ENGINE_PTR>.
 
 =head2 C<mother_re>
 
-TODO, see L<http://www.mail-archive.com/perl5-changes@perl.org/msg17328.html>
+TODO, see commit 28d8d7f41a.
 
 =head2 C<extflags>
 
@@ -711,9 +710,10 @@ used in the future for all engines for optimisations.
 
 =head2 C<nparens>, C<lastparen>, and C<lastcloseparen>
 
-These fields are used to keep track of how many paren groups could be matched
-in the pattern, which was the last open paren to be entered, and which was
-the last close paren to be entered.
+These fields are used to keep track of: how many paren capture groups
+there are in the pattern; which was the highest paren to be closed (see
+L<perlvar/$+>); and which was the most recent paren to be closed (see
+L<perlvar/$^N>).
 
 =head2 C<intflags>
 
@@ -727,10 +727,6 @@ data structure.  The Perl engine uses the
 C<regexp_internal> structure (see L<perlreguts/Base Structures>) but a custom
 engine should use something else.
 
-=head2 C<swap>
-
-Unused.  Left in for compatibility with Perl 5.10.0.
-
 =head2 C<offs>
 
 A C<regexp_paren_pair> structure which defines offsets into the string being
@@ -745,7 +741,7 @@ C<regexp_paren_pair> struct is defined as follows:
 If C<< ->offs[num].start >> or C<< ->offs[num].end >> is C<-1> then that
 capture group did not match.
 C<< ->offs[0].start/end >> represents C<$&> (or
-C<${^MATCH}> under C<//p>) and C<< ->offs[paren].end >> matches C<$$paren> where
+C<${^MATCH}> under C</p>) and C<< ->offs[paren].end >> matches C<$$paren> where
 C<$paren >= 1>.
 
 =head2 C<precomp> C<prelen>
@@ -825,7 +821,7 @@ purposes when embedding compiled regexes into larger patterns with C<qr//>.
 
 The number of times the structure is referenced.  When
 this falls to 0, the regexp is automatically freed
-by a call to pregfree.  This should be set to 1 in
+by a call to C<pregfree>.  This should be set to 1 in
 each engine's L</comp> routine.
 
 =head1 HISTORY