3 re::engine::Plugin - Pure-Perl regular expression engine plugin interface
8 use re::engine::Plugin (
10 my ($re) = @_; # A re::engine::Plugin object
12 # return value ignored
17 # We always like ponies!
18 return 1 if $str eq 'pony';
27 As of perl 5.9.5 it's possible lexically replace perl's built-in
28 regular expression engine (see L<perlreguts|perlreguts/"Pluggable
29 Interface">). This module provides glue for writing such a wrapper in
30 Perl instead of the provided C/XS interface.
32 B<NOTE>: This module is a development release that does not work with
33 any version of perl other than the current (as of February 2007)
34 I<blead>. The provided interface is not a complete wrapper around the
35 native interface (yet!) but the parts that are left can be implemented
36 with additional methods so the completed API shouldn't have any major
43 Takes a list of key-value pairs with the only mandatory pair being
44 L</exec> and its callback routine. Both subroutine references and the
45 string name of a subroutine (e.g. C<"main::exec">) can be
46 specified. The real CODE ref is currently looked up in the symbol
47 table in the latter case.
53 An optional sub to be called when a pattern is being compiled, note
54 that a single pattern may be compiled more than once by perl.
56 The subroutine will be called with a regexp object (see L</Regexp
57 object>). The regexp object will be stored internally along with the
58 pattern and provided as the first argument for the other callback
59 routines (think of it as C<$self>).
61 If your regex implementation needs to validate its pattern this is the
62 right place to B<croak> on an invalid one (but see L</BUGS>).
64 The return value of this subroutine is discarded.
68 Called when a given pattern is being executed, the first argument is
69 the regexp object and the second is the string being matched. The
70 routine should return true if the pattern matched and false if it
89 =item numbered_buff_get
101 L<perlop/"/PATTERN/cgimosx">
109 Provide an API for named (C<$+{name}>) and unnamed (C<$1, $2, ...>)
110 match variables, allow specifying both offsets into the pattern and
115 Find some neat example for the L</SYNOPSIS>, suggestions welcome.
121 Please report any bugs that aren't already listed at
122 L<http://rt.cpan.org/Dist/Display.html?Queue=re-engine-Plugin> to
123 L<http://rt.cpan.org/Public/Bug/Report.html?Queue=re-engine-Plugin>
129 Calling C<die> or anything that uses it (such as C<carp>) in the
130 L</comp> callback routines will not be trapped by an C<eval> block
131 that the pattern is in, i.e.
134 use re::engine::Plugin(
137 croak "Your pattern is invalid"
138 unless $re->pattern =~ /pony/;
142 # Ignores the eval block
143 eval { /you die in C<eval>, you die for real/ };
145 Simply put this happens because the real subroutine call happens
146 indirectly and not in the scope of the C<eval> block.
152 The regexp object is passed around as the first argument to all the
153 callback routines, it supports the following method calls (with more
160 Returns the pattern this regexp was compiled with.
164 Returns a string of flags the pattern was compiled
165 with. (e.g. C<"xs">). The flags are not guarenteed to be in any
166 particular order, so don't depend on the current one.
170 Returns or sets a user-defined stash that's passed around with the
171 pattern, this is useful for passing around an arbitary scalar between
172 callback routines, example:
174 use re::engine::Plugin (
175 comp => sub { $_[0]->stash( [ 1 .. 5 ] ) },
176 comp => sub { $_[0]->stash }, # Get [ 1 .. 5]
181 The minimum length a given string must be to match the pattern, set
182 this to an integer in B<comp> and perl will not call your B<exec>
183 routine unless the string being matched as at least that long. Returns
184 the currently set length if not called with any arguments or C<undef>
185 if no length has been set.
191 L<perlreguts/Pluggable Interface>
195 Yves explaining why I made the regexp engine a sad panda.
199 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason <avar@cpan.org>
203 This program is free software; you can redistribute it and/or modify it
204 under the same terms as Perl itself.
206 Copyright 2007 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason.