X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2Fre-engine-Plugin.git;a=blobdiff_plain;f=Plugin.pod;h=98633c4fadebf42436e1c8f1643fbb46da846336;hp=227dca36d88994a9fa4a219f3faeaeaee3bc070e;hb=HEAD;hpb=c187b4eea321d890aa957843a259cd6ec0a93470

diff --git a/Plugin.pod b/Plugin.pod
index 227dca3..98633c4 100644
--- a/Plugin.pod
+++ b/Plugin.pod
@@ -4,7 +4,7 @@ re::engine::Plugin - API to write custom regex engines
 
 =head1 VERSION
 
-Version 0.07
+Version 0.12
 
 =head1 DESCRIPTION
 
@@ -45,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
@@ -59,6 +60,7 @@ caller's scope use use the following snippet:
         re::engine::Plugin->import(
             comp => \&comp,
             exec => \&exec,
+            free => \&free,
         );
     }
 
@@ -67,6 +69,7 @@ caller's scope use use the following snippet:
     # Implementation of the engine
     sub comp { ... }
     sub exec { ... }
+    sub free { ... }
 
     1;
 
@@ -96,7 +99,7 @@ not be trapped by an C<eval> 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/;
        }
    );
 
@@ -110,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
@@ -129,11 +138,33 @@ successful, and a false one if it wasn't.
 This callback can also be specified on an individual basis with the
 L</callbacks> 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<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
+L</callbacks> method.
+
 =head1 METHODS
 
 =head2 str
 
-    "str" ~~ /pattern/;
+    "str" =~ /pattern/;
     # in comp/exec/methods:
     my $str = $rx->str;
 
@@ -156,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<imsxp> and the values will be true
@@ -213,8 +244,8 @@ 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 key is currently C<exec>. See L</exec> for more details about
-this callback.
+The only valid keys are currently C<exec> and C<free>. See L</exec> and
+L</free> for more details about these callbacks.
 
 =head2 num_captures
 
@@ -265,7 +296,20 @@ done it'll allow the binding of C<%+> and C<%-> and support the
 L<Tie::Hash> methods FETCH, STORE, DELETE, CLEAR, EXISTS, FIRSTKEY,
 NEXTKEY and SCALAR.
 
-=head1 Tainting
+=head1 CONSTANTS
+
+=head2 C<REP_THREADSAFE>
+
+True iff the module could have been built with thread-safety features
+enabled.
+
+=head2 C<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.
+
+=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
@@ -288,7 +332,7 @@ callbacks:
                     my ($re, $paren) = @_;
 
                     # This is perl's engine doing the match
-                    $str ~~ /(.*)/;
+                    $str =~ /(.*)/;
 
                     # $1 has been untainted
                     return $1;
@@ -326,7 +370,7 @@ this module is responsible for how and if it untaints its variables.
 
 L<perlreapi>, L<Taint::Util>
 
-=head1 TODO / CAVEATS
+=head1 TODO & CAVEATS
 
 I<here be dragons>
 
@@ -419,6 +463,15 @@ tests.
 
 =back
 
+=head1 DEPENDENCIES
+
+L<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.
+
+L<XSLoader> (standard since perl 5.6.0).
+
 =head1 BUGS
 
 Please report any bugs that aren't already listed at
@@ -433,9 +486,9 @@ Vincent Pit C<< <perl at profvince.com> >>
 
 =head1 LICENSE
 
-Copyright 2007-2008 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason.
+Copyright 2007,2008 E<AElig>var ArnfjE<ouml>rE<eth> 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.