This is 0.30

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

diff --git a/README b/README
index 03cda6c4d8172f1d6043e6857465f34c434f427c..4b7401275cd6dc507c5b39bcf0b3f4493ba3b805 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Variable::Magic - Associate user-defined magic to variables from Perl.
 
 VERSION
-    Version 0.28
+    Version 0.30
 
 SYNOPSIS
         use Variable::Magic qw/wizard cast dispell/;
@@ -204,22 +204,31 @@ CONSTANTS
     True iff this module could have been built with thread-safety features
     enabled.
 
+  "VMG_OP_INFO_NAME"
+    Value to pass with "op_info" to get the current op name in the magic
+    callbacks.
+
+  "VMG_OP_INFO_OBJECT"
+    Value to pass with "op_info" to get a "B::OP" object representing the
+    current op in the magic callbacks.
+
 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) = @_; ... },
-               copy_key => $bool
+               get      => sub { my ($ref, $data [, $op]) = @_; ... },
+               set      => sub { my ($ref, $data [, $op]) = @_; ... },
+               len      => sub { my ($ref, $data, $len [, $op]) = @_; ... ; return $newlen; },
+               clear    => sub { my ($ref, $data [, $op]) = @_; ... },
+               free     => sub { my ($ref, $data [, $op]) = @_, ... },
+               copy     => sub { my ($ref, $data, $key, $elt [, $op]) = @_; ... },
+               local    => sub { my ($ref, $data [, $op]) = @_; ... },
+               fetch    => sub { my ($ref, $data, $key [, $op]) = @_; ... },
+               store    => sub { my ($ref, $data, $key [, $op]) = @_; ... },
+               exists   => sub { my ($ref, $data, $key [, $op]) = @_; ... },
+               delete   => sub { my ($ref, $data, $key [, $op]) = @_; ... },
+               copy_key => $bool,
+               op_info  => [ 0 | VMG_OP_INFO_NAME | VMG_OP_INFO_OBJECT ]
 
     This function creates a 'wizard', an opaque type that holds the magic
     information. It takes a list of keys / values as argument, whose keys
@@ -246,23 +255,31 @@ FUNCTIONS
         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). Other
-        arguments are specific to the magic hooked :
+        (or "undef" when no private data constructor was supplied).
+
+        Moreover, when you pass "op_info => $num" to "wizard", the last
+        element of @_ will be the current op name if "$num ==
+        VMG_OP_INFO_NAME" and a "B::OP" object representing the current op
+        if "$num == VMG_OP_INFO_OBJECT". Both have a performance hit, but
+        just getting the name is lighter than getting the op object.
+
+        Other arguments are specific to the magic hooked :
 
-        -       "len"
+        *       "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.
+                When the variable is an array or a scalar, $_[2] contains
+                the non-magical length. The callback can return the new
+                scalar or array length to use, or "undef" to default to the
+                normal length.
 
-        -       "copy"
+        *       "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"
+        *       "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
@@ -314,6 +331,18 @@ FUNCTIONS
         my $x;
         die 'error' unless cast $x, $wiz;
 
+    The "var" argument can be an array or hash value. Magic for those
+    behaves like for any other scalar, except that it is dispelled when the
+    entry is deleted from the container. For example, if you want to call
+    "POSIX::tzset" each time the 'TZ' environment variable is changed in
+    %ENV, you can use :
+
+        use POSIX;
+        cast $ENV{TZ}, wizard set => sub { POSIX::tzset(); () };
+
+    If you want to overcome the possible deletion of the 'TZ' entry, you
+    have no choice but to rely on "store" uvar magic.
+
   "getdata"
         getdata [$@%&*]var, [$wiz|$sig]
 
@@ -356,7 +385,7 @@ CAVEATS
     first.
 
 DEPENDENCIES
-    perl 5.7.3.
+    perl 5.8.
 
     Carp (standard since perl 5), XSLoader (standard since perl 5.006).