X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=fc1ea925bc0f79c1bf561dc4d852dccd171b8876;hb=5c32c65e51fca0ff49c43b814e9653e01b1e56f1;hp=23db4c31adf42365d74062a6f2a5684aeb67b401;hpb=3f061fdc6fe7977e19a17d0a67a161462bf147f2;p=perl%2Fmodules%2FVariable-Magic.git

diff --git a/README b/README
index 23db4c3..fc1ea92 100644
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Variable::Magic - Associate user-defined magic to variables from Perl.
 
 VERSION
-    Version 0.54
+    Version 0.58
 
 SYNOPSIS
         use Variable::Magic qw<wizard cast VMG_OP_INFO_NAME>;
@@ -265,10 +265,17 @@ FUNCTIONS
         Both result in a small performance hit, but just getting the name is
         lighter than getting the op object.
 
-        These callbacks are executed in scalar context and are expected to
-        return an integer, which is then passed straight to the perl magic
-        API. However, only the return value of the *len* magic callback
-        currently holds a meaning.
+        These callbacks are always executed in scalar context. The returned
+        value is coerced into a signed integer, which is then passed
+        straight to the perl magic API. However, note that perl currently
+        only cares about the return value of the *len* magic callback and
+        ignores all the others. Starting with Variable::Magic 0.58, a
+        reference returned from a non-*len* magic callback will not be
+        destroyed immediately but will be allowed to survive until the end
+        of the statement that triggered the magic. This lets you use this
+        return value as a token for triggering a destructor after the
+        original magic action takes place. You can see an example of this
+        technique in the cookbook.
 
     Each callback can be specified as :
 
@@ -501,6 +508,45 @@ COOKBOOK
     Of course, this example does nothing with the values that are added
     after the "cast".
 
+  Delayed magic actions
+    Starting with Variable::Magic 0.58, the return value of the magic
+    callbacks can be used to delay the action until after the original
+    action takes place :
+
+        my $delayed;
+        my $delayed_aux = wizard(
+         data => sub { $_[1] },
+         free => sub {
+          my ($target) = $_[1];
+          my $target_data = &getdata($target, $delayed);
+          local $target_data->{guard} = 1;
+          if (ref $target eq 'SCALAR') {
+           my $orig = $$target;
+           $$target = $target_data->{mangler}->($orig);
+          }
+          return;
+         },
+        );
+        $delayed = wizard(
+         data => sub {
+          return +{ guard => 0, mangler => $_[1] };
+         },
+         set  => sub {
+          return if $_[1]->{guard};
+          my $token;
+          cast $token, $delayed_aux, $_[0];
+          return \$token;
+         },
+        );
+        my $x = 1;
+        cast $x, $delayed => sub { $_[0] * 2 };
+        $x = 2;
+        # $x is now 4
+        # But note that the delayed action only takes place at the end of the
+        # current statement :
+        my @y = ($x = 5, $x);
+        # $x is now 10, but @y is (5, 5)
+
 PERL MAGIC HISTORY
     The places where magic is invoked have changed a bit through perl
     history. Here is a little list of the most recent ones.
@@ -576,11 +622,6 @@ DEPENDENCIES
 
     Carp (core since perl 5), XSLoader (since 5.6.0).
 
-    Copy tests need Tie::Array (core since perl 5.005) and Tie::Hash (since
-    5.002). Some uvar tests need Hash::Util::FieldHash (since 5.9.4). Glob
-    tests need Symbol (since 5.002). Threads tests need threads and
-    threads::shared (both since 5.7.3).
-
 SEE ALSO
     perlguts and perlapi for internal information about magic.
 
@@ -607,7 +648,7 @@ SUPPORT
     <http://www.profvince.com/perl/cover/Variable-Magic>.
 
 COPYRIGHT & LICENSE
-    Copyright 2007,2008,2009,2010,2011,2012,2013,2014 Vincent Pit, all
+    Copyright 2007,2008,2009,2010,2011,2012,2013,2014,2015 Vincent Pit, all
     rights reserved.
 
     This program is free software; you can redistribute it and/or modify it