X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;ds=sidebyside;f=Plugin.pod;h=04189d2609e654c327351b4c19f424f1ce420f2b;hb=c8e0ea7d370e0a09da57acc6ffb139e2d9f010ac;hp=76e8b3a7971423c35c7c1f010701aa4a2b73b21a;hpb=7fb1e66881f572d36b7c22624b7f09672170b990;p=perl%2Fmodules%2Fre-engine-Plugin.git
diff --git a/Plugin.pod b/Plugin.pod
index 76e8b3a..04189d2 100644
--- a/Plugin.pod
+++ b/Plugin.pod
@@ -2,6 +2,10 @@
re::engine::Plugin - API to write custom regex engines
+=head1 VERSION
+
+Version 0.11
+
=head1 DESCRIPTION
As of perl 5.9.5 it's possible to lexically replace perl's built-in
@@ -19,12 +23,12 @@ C or runtime for C patterns, or something inbetween
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) 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 below.
+C<$^H{regcomp}> (as described in L and L) 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 below.
The callbacks (e.g. L) then get called with a
L object as their first argument. This object
@@ -41,6 +45,7 @@ key-value pairs of names and subroutine references:
use re::engine::Plugin (
comp => sub {},
exec => sub {},
+ free => sub {},
);
To write a custom engine which imports your functions into the
@@ -51,10 +56,11 @@ caller's scope use use the following snippet:
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,
+ free => \&free,
);
}
@@ -63,6 +69,7 @@ caller's scope use use the following snippet:
# Implementation of the engine
sub comp { ... }
sub exec { ... }
+ sub free { ... }
1;
@@ -92,7 +99,7 @@ not be trapped by an C block that the pattern is in, i.e.
comp => sub {
my $rx = shift;
croak "Your pattern is invalid"
- unless $rx->pattern ~~ /pony/;
+ unless $rx->pattern =~ /pony/;
}
);
@@ -106,15 +113,21 @@ invalid pattern such as C(/>.
=head2 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
@@ -122,11 +135,36 @@ available as the second argument (C<$str>) and through the L
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 method.
+
+=head2 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 C object associated
+with the regexp, and its return value is ignored.
+
+This callback can also be specified on an individual basis with the
+L method.
+
=head1 METHODS
=head2 str
- "str" ~~ /pattern/;
+ "str" =~ /pattern/;
# in comp/exec/methods:
my $str = $rx->str;
@@ -149,7 +187,7 @@ hashrefs, objects, etc.
=head2 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 C and the values will be true
@@ -182,6 +220,33 @@ called at all.
The length specified will be used as a a byte length (using
L), not a character length.
+=head2 nparens
+
+=head2 gofs
+
+=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 keys are currently C and C. See L and
+L for more details about these callbacks.
+
=head2 num_captures
$re->num_captures(
@@ -231,7 +296,20 @@ done it'll allow the binding of C<%+> and C<%-> and support the
L methods FETCH, STORE, DELETE, CLEAR, EXISTS, FIRSTKEY,
NEXTKEY and SCALAR.
-=head1 Tainting
+=head1 CONSTANTS
+
+=head2 C
+
+True iff the module could have been built with thread-safety features
+enabled.
+
+=head2 C
+
+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.
+
+=head1 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
@@ -254,7 +332,7 @@ callbacks:
my ($re, $paren) = @_;
# This is perl's engine doing the match
- $str ~~ /(.*)/;
+ $str =~ /(.*)/;
# $1 has been untainted
return $1;
@@ -292,7 +370,7 @@ this module is responsible for how and if it untaints its variables.
L, L
-=head1 TODO / CAVEATS
+=head1 TODO & CAVEATS
I
@@ -385,19 +463,32 @@ tests.
=back
+=head1 DEPENDENCIES
+
+L 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.
+
+L (standard since perl 5.6.0).
+
=head1 BUGS
Please report any bugs that aren't already listed at
L to
L
-=head1 AUTHOR
+=head1 AUTHORS
-Evar ArnfjErE Bjarmason
+Evar ArnfjErE Bjarmason C<< >>
+
+Vincent Pit C<< >>
=head1 LICENSE
-Copyright 2007-2008 Evar ArnfjErE Bjarmason.
+Copyright 2007,2008 Evar ArnfjErE Bjarmason.
+
+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.