The Big Boilerplate Factorization

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

diff --git a/README b/README
index b77b8453ef9536f4c6eec27afcb6de4103bd444f..ba89f24cb1cbd48730a3493fddd79f39005723e4 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.53
+    Version 0.59

 
 SYNOPSIS
         use Variable::Magic qw<wizard cast VMG_OP_INFO_NAME>;
 
 SYNOPSIS
         use Variable::Magic qw<wizard cast VMG_OP_INFO_NAME>;


@@ -132,8 +132,13 @@ DESCRIPTION
 
     *   *copy*
 
 
     *   *copy*
 

-        This magic only applies to tied arrays and hashes, and fires when
-        you try to access or change their elements.
+        When applied to tied arrays and hashes, this magic fires when you
+        try to access or change their elements.
+
+        Starting from perl 5.17.0, it can also be applied to closure
+        prototypes, in which case the magic will be called when the
+        prototype is cloned. The "VMG_COMPAT_CODE_COPY_CLONE" constant is
+        true when your perl support this feature.

 
     *   *dup*
 
 
     *   *dup*
 


@@ -225,10 +230,15 @@ FUNCTIONS
 
         *       *copy*
 
 
         *       *copy*
 

-                $_[2] is a either an alias or a copy of the current key, and
-                $_[3] is an alias to the current element (i.e. the value).
-                Because $_[2] might be a copy, it is useless to try to
-                change it or cast magic on it.
+                When the variable for which the magic is invoked is an array
+                or an hash, $_[2] is a either an alias or a copy of the
+                current key, and $_[3] is an alias to the current element
+                (i.e. the value). Since $_[2] might be a copy, it is useless
+                to try to change it or cast magic on it.
+
+                Starting from perl 5.17.0, this magic can also be called for
+                code references. In this case, $_[2] is always "undef" and
+                $_[3] is a reference to the cloned anonymous subroutine.

 
         *       *fetch*, *store*, *exists* and *delete*
 
 
         *       *fetch*, *store*, *exists* and *delete*
 


@@ -255,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 :
 


@@ -385,6 +402,10 @@ CONSTANTS
     True for perls that don't call *delete* magic when you delete an element
     from a hash in void context.
 
     True for perls that don't call *delete* magic when you delete an element
     from a hash in void context.
 

+  "VMG_COMPAT_CODE_COPY_CLONE"
+    True for perls that call *copy* magic when a magical closure prototype
+    is cloned.
+

   "VMG_COMPAT_GLOB_GET"
     True for perls that call *get* magic for operations on globs.
 
   "VMG_COMPAT_GLOB_GET"
     True for perls that call *get* magic for operations on globs.
 


@@ -487,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.


@@ -562,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.
 


@@ -589,12 +644,9 @@ SUPPORT
 
         perldoc Variable::Magic
 
 
         perldoc Variable::Magic
 

-    Tests code coverage report is available at
-    <http://www.profvince.com/perl/cover/Variable-Magic>.
-

 COPYRIGHT & LICENSE
 COPYRIGHT & LICENSE

-    Copyright 2007,2008,2009,2010,2011,2012,2013 Vincent Pit, all rights
-    reserved.
+    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
     under the same terms as Perl itself.
 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.