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
 
 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
 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
 --- #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>
 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
     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/;
 
 SYNOPSIS
         use Variable::Magic qw/wizard cast dispell/;


@@ -206,19 +206,20 @@ CONSTANTS
 
 FUNCTIONS
   "wizard"
 
 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
 
     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"
 
     *   "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
         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
 
         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.
 
     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.
 
 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
 
 
 =head1 VERSION
 

-Version 0.27
+Version 0.28

 
 =cut
 
 our $VERSION;
 BEGIN {
 
 =cut
 
 our $VERSION;
 BEGIN {

- $VERSION = '0.27';
+ $VERSION = '0.28';

 }
 
 =head1 SYNOPSIS
 }
 
 =head1 SYNOPSIS