Variable::Magic - Associate user-defined magic to variables from Perl.
VERSION
- Version 0.29
+ Version 0.35
SYNOPSIS
- use Variable::Magic qw/wizard cast dispell/;
-
- my $wiz = wizard set => sub { print STDERR "now set to ${$_[0]}!\n" };
- my $a = 1;
- cast $a, $wiz;
- $a = 2; # "now set to 2!"
- dispell $a, $wiz;
- $a = 3 # (nothing)
+ 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 $a = 1;
+ cast $a, $wiz;
+ $a = 2; # "now set to 2!"
+ } # "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 %h = (_default => 0, apple => 2);
+ cast %h, $wiz, '_default';
+ print $h{banana}, "\n"; # "0", because the 'banana' key doesn't exist in %h
+ $h{pear} = 1; # "key pear stored in helem"
+ }
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
- 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.
+
+ 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, threads::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 differs from tieing and overloading in several ways :
+ Magic callbacks usually trigger before the original action take
+ place, and can't prevent it to happen. This also 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.
- * Magic isn't copied on assignation (as for blessed references) : you
- attach it to variables, not values.
+ * It's type-agnostic.
- * It doesn't replace the original semantics : magic callbacks trigger
- before the original action take place, and can't prevent it to
- happen.
+ 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", "reftype" or another
- trick.
+ * It's mostly invisible at the Perl level.
- * It's notably faster, since perl's way of handling magic is lighter
- by nature, and there's no need for any method resolution.
+ 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 :
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"
* "free"
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.
+ the variable goes out of scope, but not when it is undefined.
* "copy"
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).
-
-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*.
-
-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.
+ 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"
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
+ 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
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). Other
- arguments are specific to the magic hooked :
+ (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"
set => sub { print STDERR "set to ${$_[0]}\n" },
free => sub { print STDERR "${$_[0]} was deleted\n" }
+ Note that "free" callbacks are *never* called during global destruction,
+ as there's no way to ensure that the wizard and the "free" callback
+ weren't destroyed before the variable.
+
"gensig"
With this tool, you can manually generate random magic signature between
SIG_MIN and SIG_MAX inclusive. That's the way "wizard" creates them when
This function associates $wiz magic to the variable supplied, without
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
+ magic is already present, and croaks on error or when no magic
+ corresponds to the given signature (in case a $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.
+ constructor in @_[1 .. @_-1]. 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.
+ # Casts $wiz onto $x, and pass '1' to the data constructor.
my $x;
- die 'error' unless cast $x, $wiz;
+ cast $x, $wiz, 1;
+
+ 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.
+
+ "cast" can be called from any magical callback, and in particular from
+ "data". This allows you to recursively cast magic on datastructures :
+
+ my $wiz;
+ $wiz = wizard
+ data => sub {
+ my ($var, $depth) = @_;
+ $depth ||= 0;
+ my $r = ref $var;
+ if ($r eq 'ARRAY') {
+ &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for @$var;
+ } elsif ($r eq 'HASH') {
+ &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for values %$var;
+ }
+ return $depth;
+ },
+ free => sub {
+ my ($var, $depth) = @_;
+ my $r = ref $var;
+ print "free $r at depth $depth\n";
+ ();
+ };
+
+ {
+ my %h = (
+ a => [ 1, 2 ],
+ b => { c => 3 }
+ );
+ cast %h, $wiz;
+ }
+
+ When %h goes out of scope, this will print something among the lines of
+ :
+
+ free HASH at depth 0
+ free HASH at depth 1
+ free SCALAR at depth 2
+ free ARRAY at depth 1
+ free SCALAR at depth 3
+ free SCALAR at depth 3
+
+ Of course, this example does nothing with the values that are added
+ after the "cast".
"getdata"
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.
+ (or the signature $sig) in the variable. It croaks when $wiz or $sig do
+ not represent a current valid magic object attached to the variable, and
+ returns "undef" when the wizard has no data constructor or when the data
+ is actually "undef".
- # Get the attached data.
- my $data = getdata $x, $wiz or die 'no such magic or magic has no data';
+ # Get the attached data, or undef if the wizard does not attach any.
+ my $data = getdata $x, $wiz;
"dispell"
dispell [$@%&*]variable, [$wiz|$sig]
The exact opposite of "cast" : it dissociates $wiz magic from the
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).
+ argument. This function returns true on success, 0 when no magic
+ represented by $wiz or $sig could be found in the variable, and croaks
+ if the supplied wizard or signature is invalid.
+
+ # Dispell now.
+ die 'no such magic in $x' 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.
- # Dispell now. If $wiz isn't a signature, undef can't be returned.
- die 'no such magic or error' unless dispell $x, $wiz;
+ "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", "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
- 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,