NAME
re::engine::Plugin - API to write custom regex engines
+VERSION
+ Version 0.12
+
DESCRIPTION
As of perl 5.9.5 it's possible to lexically replace perl's built-in
regular expression engine with your own (see perlreapi and perlpragma).
use re::engine::Plugin (
comp => sub {},
exec => sub {},
+ free => sub {},
);
To write a custom engine which imports your functions into the caller's
re::engine::Plugin->import(
comp => \&comp,
exec => \&exec,
+ free => \&free,
);
}
# Implementation of the engine
sub comp { ... }
sub exec { ... }
+ sub free { ... }
1;
comp => sub {
my $rx = shift;
croak "Your pattern is invalid"
- unless $rx->pattern ~~ /pony/;
+ unless $rx->pattern =~ /pony/;
}
);
pattern such as "/(/".
exec
- exec => sub {
- my ($rx, $str) = @_;
+ my $ponies;
+ use re::engine::Plugin(
+ exec => sub {
+ my ($rx, $str) = @_;
- # We always like ponies!
- return 1 if $str ~~ /pony/;
+ # We always like ponies!
+ if ($str =~ /pony/) {
+ $ponies++;
+ return 1;
+ }
- # Failed to match
- return;
- }
+ # Failed to match
+ return;
+ }
+ );
Called when a regex is being executed, i.e. when it's being matched
against something. The scalar being matched against the pattern is
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
+ "callbacks" method.
+
+ free
+ use re::engine::Plugin(
+ free => sub {
+ my ($rx) = @_;
+
+ say 'matched ' ($ponies // 'no')
+ . ' pon' . ($ponies > 1 ? 'ies' : 'y');
+
+ return;
+ }
+ );
+
+ Called when the regexp structure is freed by the perl interpreter. Note
+ that this happens pretty late in the destruction process, but still
+ before global destruction kicks in. The only argument this callback
+ receives is the "re::engine::Plugin" object associated with the regexp,
+ and its return value is ignored.
+
+ This callback can also be specified on an individual basis with the
+ "callbacks" method.
+
METHODS
str
- "str" ~~ /pattern/;
+ "str" =~ /pattern/;
# in comp/exec/methods:
my $str = $rx->str;
mod
my %mod = $rx->mod;
- say "has /ix" if %mod ~~ 'i' and %mod ~~ 'x';
+ say "has /ix" if %mod =~ 'i' and %mod =~ 'x';
A key-value pair list of the modifiers the pattern was compiled with.
The keys will zero or more of "imsxp" and the values will be true values
The length specified will be used as a a byte length (using SvPV), not a
character length.
+ nparens
+ gofs
+ 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 keys are currently "exec" and "free". See "exec" and
+ "free" for more details about these callbacks.
+
num_captures
$re->num_captures(
FETCH => sub {
methods FETCH, STORE, DELETE, CLEAR, EXISTS, FIRSTKEY, NEXTKEY and
SCALAR.
-Tainting
+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
my ($re, $paren) = @_;
# This is perl's engine doing the match
- $str ~~ /(.*)/;
+ $str =~ /(.*)/;
# $1 has been untainted
return $1;
SEE ALSO
perlreapi, Taint::Util
-TODO / CAVEATS
+TODO & CAVEATS
*here be dragons*
* Engines implemented with this module don't support "s///" and "split
checkstr callbacks are called. Write wrappers around them and add
tests.
+DEPENDENCIES
+ perl 5.10.
+
+ A C compiler. This module may happen to build with a C++ compiler as
+ well, but don't rely on it, as no guarantee is made in this regard.
+
+ XSLoader (standard since perl 5.6.0).
+
BUGS
Please report any bugs that aren't already listed at
<http://rt.cpan.org/Dist/Display.html?Queue=re-engine-Plugin> to
<http://rt.cpan.org/Public/Bug/Report.html?Queue=re-engine-Plugin>
AUTHORS
-
Ævar Arnfjörð Bjarmason "<avar at cpan.org>"
+
Ævar Arnfjörð Bjarmason "<avar at cpan.org>"
Vincent Pit "<perl at profvince.com>"
LICENSE
- Copyright 2007-2008 Ævar Arnfjörð Bjarmason.
+ Copyright 2007,2008 Ævar Arnfjörð Bjarmason.
- Copyright 2009 Vincent Pit.
+ Copyright 2009,2010,2011,2013,2014,2015 Vincent Pit.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
projects / perl / modules / re-engine-Plugin.git / blobdiff