Jumbo POD overhaul

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

diff --git a/README b/README
index ac81e42c52bcf6d095d254e9dcbd72d4238ba4e6..494ef72d2cdcbff8a48185672fe5b70107b38dcc 100644 (file)
--- a/README
+++ b/README
@@ -2,14 +2,16 @@ 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.46
+    Version 0.49

 
 SYNOPSIS
         use Variable::Magic qw<wizard cast VMG_OP_INFO_NAME>;
 
         { # A variable tracer
 
 SYNOPSIS
         use Variable::Magic qw<wizard cast VMG_OP_INFO_NAME>;
 
         { # A variable tracer

-         my $wiz = wizard set  => sub { print "now set to ${$_[0]}!\n" },
-                          free => sub { print "destroyed!\n" };
+         my $wiz = wizard(
+          set  => sub { print "now set to ${$_[0]}!\n" },
+          free => sub { print "destroyed!\n" },
+         );

 
          my $a = 1;
          cast $a, $wiz;
 
          my $a = 1;
          cast $a, $wiz;


@@ -17,15 +19,17 @@ SYNOPSIS
         }               # "destroyed!"
 
         { # A hash with a default value
         }               # "destroyed!"
 
         { # A hash with a default value

-         my $wiz = wizard data     => sub { $_[1] },
-                          fetch    => sub { $_[2] = $_[1] unless exists $_[0]->{$_[2]}; () },
-                          store    => sub { print "key $_[2] stored in $_[-1]\n" },
-                          copy_key => 1,
-                          op_info  => VMG_OP_INFO_NAME;
+         my $wiz = wizard(
+          data     => sub { $_[1] },
+          fetch    => sub { $_[2] = $_[1] unless exists $_[0]->{$_[2]}; () },
+          store    => sub { print "key $_[2] stored in $_[-1]\n" },
+          copy_key => 1,
+          op_info  => VMG_OP_INFO_NAME,
+         );

 
          my %h = (_default => 0, apple => 2);
          cast %h, $wiz, '_default';
 
          my %h = (_default => 0, apple => 2);
          cast %h, $wiz, '_default';

-         print $h{banana}, "\n"; # "0", because the 'banana' key doesn't exist in %h
+         print $h{banana}, "\n"; # "0" (there is no 'banana' key in %h)

          $h{pear} = 1;           # "key pear stored in helem"
         }
 
          $h{pear} = 1;           # "key pear stored in helem"
         }
 


@@ -150,29 +154,26 @@ DESCRIPTION
     You can refer to the tests to have more insight of where the different
     magics are invoked.
 
     You can refer to the tests to have more insight of where the different
     magics are invoked.
 

-    To prevent any clash between different magics defined with this module,
-    an unique numerical signature is attached to each kind of magic (i.e.
-    each set of callbacks for magic operations). At the C level, magic
-    tokens owned by magic created by this module have their "mg->mg_private"
-    field set to 0x3891 or 0x3892, so please don't use these magic (sic)
-    numbers in other extensions.
-

 FUNCTIONS
   "wizard"
 FUNCTIONS
   "wizard"

-        wizard data     => sub { ... },
-               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 ]
+        wizard(
+         data     => sub { ... },
+         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
 
     This function creates a 'wizard', an opaque type that holds the magic
     information. It takes a list of keys / values as argument, whose keys


@@ -233,8 +234,19 @@ FUNCTIONS
         straight to the perl magic API. However, only the return value of
         the "len" callback currently holds a meaning.
 
         straight to the perl magic API. However, only the return value of
         the "len" callback currently holds a meaning.
 

-    Each callback can be specified as a code or a string reference, in which
-    case the function denoted by the string will be used as the callback.
+    Each callback can be specified as :
+
+    *   a code reference, which will be called as a subroutine.
+
+    *   a string reference, where the string denotes which subroutine is to
+        be called when magic is triggered. If the subroutine name is not
+        fully qualified, then the current package at the time the magic is
+        invoked will be used instead.
+
+    *   a reference to "undef", in which case a no-op magic callback is
+        installed instead of the default one. This may especially be helpful
+        for 'local' magic, where an empty callback prevents magic from being
+        copied during localization.

 
     Note that "free" callbacks are *never* called during global destruction,
     as there's no way to ensure that the wizard and the "free" callback
 
     Note that "free" callbacks are *never* called during global destruction,
     as there's no way to ensure that the wizard and the "free" callback


@@ -243,9 +255,11 @@ FUNCTIONS
     Here's a simple usage example :
 
         # A simple scalar tracer
     Here's a simple usage example :
 
         # A simple scalar tracer

-        my $wiz = wizard get  => sub { print STDERR "got ${$_[0]}\n" },
-                         set  => sub { print STDERR "set to ${$_[0]}\n" },
-                         free => sub { print STDERR "${$_[0]} was deleted\n" }
+        my $wiz = wizard(
+         get  => sub { print STDERR "got ${$_[0]}\n" },
+         set  => sub { print STDERR "set to ${$_[0]}\n" },
+         free => sub { print STDERR "${$_[0]} was deleted\n" },
+        );

 
   "cast"
         cast [$@%&*]var, $wiz, ...
 
   "cast"
         cast [$@%&*]var, $wiz, ...


@@ -310,6 +324,10 @@ CONSTANTS
     callbacks on hashes. Initial VMG_UVAR capability was introduced in perl
     5.9.5, with a fully functional implementation shipped with perl 5.10.0.
 
     callbacks on hashes. Initial VMG_UVAR capability was introduced in perl
     5.9.5, with a fully functional implementation shipped with perl 5.10.0.
 

+  "VMG_COMPAT_SCALAR_LENGTH_NOLEN"
+    True for perls that don't call 'len' magic when taking the "length" of a
+    magical scalar.
+

   "VMG_COMPAT_ARRAY_PUSH_NOLEN"
     True for perls that don't call 'len' magic when you push an element in a
     magical array. Starting from perl 5.11.0, this only refers to pushes in
   "VMG_COMPAT_ARRAY_PUSH_NOLEN"
     True for perls that don't call 'len' magic when you push an element in a
     magical array. Starting from perl 5.11.0, this only refers to pushes in


@@ -326,9 +344,9 @@ CONSTANTS
   "VMG_COMPAT_ARRAY_UNDEF_CLEAR"
     True for perls that call 'clear' magic when undefining magical arrays.
 
   "VMG_COMPAT_ARRAY_UNDEF_CLEAR"
     True for perls that call 'clear' magic when undefining magical arrays.
 

-  "VMG_COMPAT_SCALAR_LENGTH_NOLEN"
-    True for perls that don't call 'len' magic when taking the "length" of a
-    magical scalar.
+  "VMG_COMPAT_HASH_DELETE_NOUVAR_VOID"
+    True for perls that don't call 'delete' uvar magic when you delete an
+    element from a hash in void context.

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


@@ -373,7 +391,7 @@ COOKBOOK
           unless (defined $data) {
            $data = \(my $slot);
            &cast($var, $wiz, $slot)
           unless (defined $data) {
            $data = \(my $slot);
            &cast($var, $wiz, $slot)

-                            or die "Couldn't cast UserData magic onto the variable";
+                     or die "Couldn't cast UserData magic onto the variable";

           }
           $$data;
          }
           }
           $$data;
          }


@@ -543,7 +561,8 @@ SUPPORT
     <http://www.profvince.com/perl/cover/Variable-Magic>.
 
 COPYRIGHT & LICENSE
     <http://www.profvince.com/perl/cover/Variable-Magic>.
 
 COPYRIGHT & LICENSE

-    Copyright 2007,2008,2009,2010,2011 Vincent Pit, all rights reserved.
+    Copyright 2007,2008,2009,2010,2011,2012 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.