This is 0.28

diff --git a/Changes b/Changes
index 292cf9985c53b680821c5f7c90a0910d0056ec53..7c6fe6718133f837a4e4b50bd9d70911dc5a8385 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,18 @@
 Revision history for Variable-Magic
 
+0.28    2009-01-24 17:05 UTC
+        + Add : The 'copy_key' option to wizard(), that enables the safe edition
+                of $_[2] in uvar callbacks to redirect actions to another key.
+        + Fix : Exception objects thrown from callbacks at compile time were not
+                available in $@.
+        + Fix : free callbacks triggered during global destruction could lead to
+                segfaults because the wizard was already freed.
+        + Fix : Refcount of scalars with free callback.
+        + Fix : Segfaults when using get or uvar magic simultaneously with clear
+                magic.
+        + Doc : The documentation about what the callbacks take and should
+                return is now somewhat clearer.
+
 0.27    2009-01-18 23:40 UTC
         + Fix : Offset of 1 with len magic on scalars.
         + Fix : Segfaults that seem to happen when one croak in a callback at

diff --git a/META.yml b/META.yml
index e67f456a7449db553f4b9e4561b900a40323c9bb..d276af4808c8c237558958214b8f83747cc61196 100644 (file)
--- a/META.yml
+++ b/META.yml
@@ -1,6 +1,6 @@
 --- #YAML:1.0
 name:               Variable-Magic
-version:            0.27
+version:            0.28
 abstract:           Associate user-defined magic to variables from Perl.
 author:
     - Vincent Pit <perl@profvince.com>

diff --git a/README b/README
index d5004fc0fd7ac68598b453f4a6961dca6b4b84dd..03cda6c4d8172f1d6043e6857465f34c434f427c 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Variable::Magic - Associate user-defined magic to variables from Perl.
 
 VERSION
-    Version 0.27
+    Version 0.28
 
 SYNOPSIS
         use Variable::Magic qw/wizard cast dispell/;
@@ -206,19 +206,20 @@ CONSTANTS
 
 FUNCTIONS
   "wizard"
-        wizard sig    => ...,
-               data   => sub { ... },
-               get    => sub { my ($ref, $data) = @_; ... },
-               set    => sub { my ($ref, $data) = @_; ... },
-               len    => sub { my ($ref, $data, $len) = @_; ... ; return $newlen; },
-               clear  => sub { my ($ref, $data) = @_; ... },
-               free   => sub { my ($ref, $data) = @_, ... },
-               copy   => sub { my ($ref, $data, $key, $elt) = @_; ... },
-               local  => sub { my ($ref, $data) = @_; ... },
-               fetch  => sub { my ($ref, $data, $key) = @_; ... },
-               store  => sub { my ($ref, $data, $key) = @_; ... },
-               exists => sub { my ($ref, $data, $key) = @_; ... },
-               delete => sub { my ($ref, $data, $key) = @_; ... }
+        wizard sig      => ...,
+               data     => sub { ... },
+               get      => sub { my ($ref, $data) = @_; ... },
+               set      => sub { my ($ref, $data) = @_; ... },
+               len      => sub { my ($ref, $data, $len) = @_; ... ; return $newlen; },
+               clear    => sub { my ($ref, $data) = @_; ... },
+               free     => sub { my ($ref, $data) = @_, ... },
+               copy     => sub { my ($ref, $data, $key, $elt) = @_; ... },
+               local    => sub { my ($ref, $data) = @_; ... },
+               fetch    => sub { my ($ref, $data, $key) = @_; ... },
+               store    => sub { my ($ref, $data, $key) = @_; ... },
+               exists   => sub { my ($ref, $data, $key) = @_; ... },
+               delete   => sub { my ($ref, $data, $key) = @_; ... },
+               copy_key => $bool
 
     This function creates a 'wizard', an opaque type that holds the magic
     information. It takes a list of keys / values as argument, whose keys
@@ -241,17 +242,36 @@ FUNCTIONS
     *   "get", "set", "len", "clear", "free", "copy", "local", "fetch",
         "store", "exists" and "delete"
 
-        Code references to corresponding magic callbacks. You don't have to
-        specify all of them : the magic associated with undefined entries
+        Code references to the corresponding magic callbacks. You don't have
+        to specify all of them : the magic associated with undefined entries
         simply won't be hooked. In those callbacks, $_[0] is always a
         reference to the magic object and $_[1] is always the private data
-        (or "undef" when no private data constructor was supplied). In the
-        special case of "len" magic and when the variable is an array, $_[2]
-        contains its normal length. $_[2] is the current key in "copy",
-        "fetch", "store", "exists" and "delete" callbacks, although for
-        "copy" it may just be a copy of the actual key so it's useless to
-        (for example) cast magic on it. "copy" magic also receives the
-        current element (i.e. the value) in $_[3].
+        (or "undef" when no private data constructor was supplied). Other
+        arguments are specific to the magic hooked :
+
+        -       "len"
+
+                When the variable is an array, $_[2] contains the normal
+                length. The callback is also expected to return the new
+                scalar or array length.
+
+        -       "copy"
+
+                $_[2] is a either a copy or an alias of the current key,
+                which means that it is useless to try to change or cast
+                magic on it. $_[3] is an alias to the current element (i.e.
+                the value).
+
+        -       "fetch", "store", "exists" and "delete"
+
+                $_[2] is an alias to the current key. Nothing prevents you
+                from changing it, but be aware that there lurk dangerous
+                side effects. For example, it may righteously be readonly if
+                the key was a bareword. You can get a copy instead by
+                passing "copy_key => 1" to "wizard", which allows you to
+                safely assign to $_[2] in order to e.g. redirect the action
+                to another key. This however has a little performance
+                drawback because of the copy.
 
         All the callbacks are expected to return an integer, which is passed
         straight to the perl magic API. However, only the return value of
@@ -335,8 +355,6 @@ CAVEATS
     this destructor won't be called because the wizard will be destroyed
     first.
 
-    Using "get" and "clear" magics on hashes may cause segfaults.
-
 DEPENDENCIES
     perl 5.7.3.
 

diff --git a/lib/Variable/Magic.pm b/lib/Variable/Magic.pm
index a94fbe377ca5c3c2956c68e4f1210544f07070ef..19ba55f68748ffaadf2620854187de321e629f15 100644 (file)
--- a/lib/Variable/Magic.pm
+++ b/lib/Variable/Magic.pm
@@ -13,13 +13,13 @@ Variable::Magic - Associate user-defined magic to variables from Perl.
 
 =head1 VERSION
 
-Version 0.27
+Version 0.28
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.27';
+ $VERSION = '0.28';
 }
 
 =head1 SYNOPSIS