X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=f31437cd31ddea8004950fa498ea8d0e96a67aa5;hb=refs%2Ftags%2Fv0.11;hp=0a385c122a261c002f85abcb51495db85afcf3d1;hpb=763ba8093427f3668368fa885741618ac6289d41;p=perl%2Fmodules%2FVariable-Magic.git

diff --git a/README b/README
index 0a385c1..f31437c 100644
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Variable::Magic - Associate user-defined magic to variables from Perl.
 
 VERSION
-    Version 0.08
+    Version 0.11
 
 SYNOPSIS
         use Variable::Magic qw/wizard cast dispell/;
@@ -64,7 +64,7 @@ DESCRIPTION
         of the variable will trigger the callback. It is available on your
         perl iff "MGf_LOCAL" is true.
 
-    The following actions only applies to hashes and are available iff
+    The following actions only apply to hashes and are available iff
     "VMG_UVAR" is true. They are referred to as "uvar" magics.
 
     "fetch"
@@ -95,8 +95,8 @@ PERL MAGIC HISTORY
     *p14416* : 'copy' and 'dup' magic.
 
   5.9.3
-    'len' magic is no longer called when pushing an element into a magic
-    array.
+    *p25854* : 'len' magic is no longer called when pushing an element into
+    a magic array.
     *p26569* : 'local' magic.
 
   5.9.5
@@ -104,6 +104,11 @@ PERL MAGIC HISTORY
     *p31473* : 'clear' magic wasn't invoked when undefining an array. The
     bug is fixed as of this version.
 
+  5.10.0
+    Since "PERL_MAGIC_uvar" is uppercased, "hv_magic_check()" triggers
+    'copy' magic on hash stores for (non-tied) hashes that also have 'uvar'
+    magic.
+
 CONSTANTS
   "SIG_MIN"
     The minimum integer used as a signature for user-defined magic.
@@ -127,6 +132,13 @@ CONSTANTS
     When this constant is true, you can use the "fetch,store,exists,delete"
     callbacks on hashes.
 
+  "VMG_COMPAT_ARRAY_PUSH_NOLEN"
+    True for perls that don't call 'len' magic when you push an element in a
+    magical array.
+
+  "VMG_COMPAT_ARRAY_UNDEF_CLEAR"
+    True for perls that call 'clear' magic when undefining magical arrays.
+
 FUNCTIONS
   "wizard"
         wizard sig    => ...,
@@ -136,7 +148,7 @@ FUNCTIONS
                len    => sub { my ($ref, $data, $len) = @_; ... ; return $newlen; },
                clear  => sub { my ($ref, $data) = @_; ... },
                free   => sub { my ($ref, $data) = @_, ... },
-               copy   => sub { my ($ref, $data, $elt) = @_; ... },
+               copy   => sub { my ($ref, $data, $key, $elt) = @_; ... },
                local  => sub { my ($ref, $data) = @_; ... },
                fetch  => sub { my ($ref, $data, $key) = @_; ... },
                store  => sub { my ($ref, $data, $key) = @_; ... },
@@ -167,9 +179,11 @@ FUNCTIONS
         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. "copy" magic receives the current
-        element (i.e. the value) in $_[2]. $_[2] is also the current key in
-        "fetch", "store", "exists" and "delete" callbacks.
+        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].
 
         # A simple scalar tracer
         my $wiz = wizard get  => sub { print STDERR "got ${$_[0]}\n" },
@@ -201,7 +215,8 @@ FUNCTIONS
     magic is already present, 0 on error, and "undef" when no magic
     corresponds to the given signature (in case $sig was supplied). All
     extra arguments specified after $wiz are passed to the private data
-    constructor.
+    constructor. If the variable isn't a hash, any "uvar" callback of the
+    wizard is safely ignored.
 
         # Casts $wiz onto $x. If $wiz isn't a signature, undef can't be returned.
         my $x;
@@ -239,6 +254,15 @@ EXPORT
     "MGf_LOCAL" and "VMG_UVAR" are also only exported on request. They are
     all exported by the tags ':consts' and ':all'.
 
+CAVEATS
+    If you store a magic object in the private data slot, the magic won't be
+    accessible by "getdata" since it's not copied by assignation. The only
+    way to address this would be to return a reference.
+
+    If you define a wizard with a "free" callback and cast it on itself,
+    this destructor won't be called because the wizard will be destroyed
+    first.
+
 DEPENDENCIES
     perl 5.7.3.