The Big Boilerplate Factorization

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

diff --git a/README b/README
index e04ba968017b28339c5c7dcc91c7a1bddf98aee5..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.52
+    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>;


@@ -72,7 +72,7 @@ DESCRIPTION
 
         The same magic can be applied on scalars, arrays, hashes, subs or
         globs. But the same hook (see below for a list) may trigger
 
         The same magic can be applied on scalars, arrays, hashes, subs or
         globs. But the same hook (see below for a list) may trigger

-        differently depending on the the type of the variable.
+        differently depending on the type of the variable.

 
     *   Magic is invisible at Perl level.
 
 
     *   Magic is invisible at Perl level.
 


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


@@ -560,12 +620,7 @@ DEPENDENCIES
     A C compiler. This module may happen to build with a C++ compiler as
     well, but don't rely on it, as no guarantee is made in this regard.
 
     A C compiler. This module may happen to build with a C++ compiler as
     well, but don't rely on it, as no guarantee is made in this regard.
 

-    Carp (core since perl 5), XSLoader (since 5.006).
-
-    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.009004).
-    Glob tests need Symbol (since 5.002). Threads tests need threads and
-    threads::shared (both since 5.007003).
+    Carp (core since perl 5), XSLoader (since 5.6.0).

 
 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 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.