Plugin.pod

   1 =head1 NAME
   2
   3 re::engine::Plugin - Pure-Perl regular expression engine plugin interface
   4
   5 =head1 SYNOPSIS
   6
   7     use feature ':5.10';
   8     use re::engine::Plugin (
   9         comp => sub {
  10             my ($re) = @_; # A re::engine::Plugin object
  11
  12             # return value ignored
  13         },
  14         exec => sub {
  15             my ($re, $str) = @_;
  16
  17            # We always like ponies!
  18            return 1 if $str eq 'pony';
  19            return;
  20         }
  21     );
  22
  23     "pony" =~ /yummie/;
  24
  25 =head1 DESCRIPTION
  26
  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.
  31
  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
  37 changes.
  38
  39 =head1 METHODS
  40
  41 =head2 import
  42
  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.
  48
  49 =over 4
  50
  51 =item comp
  52
  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.
  55
  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>).
  60
  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>).
  63
  64 The return value of this subroutine is discarded.
  65
  66 =item exec
  67
  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
  71 didn't.
  72
  73 =item intuit
  74
  75 TODO: implement
  76
  77 =item checkstr
  78
  79 TODO: implement
  80
  81 =item free
  82
  83 TODO: implement
  84
  85 =item dupe
  86
  87 TODO: implement
  88
  89 =item numbered_buff_get
  90
  91 TODO: implement
  92
  93 =item named_buff_get
  94
  95 TODO: implement
  96
  97 =back
  98
  99 =head2 flags
 100
 101 L<perlop/"/PATTERN/cgimosx">
 102
 103 =head1 TODO
 104
 105 =over
 106
 107 =item *
 108
 109 Provide an API for named (C<$+{name}>) and unnamed (C<$1, $2, ...>)
 110 match variables, allow specifying both offsets into the pattern and
 111 any given scalar.
 112
 113 =item *
 114
 115 Find some neat example for the L</SYNOPSIS>, suggestions welcome.
 116
 117 =back
 118
 119 =head1 BUGS
 120
 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>
 124
 125 =over 1
 126
 127 =item
 128
 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.
 132
 133    use Carp qw(croak);
 134    use re::engine::Plugin(
 135        comp => sub {
 136            my $re = shift;
 137            croak "Your pattern is invalid"
 138                unless $re->pattern =~ /pony/;
 139        }
 140    );
 141
 142    # Ignores the eval block
 143    eval { /you die in C<eval>, you die for real/ };
 144
 145 Simply put this happens because the real subroutine call happens
 146 indirectly and not in the scope of the C<eval> block.
 147
 148 =back
 149
 150 =head1 Regexp object
 151
 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
 154 to come!).
 155
 156 =over
 157
 158 =item pattern
 159
 160 Returns the pattern this regexp was compiled with.
 161
 162 =item flags
 163
 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.
 167
 168 =item stash
 169
 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:
 173
 174     use re::engine::Plugin (
 175         comp => sub { $_[0]->stash( [ 1 .. 5 ] ) },
 176         comp => sub { $_[0]->stash }, # Get [ 1 .. 5]
 177     );
 178
 179 =item minlen
 180
 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.
 186
 187 =back
 188
 189 =head1 SEE ALSO
 190
 191 L<perlreguts/Pluggable Interface>
 192
 193 =head1 THANKS
 194
 195 Yves explaining why I made the regexp engine a sad panda.
 196
 197 =head1 AUTHOR
 198
 199 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason <avar@cpan.org>
 200
 201 =head1 LICENSE
 202
 203 This program is free software; you can redistribute it and/or modify it
 204 under the same terms as Perl itself.
 205
 206 Copyright 2007 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason.
 207
 208 =cut