Variable::Magic - Associate user-defined magic to variables from Perl.
VERSION
- Version 0.25
+ Version 0.28
SYNOPSIS
use Variable::Magic qw/wizard cast dispell/;
*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
*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*.
+
CONSTANTS
"SIG_MIN"
The minimum integer used as a signature for user-defined magic.
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.
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) = @_; ... },
+ 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
This function creates a 'wizard', an opaque type that holds the magic
information. It takes a list of keys / values as argument, whose keys
* "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
- (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). Other
+ arguments are specific to the magic hooked :
+
+ - "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.
+
+ - "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" },
<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.
projects / perl / modules / Variable-Magic.git / blobdiff