Enable free callbcks

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

diff --git a/Plugin.pod b/Plugin.pod
index ea371cda66b2f691e797ccf251a6967d83a3bfee..e69c8f4b45c4299972b6abdec8ba4f51aa43b9a1 100644 (file)
--- a/Plugin.pod
+++ b/Plugin.pod
@@ -4,7 +4,7 @@ re::engine::Plugin - API to write custom regex engines
 
 =head1 VERSION
 
-Version 0.09
+Version 0.10
 
 =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;
 
@@ -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,6 +138,28 @@ 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
@@ -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