Variable::Magic - Associate user-defined magic to variables from Perl.
VERSION
- Version 0.08
+ Version 0.14
SYNOPSIS
use Variable::Magic qw/wizard cast dispell/;
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"
*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
*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.
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 => ...,
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) = @_; ... },
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" },
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;
"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.
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 #perl @ FreeNode (Prof_Vince).
+ You can contact me by mail or on #perl @ FreeNode (vincent or
+ Prof_Vince).
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-2008 Vincent Pit, all rights reserved.