Remove the code coverage link

[perl/modules/Variable-Magic.git] / README

diff --git a/README b/README
index 23db4c31adf42365d74062a6f2a5684aeb67b401..fc1ea925bc0f79c1bf561dc4d852dccd171b8876 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Variable::Magic - Associate user-defined magic to variables from Perl.
 
 VERSION
     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>;
 
 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.
 
         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 :
 
 
     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".
 
     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.
 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).
 
 
     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.
 
 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
     <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
     rights reserved.
 
     This program is free software; you can redistribute it and/or modify it