view release on metacpan or  search on metacpan

lib/POD2/RU/perlreapi.pod  view on Meta::CPAN

C<re::regnames_count>, if any.  The first two will be combined with
C<RXapif_ONE> or C<RXapif_ALL>.

    RXapif_REGNAME
    RXapif_REGNAMES
    RXapif_REGNAMES_COUNT

Internally C<%+> and C<%-> are implemented with a real tied interface
via L<Tie::Hash::NamedCapture>.  The methods in that package will call
back into these functions.  However the usage of
L<Tie::Hash::NamedCapture> for this purpose might change in future
releases.  For instance this might be implemented by magic instead
(would need an extension to mgvtbl).

=head3 named_buff

    SV*     (*named_buff) (pTHX_ REGEXP * const rx, SV * const key,
                           SV * const value, U32 flags);

=head3 named_buff_iter

    SV*     (*named_buff_iter) (pTHX_
                                REGEXP * const rx,
                                const SV * const lastkey,
                                const U32 flags);

=head2 qr_package

    SV* qr_package(pTHX_ REGEXP * const rx);

The package the qr// magic object is blessed into (as seen by C<ref
qr//>).  It is recommended that engines change this to their package
name for identification regardless of if they implement methods
on the object.

The package this method returns should also have the internal
C<Regexp> package in its C<@ISA>.  C<< qr//->isa("Regexp") >> should always
be true regardless of what engine is being used.

Example implementation might be:

    SV*
    Example_qr_package(pTHX_ REGEXP * const rx)
    {
    	PERL_UNUSED_ARG(rx);
    	return newSVpvs("re::engine::Example");
    }

Any method calls on an object created with C<qr//> will be dispatched to the
package as a normal object.

    use re::engine::Example;
    my $re = qr//;
    $re->meth; # dispatched to re::engine::Example::meth()

To retrieve the C<REGEXP> object from the scalar in an XS function use
the C<SvRX> macro, see L<"REGEXP Functions" in perlapi|perlapi/REGEXP
Functions>.

    void meth(SV * rv)
    PPCODE:
        REGEXP * re = SvRX(sv);

=head2 dupe

    void* dupe(pTHX_ REGEXP * const rx, CLONE_PARAMS *param);

On threaded builds a regexp may need to be duplicated so that the pattern
can be used by multiple threads.  This routine is expected to handle the
duplication of any private data pointed to by the C<pprivate> member of
the C<regexp> structure.  It will be called with the preconstructed new
C<regexp> structure as an argument, the C<pprivate> member will point at
the B<old> private structure, and it is this routine's responsibility to
construct a copy and return a pointer to it (which Perl will then use to
overwrite the field as passed to this routine.)

This allows the engine to dupe its private data but also if necessary
modify the final structure if it really must.

On unthreaded builds this field doesn't exist.

=head2 op_comp

This is private to the Perl core and subject to change. Should be left
null.

=head1 The REGEXP structure

The REGEXP struct is defined in F<regexp.h>.
All regex engines must be able to
correctly build such a structure in their L</comp> routine.

The REGEXP structure contains all the data that Perl needs to be aware of
to properly work with the regular expression.  It includes data about
optimisations that Perl can use to determine if the regex engine should
really be used, and various other control info that is needed to properly
execute patterns in various contexts, such as if the pattern anchored in
some way, or what flags were used during the compile, or if the
program contains special constructs that Perl needs to be aware of.

In addition it contains two fields that are intended for the private
use of the regex engine that compiled the pattern.  These are the
C<intflags> and C<pprivate> members.  C<pprivate> is a void pointer to
an arbitrary structure, whose use and management is the responsibility
of the compiling engine.  Perl will never modify either of these
values.

    typedef struct regexp {
        /* what engine created this regexp? */
        const struct regexp_engine* engine;

        /* what re is this a lightweight copy of? */
        struct regexp* mother_re;

        /* Information about the match that the Perl core uses to manage
         * things */
        U32 extflags;   /* Flags used both externally and internally */
	I32 minlen;	/* mininum possible number of chars in */
                           string to match */
	I32 minlenret;	/* mininum possible number of chars in $& */
        U32 gofs;       /* chars left of pos that we search from */