Variable::Magic - Associate user-defined magic to variables from Perl.
VERSION
- Version 0.52
+ Version 0.60
SYNOPSIS
use Variable::Magic qw<wizard cast VMG_OP_INFO_NAME>;
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.
+ differently depending on the type of the variable.
* Magic is invisible at Perl level.
* *copy*
- This magic only applies to tied arrays and hashes, and fires when
- you try to access or change their elements.
+ When applied to tied arrays and hashes, this magic fires when you
+ try to access or change their elements.
+
+ Starting from perl 5.17.0, it can also be applied to closure
+ prototypes, in which case the magic will be called when the
+ prototype is cloned. The "VMG_COMPAT_CODE_COPY_CLONE" constant is
+ true when your perl support this feature.
* *dup*
* *copy*
- $_[2] is a either an alias or a copy of the current key, and
- $_[3] is an alias to the current element (i.e. the value).
- Because $_[2] might be a copy, it is useless to try to
- change it or cast magic on it.
+ When the variable for which the magic is invoked is an array
+ or an hash, $_[2] is a either an alias or a copy of the
+ current key, and $_[3] is an alias to the current element
+ (i.e. the value). Since $_[2] might be a copy, it is useless
+ to try to change it or cast magic on it.
+
+ Starting from perl 5.17.0, this magic can also be called for
+ code references. In this case, $_[2] is always "undef" and
+ $_[3] is a reference to the cloned anonymous subroutine.
* *fetch*, *store*, *exists* and *delete*
Both result in a small performance hit, but just getting the name is
lighter than getting the op object.
- These callbacks are executed in scalar context and are expected to
- return an integer, which is then passed straight to the perl magic
- API. However, only the return value of the *len* magic callback
- currently holds a meaning.
+ These callbacks are always executed in scalar context. The returned
+ value is coerced into a signed integer, which is then passed
+ straight to the perl magic API. However, note that perl currently
+ only cares about the return value of the *len* magic callback and
+ ignores all the others. Starting with Variable::Magic 0.58, a
+ reference returned from a non-*len* magic callback will not be
+ destroyed immediately but will be allowed to survive until the end
+ of the statement that triggered the magic. This lets you use this
+ return value as a token for triggering a destructor after the
+ original magic action takes place. You can see an example of this
+ technique in the cookbook.
Each callback can be specified as :
True for perls that don't call *delete* magic when you delete an element
from a hash in void context.
+ "VMG_COMPAT_CODE_COPY_CLONE"
+ True for perls that call *copy* magic when a magical closure prototype
+ is cloned.
+
"VMG_COMPAT_GLOB_GET"
True for perls that call *get* magic for operations on globs.
Of course, this example does nothing with the values that are added
after the "cast".
+ Delayed magic actions
+ Starting with Variable::Magic 0.58, the return value of the magic
+ callbacks can be used to delay the action until after the original
+ action takes place :
+
+ my $delayed;
+ my $delayed_aux = wizard(
+ data => sub { $_[1] },
+ free => sub {
+ my ($target) = $_[1];
+ my $target_data = &getdata($target, $delayed);
+ local $target_data->{guard} = 1;
+ if (ref $target eq 'SCALAR') {
+ my $orig = $$target;
+ $$target = $target_data->{mangler}->($orig);
+ }
+ return;
+ },
+ );
+ $delayed = wizard(
+ data => sub {
+ return +{ guard => 0, mangler => $_[1] };
+ },
+ set => sub {
+ return if $_[1]->{guard};
+ my $token;
+ cast $token, $delayed_aux, $_[0];
+ return \$token;
+ },
+ );
+ my $x = 1;
+ cast $x, $delayed => sub { $_[0] * 2 };
+ $x = 2;
+ # $x is now 4
+ # But note that the delayed action only takes place at the end of the
+ # current statement :
+ my @y = ($x = 5, $x);
+ # $x is now 10, but @y is (5, 5)
+
PERL MAGIC HISTORY
The places where magic is invoked have changed a bit through perl
history. Here is a little list of the most recent ones.
A C compiler. This module may happen to build with a C++ compiler as
well, but don't rely on it, as no guarantee is made in this regard.
- Carp (core since perl 5), XSLoader (since 5.006).
-
- Copy tests need Tie::Array (core since perl 5.005) and Tie::Hash (since
- 5.002). Some uvar tests need Hash::Util::FieldHash (since 5.009004).
- Glob tests need Symbol (since 5.002). Threads tests need threads and
- threads::shared (both since 5.007003).
+ Carp (core since perl 5), XSLoader (since 5.6.0).
SEE ALSO
perlguts and perlapi for internal information about magic.
perldoc Variable::Magic
- Tests code coverage report is available at
- <http://www.profvince.com/perl/cover/Variable-Magic>.
-
COPYRIGHT & LICENSE
- Copyright 2007,2008,2009,2010,2011,2012 Vincent Pit, all rights
- reserved.
+ Copyright 2007,2008,2009,2010,2011,2012,2013,2014,2015,2016 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.