This is 0.31

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

diff --git a/README b/README
index 61b60ab6ab683ee56d0b4a5499a4f00a6b9d5e75..171a7ca2cfdc055fb271a679d72d6ecb4e74198f 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.22
+    Version 0.31

 
 SYNOPSIS
         use Variable::Magic qw/wizard cast dispell/;
 
 SYNOPSIS
         use Variable::Magic qw/wizard cast dispell/;


@@ -15,27 +15,51 @@ SYNOPSIS
         $a = 3           # (nothing)
 
 DESCRIPTION
         $a = 3           # (nothing)
 
 DESCRIPTION

-    Magic is Perl way of enhancing objects. This mechanism let the user add
+    Magic is Perl way of enhancing objects. This mechanism lets the user add

     extra data to any variable and hook syntaxical operations (such as
     extra data to any variable and hook syntaxical operations (such as

-    access, assignation or destruction) that can be applied to it. With this
-    module, you can add your own magic to any variable without the pain of
-    the C API.
+    access, assignment or destruction) that can be applied to it. With this
+    module, you can add your own magic to any variable without having to
+    write a single line of XS.

 
 

-    Magic differs from tieing and overloading in several ways :
+    You'll realize that these magic variables look a lot like tied
+    variables. It's not surprising, as tied variables are implemented as a
+    special kind of magic, just like any 'irregular' Perl variable : scalars
+    like $!, $( or $^W, the %ENV and %SIG hashes, the @ISA array, "vec()"
+    and "substr()" lvalues, thread::shared variables... They all share the
+    same underlying C API, and this module gives you direct access to it.

 
 

-    *   Magic isn't copied on assignation (as for blessed references) : you
-        attach it to variables, not values.
+    Still, the magic made available by this module differs from tieing and
+    overloading in several ways :

 
 

-    *   It doesn't replace the original semantics : magic callbacks trigger
-        before the original action take place, and can't prevent it to
-        happen.
+    *   It isn't copied on assignment.

 
 

-    *   It's mostly invisible at the Perl level : magical and non-magical
-        variables cannot be distinguished with "ref", "reftype" or another
-        trick.
+        You attach it to variables, not values (as for blessed references).

 
 

-    *   It's notably faster, since perl's way of handling magic is lighter
-        by nature, and there's no need for any method resolution.
+    *   It doesn't replace the original semantics.
+
+        Magic callbacks trigger before the original action take place, and
+        can't prevent it to happen. This makes catching individual events
+        easier than with "tie", where you have to provide fallbacks methods
+        for all actions by usually inheriting from the correct "Tie::Std*"
+        class and overriding individual methods in your own class.
+
+    *   It's type-agnostic.
+
+        The same magic can be applied on scalars, arrays, hashes, subs or
+        globs. But the same hook (see below for a list) may trigger
+        differently depending on the the type of the variable.
+
+    *   It's mostly invisible at the Perl level.
+
+        Magical and non-magical variables cannot be distinguished with
+        "ref", "tied" or another trick.
+
+    *   It's notably faster.
+
+        Mainly because perl's way of handling magic is lighter by nature,
+        and because there's no need for any method resolution. Also, since
+        you don't have to reimplement all the variable semantics, you only
+        pay for what you actually use.

 
     The operations that can be overloaded are :
 
 
     The operations that can be overloaded are :
 


@@ -54,7 +78,7 @@ DESCRIPTION
         This magic is a little special : it is called when the 'size' or the
         'length' of the variable has to be known by Perl. Typically, it's
         the magic involved when an array is evaluated in scalar context, but
         This magic is a little special : it is called when the 'size' or the
         'length' of the variable has to be known by Perl. Typically, it's
         the magic involved when an array is evaluated in scalar context, but

-        also on array assignation and loops ("for", "map" or "grep"). The
+        also on array assignment and loops ("for", "map" or "grep"). The

         callback has then to return the length as an integer.
 
     *   "clear"
         callback has then to return the length as an integer.
 
     *   "clear"


@@ -115,96 +139,23 @@ DESCRIPTION
     an unique numerical signature is attached to each kind of magic (i.e.
     each set of callbacks for magic operations).
 
     an unique numerical signature is attached to each kind of magic (i.e.
     each set of callbacks for magic operations).
 

-PERL MAGIC HISTORY
-    The places where magic is invoked have changed a bit through perl
-    history. Here's a little list of the most recent ones.
-
-    *   5.6.x
-
-        *p14416* : 'copy' and 'dup' magic.
-
-    *   5.9.3
-
-        *p25854* : 'len' magic is no longer called when pushing an element
-        into a magic array.
-
-        *p26569* : 'local' magic.
-
-    *   5.9.5
-
-        *p31064* : Meaningful 'uvar' magic.
-
-        *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.
-
-    *   5.11.x
-
-        *p32969* : 'len' magic is no longer invoked when calling "length"
-        with a magical scalar.
-
-CONSTANTS
-  "SIG_MIN"
-    The minimum integer used as a signature for user-defined magic.
-
-  "SIG_MAX"
-    The maximum integer used as a signature for user-defined magic.
-
-  "SIG_NBR"
-        SIG_NBR = SIG_MAX - SIG_MIN + 1
-
-  "MGf_COPY"
-    Evaluates to true iff the 'copy' magic is available.
-
-  "MGf_DUP"
-    Evaluates to true iff the 'dup' magic is available.
-
-  "MGf_LOCAL"
-    Evaluates to true iff the 'local' magic is available.
-
-  "VMG_UVAR"
-    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.
-
-  "VMG_COMPAT_SCALAR_LENGTH_NOLEN"
-    True for perls that don't call 'len' magic when taking the "length" of a
-    magical scalar.
-
-  "VMG_PERL_PATCHLEVEL"
-    The perl patchlevel this module was built with, or 0 for non-debugging
-    perls.
-
-  "VMG_THREADSAFE"
-    True iff this module could have been built with thread-safety features
-    enabled.
-

 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 [, $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


@@ -227,17 +178,48 @@ 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).
+
+        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"
+
+                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"
+
+                $_[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
+        the "len" callback currently holds a meaning.

 
         # A simple scalar tracer
         my $wiz = wizard get  => sub { print STDERR "got ${$_[0]}\n" },
 
         # A simple scalar tracer
         my $wiz = wizard get  => sub { print STDERR "got ${$_[0]}\n" },


@@ -276,6 +258,18 @@ FUNCTIONS
         my $x;
         die 'error' unless cast $x, $wiz;
 
         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]
 
   "getdata"
         getdata [$@%&*]var, [$wiz|$sig]
 


@@ -299,18 +293,114 @@ FUNCTIONS
         # Dispell now. If $wiz isn't a signature, undef can't be returned.
         die 'no such magic or error' unless dispell $x, $wiz;
 
         # Dispell now. If $wiz isn't a signature, undef can't be returned.
         die 'no such magic or error' unless dispell $x, $wiz;
 

+CONSTANTS
+  "SIG_MIN"
+    The minimum integer used as a signature for user-defined magic.
+
+  "SIG_MAX"
+    The maximum integer used as a signature for user-defined magic.
+
+  "SIG_NBR"
+        SIG_NBR = SIG_MAX - SIG_MIN + 1
+
+  "MGf_COPY"
+    Evaluates to true iff the 'copy' magic is available.
+
+  "MGf_DUP"
+    Evaluates to true iff the 'dup' magic is available.
+
+  "MGf_LOCAL"
+    Evaluates to true iff the 'local' magic is available.
+
+  "VMG_UVAR"
+    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_UNSHIFT_NOLEN_VOID"
+    True for perls that don't call 'len' magic when you unshift in void
+    context an element in a magical array.
+
+  "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_PERL_PATCHLEVEL"
+    The perl patchlevel this module was built with, or 0 for non-debugging
+    perls.
+
+  "VMG_THREADSAFE"
+    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.
+
+PERL MAGIC HISTORY
+    The places where magic is invoked have changed a bit through perl
+    history. Here's a little list of the most recent ones.
+
+    *   5.6.x
+
+        *p14416* : 'copy' and 'dup' magic.
+
+    *   5.8.9
+
+        *p28160* : Integration of *p25854* (see below).
+
+        *p32542* : Integration of *p31473* (see below).
+
+    *   5.9.3
+
+        *p25854* : 'len' magic is no longer called when pushing an element
+        into a magic array.
+
+        *p26569* : 'local' magic.
+
+    *   5.9.5
+
+        *p31064* : Meaningful 'uvar' magic.
+
+        *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.
+
+    *   5.11.x
+
+        *p32969* : 'len' magic is no longer invoked when calling "length"
+        with a magical scalar.
+
+        *p34908* : 'len' magic is no longer called when pushing / unshifting
+        an element into a magical array in void context. The "push" part was
+        already covered by *p25854*.
+

 EXPORT
     The functions "wizard", "gensig", "getsig", "cast", "getdata" and
     "dispell" are only exported on request. All of them are exported by the
     tags ':funcs' and ':all'.
 
 EXPORT
     The functions "wizard", "gensig", "getsig", "cast", "getdata" and
     "dispell" are only exported on request. All of them are exported by the
     tags ':funcs' and ':all'.
 

-    The constants "SIG_MIN", "SIG_MAX", "SIG_NBR", "MGf_COPY", "MGf_DUP",
-    "MGf_LOCAL" and "VMG_UVAR" are also only exported on request. They are
-    all exported by the tags ':consts' and ':all'.
+    All the constants are also only exported on request, either individually
+    or by the tags ':consts' and ':all'.

 
 CAVEATS
     If you store a magic object in the private data slot, the magic won't be
 
 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
+    accessible by "getdata" since it's not copied by assignment. 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,
     way to address this would be to return a reference.
 
     If you define a wizard with a "free" callback and cast it on itself,


@@ -318,7 +408,7 @@ CAVEATS
     first.
 
 DEPENDENCIES
     first.
 
 DEPENDENCIES

-    perl 5.7.3.
+    perl 5.8.

 
     Carp (standard since perl 5), XSLoader (standard since perl 5.006).
 
 
     Carp (standard since perl 5), XSLoader (standard since perl 5.006).
 


@@ -340,8 +430,7 @@ SEE ALSO
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 

-    You can contact me by mail or on #perl @ FreeNode (vincent or
-    Prof_Vince).
+    You can contact me by mail or on "irc.perl.org" (vincent).

 
 BUGS
     Please report any bugs or feature requests to "bug-variable-magic at
 
 BUGS
     Please report any bugs or feature requests to "bug-variable-magic at


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

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