Variable::Magic - Associate user-defined magic to variables from Perl.
VERSION
- Version 0.01
+ Version 0.31
SYNOPSIS
use Variable::Magic qw/wizard cast dispell/;
- my $wiz = wizard set => sub { print STDERR "now set to $_[0]!\n" };
+ my $wiz = wizard set => sub { print STDERR "now set to ${$_[0]}!\n" };
my $a = 1;
cast $a, $wiz;
$a = 2; # "now set to 2!"
$a = 3 # (nothing)
DESCRIPTION
- Magic is Perl way of enhancing objects. This mechanism let the user add
- extra data to any variable and overload 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.
+ Magic is Perl way of enhancing objects. This mechanism lets the user add
+ extra data to any variable and hook syntaxical operations (such as
+ 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.
+
+ 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.
+
+ Still, the magic made available by this module differs from tieing and
+ overloading in several ways :
+
+ * It isn't copied on assignment.
+
+ You attach it to variables, not values (as for blessed references).
+
+ * 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 :
- "get"
+ * "get"
+
This magic is invoked when the variable is evaluated (does not
include array/hash subscripts and slices).
- "set"
+ * "set"
+
This one is triggered each time the value of the variable changes
(includes array/hash subscripts and slices).
- "len"
+ * "len"
+
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"
+ * "clear"
+
This magic is invoked when the variable is reset, such as when an
array is emptied. Please note that this is different from undefining
- the variable, even though the magic is called when the reset is a
- result of the undefine (e.g. for an array).
+ the variable, even though the magic is called when the clearing is a
+ result of the undefine (e.g. for an array, but actually a bug
+ prevent it to work before perl 5.9.5 - see the history).
- "free"
- This last one can be considered as an object destructor. It happens
- when the variable goes out of scope (with the exception of global
- scope), but not when it is undefined.
+ * "free"
- 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).
+ This one can be considered as an object destructor. It happens when
+ the variable goes out of scope (with the exception of global scope),
+ but not when it is undefined.
-CONSTANTS
- "SIG_MIN"
- The minimum integer used as a signature for user-defined magic.
+ * "copy"
- "SIG_MAX"
- The maximum integer used as a signature for user-defined magic.
+ This magic only applies to tied arrays and hashes. It fires when you
+ try to access or change their elements. It is available on your perl
+ iff "MGf_COPY" is true.
- "SIG_NBR"
- SIG_NBR = SIG_MAX - SIG_MIN + 1
+ * "dup"
+
+ Invoked when the variable is cloned across threads. Currently not
+ available.
+
+ * "local"
+
+ When this magic is set on a variable, all subsequent localizations
+ of the variable will trigger the callback. It is available on your
+ perl iff "MGf_LOCAL" is true.
+
+ The following actions only apply to hashes and are available iff
+ "VMG_UVAR" is true. They are referred to as "uvar" magics.
+
+ * "fetch"
+
+ This magic happens each time an element is fetched from the hash.
+
+ * "store"
+
+ This one is called when an element is stored into the hash.
+
+ * "exists"
+
+ This magic fires when a key is tested for existence in the hash.
+
+ * "delete"
+
+ This last one triggers when a key is deleted in the hash, regardless
+ of whether the key actually exists in it.
+
+ 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).
FUNCTIONS
"wizard"
- wizard sig => .., data => ..., get => .., set => .., len => .., clear => .., free => ..
+ 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
can be :
- 'sig'
+ * "sig"
+
The numerical signature. If not specified or undefined, a random
- signature is generated.
-
- 'data'
- A code reference to a private data constructor. It will be called
- each time this magic is cast on a variable, and the scalar returned
- will be used as private data storage for it.
-
- 'get', 'set', 'len', 'clear' and 'free'
- Code references to corresponding magic callbacks. You don't have to
- specify all of them : the magic associated with undefined entries
- simply won't be hooked. When the magic variable is an array or a
- hash, $_[0] is a reference to it, but directly references it
- otherwise. $_[1] is 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.
+ signature is generated. If the signature matches an already defined
+ magic, then the existant magic object is returned.
+
+ * "data"
+
+ A code reference to a private data constructor. It is called each
+ time this magic is cast on a variable, and the scalar returned is
+ used as private data storage for it. $_[0] is a reference to the
+ magic object and @_[1 .. @_-1] are all extra arguments that were
+ passed to "cast".
+
+ * "get", "set", "len", "clear", "free", "copy", "local", "fetch",
+ "store", "exists" and "delete"
+
+ 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
+ (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" },
- 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" }
"gensig"
With this tool, you can manually generate random magic signature between
my $sig = getsig $wiz;
"cast"
- cast [$@%&*]var, $wiz
+ cast [$@%&*]var, [$wiz|$sig], ...
This function associates $wiz magic to the variable supplied, without
- overwriting any other kind of magic. It returns true on success or when
- $wiz magic is already present, and false on error.
-
- # Casts $wiz to $x
+ overwriting any other kind of magic. You can also supply the numeric
+ signature $sig instead of $wiz. It returns true on success or when $wiz
+ 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. 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;
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
+ getdata [$@%&*]var, [$wiz|$sig]
+
+ This accessor fetches the private data associated with the magic $wiz
+ (or the signature $sig) in the variable. "undef" is returned when no
+ such magic or data is found, or when $sig does not represent a current
+ valid magic object.
- This accessor fetches the private data associated with the magic $wiz in
- the variable. "undef" is returned when no such magic or data is found.
+ # Get the attached data.
+ my $data = getdata $x, $wiz or die 'no such magic or magic has no data';
"dispell"
- dispell [$@%&*]variable, $wiz
- dispell [$@%&*]variable, $sig
+ dispell [$@%&*]variable, [$wiz|$sig]
The exact opposite of "cast" : it dissociates $wiz magic from the
- variable. You can also pass the magic signature as the second argument.
- True is returned on success, and false on error or when no magic
- represented by $wiz could be found in the variable.
+ variable. You can also pass the magic signature $sig as the second
+ argument. True is returned on success, 0 on error or when no magic
+ represented by $wiz could be found in the variable, and "undef" when no
+ magic corresponds to the given signature (in case $sig was supplied).
- # Dispell now
+ # 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'.
- The constants "SIG_MIN", "SIG_MAX" and "SIG_NBR" 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
+ 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,
+ this destructor won't be called because the wizard will be destroyed
+ first.
DEPENDENCIES
+ perl 5.8.
+
Carp (standard since perl 5), XSLoader (standard since perl 5.006).
- Tests use Symbol (standard since perl 5.002).
+ Copy tests need Tie::Array (standard since perl 5.005) and Tie::Hash
+ (since 5.002).
+
+ Some uvar tests need Hash::Util::FieldHash (standard since perl
+ 5.009004).
+
+ Glob tests need Symbol (standard since perl 5.002).
+
+ Threads tests need threads and threads::shared.
SEE ALSO
perlguts and perlapi for internal information about magic.
+ perltie and overload for other ways of enhancing objects.
+
AUTHOR
- Vincent Pit, "<perl at profvince.com>"
+ Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
+
+ 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
perldoc Variable::Magic
+ Tests code coverage report is available at
+ <http://www.profvince.com/perl/cover/Variable-Magic>.
+
COPYRIGHT & LICENSE
- Copyright 2007 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.