X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2Fre-engine-Plugin.git;a=blobdiff_plain;f=README;h=c885526b5815dcf18eed8c2d47795b383cd2b541;hp=9da0ecf52406a10dfc133c87339060e5d39465a5;hb=HEAD;hpb=de28b8b2f575972f4c8ccb7f037db6f3b38860cf diff --git a/README b/README index 9da0ecf..c885526 100644 --- a/README +++ b/README @@ -1,6 +1,9 @@ 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). @@ -35,6 +38,7 @@ CALLBACKS use re::engine::Plugin ( comp => sub {}, exec => sub {}, + free => sub {}, ); To write a custom engine which imports your functions into the caller's @@ -49,6 +53,7 @@ CALLBACKS re::engine::Plugin->import( comp => \&comp, exec => \&exec, + free => \&free, ); } @@ -57,6 +62,7 @@ CALLBACKS # Implementation of the engine sub comp { ... } sub exec { ... } + sub free { ... } 1; @@ -84,7 +90,7 @@ CALLBACKS comp => sub { my $rx = shift; croak "Your pattern is invalid" - unless $rx->pattern ~~ /pony/; + unless $rx->pattern =~ /pony/; } ); @@ -97,15 +103,21 @@ CALLBACKS 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 @@ -113,9 +125,33 @@ CALLBACKS 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; @@ -136,7 +172,7 @@ METHODS 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 @@ -167,6 +203,31 @@ METHODS 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 { @@ -213,7 +274,17 @@ METHODS 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 @@ -233,7 +304,7 @@ Tainting my ($re, $paren) = @_; # This is perl's engine doing the match - $str ~~ /(.*)/; + $str =~ /(.*)/; # $1 has been untainted return $1; @@ -270,7 +341,7 @@ Tainting SEE ALSO perlreapi, Taint::Util -TODO / CAVEATS +TODO & CAVEATS *here be dragons* * Engines implemented with this module don't support "s///" and "split @@ -340,20 +411,28 @@ TODO / CAVEATS 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 to AUTHORS - Ævar Arnfjörð Bjarmason "" + Ævar Arnfjörð Bjarmason "" Vincent Pit "" 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.