This is 0.12

[perl/modules/re-engine-Plugin.git] / README

diff --git a/README b/README
index d6e41383509c641683a181a4afc86422ffad33b1..c885526b5815dcf18eed8c2d47795b383cd2b541 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     re::engine::Plugin - API to write custom regex engines
 
 VERSION
-    Version 0.10
+    Version 0.12
 
 DESCRIPTION
     As of perl 5.9.5 it's possible to lexically replace perl's built-in
@@ -38,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
@@ -52,6 +53,7 @@ CALLBACKS
             re::engine::Plugin->import(
                 comp => \&comp,
                 exec => \&exec,
+                free => \&free,
             );
         }
 
@@ -60,6 +62,7 @@ CALLBACKS
         # Implementation of the engine
         sub comp { ... }
         sub exec { ... }
+        sub free { ... }
 
         1;
 
@@ -87,7 +90,7 @@ CALLBACKS
            comp => sub {
                my $rx = shift;
                croak "Your pattern is invalid"
-                   unless $rx->pattern ~~ /pony/;
+                   unless $rx->pattern =~ /pony/;
            }
        );
 
@@ -100,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
@@ -119,9 +128,30 @@ CALLBACKS
     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;
 
@@ -142,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
@@ -195,8 +225,8 @@ METHODS
     given as the key by the code reference passed as the corresponding
     value.
 
-    The only valid key is currently "exec". See "exec" for more details
-    about this callback.
+    The only valid keys are currently "exec" and "free". See "exec" and
+    "free" for more details about these callbacks.
 
   num_captures
         $re->num_captures(
@@ -274,7 +304,7 @@ TAINTING
                         my ($re, $paren) = @_;
 
                         # This is perl's engine doing the match
-                        $str ~~ /(.*)/;
+                        $str =~ /(.*)/;
 
                         # $1 has been untainted
                         return $1;
@@ -402,7 +432,7 @@ AUTHORS
 LICENSE
     Copyright 2007,2008 Ævar Arnfjörð Bjarmason.
 
-    Copyright 2009,2010,2011,2013,2014 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.