view release on metacpan or  search on metacpan

README  view on Meta::CPAN

                return 123;
            },
        );

    Takes a list of key-value pairs of names and subroutines that implement
    numbered capture variables. "FETCH" will be called on value retrieval
    ("say $1"), "STORE" on assignment ("$1 = "ook"") and "LENGTH" on "length
    $1".

    The second paramater of each routine is the paren number being
    requested/stored, the following mapping applies for those numbers:

        -2 => $` or ${^PREMATCH}
        -1 => $' or ${^POSTMATCH}
         0 => $& or ${^MATCH}
         1 => $1
         # ...

    Assignment to capture variables makes it possible to implement something
    like Perl 6 ":rw" semantics, and since it's possible to make the capture
    variables return any scalar instead of just a string it becomes possible
    to implement Perl 6 match object semantics (to name an example).

  named_captures
    TODO: implement

    perl internals still needs to be changed to support this but when it's
    done it'll allow the binding of "%+" and "%-" and support the Tie::Hash
    methods FETCH, STORE, DELETE, CLEAR, EXISTS, FIRSTKEY, NEXTKEY and
    SCALAR.

CONSTANTS
  "REP_THREADSAFE"
    True iff the module could have been built with thread-safety features
    enabled.

  "REP_FORKSAFE"
    True iff this module could have been built with fork-safety features
    enabled. This will always be true except on Windows where it's false for
    perl 5.10.0 and below.

TAINTING
    The only way to untaint an existing variable in Perl is to use it as a
    hash key or referencing subpatterns from a regular expression match (see
    perlsec), the latter only works in perl's regex engine because it
    explicitly untaints capture variables which a custom engine will also
    need to do if it wants its capture variables to be untanted.

    There are basically two ways to go about this, the first and obvious one
    is to make use of Perl'l lexical scoping which enables the use of its
    built-in regex engine in the scope of the overriding engine's callbacks:

        use re::engine::Plugin (
            exec => sub {
                my ($re, $str) = @_; # $str is tainted

                $re->num_captures(
                    FETCH => sub {
                        my ($re, $paren) = @_;

                        # This is perl's engine doing the match
                        $str =~ /(.*)/;

                        # $1 has been untainted
                        return $1;
                    },
                );
            },
        );

    The second is to use something like Taint::Util which flips the taint
    flag on the scalar without invoking the perl's regex engine:

        use Taint::Util;
        use re::engine::Plugin (
            exec => sub {
                my ($re, $str) = @_; # $str is tainted

                $re->num_captures(
                    FETCH => sub {
                        my ($re, $paren) = @_;

                        # Copy $str and untaint the copy
                        untaint(my $ret = $str);

                        # Return the untainted value
                        return $ret;
                    },
                );
            },
        );

    In either case a regex engine using perl's regex api or this module is
    responsible for how and if it untaints its variables.

SEE ALSO
    perlreapi, Taint::Util

TODO & CAVEATS
    *here be dragons*

    *   Engines implemented with this module don't support "s///" and "split
        //", the appropriate parts of the "REGEXP" struct need to be wrapped
        and documented.

    *   Still not a complete wrapper for perlreapi in other ways, needs
        methods for some "REGEXP" struct members, some callbacks aren't
        implemented etc.

    *   Support overloading operations on the "qr//" object, this allow
        control over the of "qr//" objects in a manner that isn't limited by
        "wrapped"/"wraplen".

            $re->overload(
                '""'  => sub { ... },
                '@{}' => sub { ... },
                ...
            );

    *   Support the dispatch of arbitary methods from the re::engine::Plugin
        qr// object to user defined subroutines via AUTOLOAD;