re::engine::Plugin - API to write custom regex engines
-=head1 NOTICE
-
-This is a B<developer release> that requires a patch to blead to work,
-the patch can be found in F<named_capture.patch> in this distribution.
-
=head1 DESCRIPTION
As of perl 5.9.5 it's possible to lexically replace perl's built-in
depending on variable interpolation etc.
When this module is loaded into a scope it inserts a hook into
-C<$^H{regcomp}> (as described in L<perlreapi>) to have each regexp
-constructed in its lexical scope handled by this engine, but it
-differs from other engines in that it also inserts other hooks into
-C<%^H> in the same scope that point to user-defined subroutines to use
-during compilation, execution etc, these are described in
-L</CALLBACKS> below.
+C<$^H{regcomp}> (as described in L<perlreapi> and L<perlpragma>) to
+have each regexp constructed in its lexical scope handled by this
+engine, but it differs from other engines in that it also inserts
+other hooks into C<%^H> in the same scope that point to user-defined
+subroutines to use during compilation, execution etc, these are
+described in L</CALLBACKS> below.
The callbacks (e.g. L</comp>) then get called with a
L<re::engine::Plugin> object as their first argument. This object
sub import
{
- # Populates the caller's %^H with our callbacks
+ # Sets the caller's $^H{regcomp} his %^H with our callbacks
re::engine::Plugin->import(
comp => \&comp,
exec => \&exec,
method. The routine should return a true value if the match was
successful, and a false one if it wasn't.
+This callback can also be specified on an individual basis with the
+L</callbacks> method.
+
=head1 METHODS
=head2 str
The length specified will be used as a a byte length (using
L<SvPV|perlapi/SvPV>), not a character length.
+=head2 callbacks
+
+ # A dumb regexp engine that just tests string equality
+ use re::engine::Plugin comp => sub {
+ my ($re) = @_;
+
+ my $pat = $re->pattern;
+
+ $re->callbacks(
+ exec => sub {
+ my ($re, $str) = @_;
+ return $pat eq $str;
+ },
+ );
+ };
+
+Takes a list of key-value pairs of names and subroutines, and replace the
+callback currently attached to the regular expression for the type given as
+the key by the code reference passed as the corresponding value.
+
+The only valid key is currently C<exec>. See L</exec> for more details about
+this callback.
+
=head2 num_captures
$re->num_captures(
=head2 named_captures
-B<TODO>: document
+B<TODO>: implement
-This is implemented but not documented, see F<t/named_buff> for usage
-examples.
+perl internals still needs to be changed to support this but when it's
+done it'll allow the binding of C<%+> and C<%-> and support the
+L<Tie::Hash> methods FETCH, STORE, DELETE, CLEAR, EXISTS, FIRSTKEY,
+NEXTKEY and SCALAR.
=head1 Tainting
=item *
-Export constants defined as macros in core relevant to our interests,
-e.g. PMf_ stuff and things needed by extflags.
-
-=item *
-
Engines implemented with this module don't support C<s///> and C<split
//>, the appropriate parts of the C<REGEXP> struct need to be wrapped
and documented.
L<http://rt.cpan.org/Dist/Display.html?Queue=re-engine-Plugin> to
L<http://rt.cpan.org/Public/Bug/Report.html?Queue=re-engine-Plugin>
-=head1 AUTHOR
+=head1 AUTHORS
-E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason <avar@cpan.org>
+E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason C<< <avar at cpan.org> >>
+
+Vincent Pit C<< <perl at profvince.com> >>
=head1 LICENSE
-Copyright 2007 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason.
+Copyright 2007-2008 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason.
+
+Copyright 2009 Vincent Pit.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.