package Variable::Magic;
-use 5.007003;
+use 5.008;
use strict;
use warnings;
=head1 VERSION
-Version 0.28
+Version 0.30
=cut
our $VERSION;
BEGIN {
- $VERSION = '0.28';
+ $VERSION = '0.30';
}
=head1 SYNOPSIS
=head1 DESCRIPTION
Magic is Perl way of enhancing objects.
-This mechanism let 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.
+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.
-Magic differs from tieing and overloading in several ways :
+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 C<$!>, C<$(> or C<$^W>, the C<%ENV> and C<%SIG> hashes, the C<@ISA> array, C<vec()> and C<substr()> lvalues, L<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 :
=over 4
=item *
-Magic isn't copied on assignation (as for blessed references) : you attach it to variables, not values.
+It isn't copied on assignment.
+
+You attach it to variables, not values (as for blessed references).
+
+=item *
+
+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 C<tie>, where you have to provide fallbacks methods for all actions by usually inheriting from the correct C<Tie::Std*> class and overriding individual methods in your own class.
=item *
-It doesn't replace the original semantics : magic callbacks trigger before the original action take place, and can't prevent it to happen.
+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.
=item *
-It's mostly invisible at the Perl level : magical and non-magical variables cannot be distinguished with C<ref>, C<reftype> or another trick.
+It's mostly invisible at the Perl level.
+
+Magical and non-magical variables cannot be distinguished with C<ref>, C<tied> or another trick.
=item *
-It's notably faster, since perl's way of handling magic is lighter by nature, and there's no need for any method resolution.
+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.
=back
C<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 (C<for>, C<map> or C<grep>).
+Typically, it's the magic involved when an array is evaluated in scalar context, but also on array assignment and loops (C<for>, C<map> or C<grep>).
The callback has then to return the length as an integer.
=item *
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).
-=head1 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.
-
-=over 4
-
-=item *
-
-B<5.6.x>
-
-I<p14416> : 'copy' and 'dup' magic.
-
-=item *
-
-B<5.8.9>
-
-I<p28160> : Integration of I<p25854> (see below).
-
-I<p32542> : Integration of I<p31473> (see below).
-
-=item *
-
-B<5.9.3>
-
-I<p25854> : 'len' magic is no longer called when pushing an element into a magic array.
-
-I<p26569> : 'local' magic.
-
-=item *
-
-B<5.9.5>
-
-I<p31064> : Meaningful 'uvar' magic.
-
-I<p31473> : 'clear' magic wasn't invoked when undefining an array.
-The bug is fixed as of this version.
-
-=item *
-
-B<5.10.0>
-
-Since C<PERL_MAGIC_uvar> is uppercased, C<hv_magic_check()> triggers 'copy' magic on hash stores for (non-tied) hashes that also have 'uvar' magic.
-
-=item *
-
-B<5.11.x>
-
-I<p32969> : 'len' magic is no longer invoked when calling C<length> with a magical scalar.
-
-I<p34908> : 'len' magic is no longer called when pushing / unshifting an element into a magical array in void context.
-The C<push> part was already covered by I<p25854>.
-
-=back
-
-=head1 CONSTANTS
-
-=head2 C<SIG_MIN>
-
-The minimum integer used as a signature for user-defined magic.
-
-=head2 C<SIG_MAX>
-
-The maximum integer used as a signature for user-defined magic.
-
-=head2 C<SIG_NBR>
-
- SIG_NBR = SIG_MAX - SIG_MIN + 1
-
-=head2 C<MGf_COPY>
-
-Evaluates to true iff the 'copy' magic is available.
-
-=head2 C<MGf_DUP>
-
-Evaluates to true iff the 'dup' magic is available.
-
-=head2 C<MGf_LOCAL>
-
-Evaluates to true iff the 'local' magic is available.
-
-=head2 C<VMG_UVAR>
-
-When this constant is true, you can use the C<fetch,store,exists,delete> callbacks on hashes.
-
-=head2 C<VMG_COMPAT_ARRAY_PUSH_NOLEN>
-
-True for perls that don't call 'len' magic when you push an element in a magical array.
-
-=head2 C<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.
-
-=head2 C<VMG_COMPAT_ARRAY_UNDEF_CLEAR>
-
-True for perls that call 'clear' magic when undefining magical arrays.
-
-=head2 C<VMG_COMPAT_SCALAR_LENGTH_NOLEN>
-
-True for perls that don't call 'len' magic when taking the C<length> of a magical scalar.
-
-=head2 C<VMG_PERL_PATCHLEVEL>
-
-The perl patchlevel this module was built with, or C<0> for non-debugging perls.
-
-=head2 C<VMG_THREADSAFE>
-
-True iff this module could have been built with thread-safety features enabled.
-
=head1 FUNCTIONS
=cut
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 can be :
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, C<$_[0]> is always a reference to the magic object and C<$_[1]> is always the private data (or C<undef> when no private data constructor was supplied).
+
+Moreover, when you pass C<< op_info => $num >> to C<wizard>, the last element of C<@_> will be the current op name if C<$num == VMG_OP_INFO_NAME> and a C<B::OP> object representing the current op if C<$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 :
=over 8
-=item -
+=item *
C<len>
-When the variable is an array, C<$_[2]> contains the normal length.
-The callback is also expected to return the new scalar or array length.
+When the variable is an array or a scalar, C<$_[2]> contains the non-magical length.
+The callback can return the new scalar or array length to use, or C<undef> to default to the normal length.
-=item -
+=item *
C<copy>
C<$_[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.
C<$_[3]> is an alias to the current element (i.e. the value).
-=item -
+=item *
C<fetch>, C<store>, C<exists> and C<delete>
sub wizard {
croak 'Wrong number of arguments for wizard()' if @_ % 2;
my %opts = @_;
- my @keys = qw/sig data get set len clear free/;
+ my @keys = qw/sig data op_info get set len clear free/;
push @keys, 'copy' if MGf_COPY;
push @keys, 'dup' if MGf_DUP;
push @keys, 'local' if MGf_LOCAL;
my $x;
die 'error' unless cast $x, $wiz;
+The C<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 C<POSIX::tzset> each time the C<'TZ'> environment variable is changed in C<%ENV>, you can use :
+
+ use POSIX;
+ cast $ENV{TZ}, wizard set => sub { POSIX::tzset(); () };
+
+If you want to overcome the possible deletion of the C<'TZ'> entry, you have no choice but to rely on C<store> uvar magic.
+
=head2 C<getdata>
getdata [$@%&*]var, [$wiz|$sig]
# Dispell now. If $wiz isn't a signature, undef can't be returned.
die 'no such magic or error' unless dispell $x, $wiz;
+=head1 CONSTANTS
+
+=head2 C<SIG_MIN>
+
+The minimum integer used as a signature for user-defined magic.
+
+=head2 C<SIG_MAX>
+
+The maximum integer used as a signature for user-defined magic.
+
+=head2 C<SIG_NBR>
+
+ SIG_NBR = SIG_MAX - SIG_MIN + 1
+
+=head2 C<MGf_COPY>
+
+Evaluates to true iff the 'copy' magic is available.
+
+=head2 C<MGf_DUP>
+
+Evaluates to true iff the 'dup' magic is available.
+
+=head2 C<MGf_LOCAL>
+
+Evaluates to true iff the 'local' magic is available.
+
+=head2 C<VMG_UVAR>
+
+When this constant is true, you can use the C<fetch,store,exists,delete> callbacks on hashes.
+
+=head2 C<VMG_COMPAT_ARRAY_PUSH_NOLEN>
+
+True for perls that don't call 'len' magic when you push an element in a magical array.
+
+=head2 C<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.
+
+=head2 C<VMG_COMPAT_ARRAY_UNDEF_CLEAR>
+
+True for perls that call 'clear' magic when undefining magical arrays.
+
+=head2 C<VMG_COMPAT_SCALAR_LENGTH_NOLEN>
+
+True for perls that don't call 'len' magic when taking the C<length> of a magical scalar.
+
+=head2 C<VMG_PERL_PATCHLEVEL>
+
+The perl patchlevel this module was built with, or C<0> for non-debugging perls.
+
+=head2 C<VMG_THREADSAFE>
+
+True iff this module could have been built with thread-safety features enabled.
+
+=head2 C<VMG_OP_INFO_NAME>
+
+Value to pass with C<op_info> to get the current op name in the magic callbacks.
+
+=head2 C<VMG_OP_INFO_OBJECT>
+
+Value to pass with C<op_info> to get a C<B::OP> object representing the current op in the magic callbacks.
+
+=head1 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.
+
+=over 4
+
+=item *
+
+B<5.6.x>
+
+I<p14416> : 'copy' and 'dup' magic.
+
+=item *
+
+B<5.8.9>
+
+I<p28160> : Integration of I<p25854> (see below).
+
+I<p32542> : Integration of I<p31473> (see below).
+
+=item *
+
+B<5.9.3>
+
+I<p25854> : 'len' magic is no longer called when pushing an element into a magic array.
+
+I<p26569> : 'local' magic.
+
+=item *
+
+B<5.9.5>
+
+I<p31064> : Meaningful 'uvar' magic.
+
+I<p31473> : 'clear' magic wasn't invoked when undefining an array.
+The bug is fixed as of this version.
+
+=item *
+
+B<5.10.0>
+
+Since C<PERL_MAGIC_uvar> is uppercased, C<hv_magic_check()> triggers 'copy' magic on hash stores for (non-tied) hashes that also have 'uvar' magic.
+
+=item *
+
+B<5.11.x>
+
+I<p32969> : 'len' magic is no longer invoked when calling C<length> with a magical scalar.
+
+I<p34908> : 'len' magic is no longer called when pushing / unshifting an element into a magical array in void context.
+The C<push> part was already covered by I<p25854>.
+
+=back
+
=head1 EXPORT
The functions L</wizard>, L</gensig>, L</getsig>, L</cast>, L</getdata> and L</dispell> are only exported on request.
All of them are exported by the tags C<':funcs'> and C<':all'>.
-The constants L</SIG_MIN>, L</SIG_MAX>, L</SIG_NBR>, L</MGf_COPY>, L</MGf_DUP>, L</MGf_LOCAL> and L</VMG_UVAR> are also only exported on request.
-They are all exported by the tags C<':consts'> and C<':all'>.
+All the constants are also only exported on request, either individually or by the tags C<':consts'> and C<':all'>.
=cut
our @EXPORT = ();
our %EXPORT_TAGS = (
'funcs' => [ qw/wizard gensig getsig cast getdata dispell/ ],
- 'consts' => [ qw/SIG_MIN SIG_MAX SIG_NBR MGf_COPY MGf_DUP MGf_LOCAL VMG_UVAR/,
- qw/VMG_COMPAT_ARRAY_PUSH_NOLEN VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID VMG_COMPAT_ARRAY_UNDEF_CLEAR/,
- qw/VMG_COMPAT_SCALAR_LENGTH_NOLEN/,
+ 'consts' => [
+ qw/SIG_MIN SIG_MAX SIG_NBR MGf_COPY MGf_DUP MGf_LOCAL VMG_UVAR/,
+ qw/VMG_COMPAT_ARRAY_PUSH_NOLEN VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID VMG_COMPAT_ARRAY_UNDEF_CLEAR VMG_COMPAT_SCALAR_LENGTH_NOLEN/,
qw/VMG_PERL_PATCHLEVEL/,
- qw/VMG_THREADSAFE/ ]
+ qw/VMG_THREADSAFE/,
+ qw/VMG_OP_INFO_NAME VMG_OP_INFO_OBJECT/
+ ]
);
our @EXPORT_OK = map { @$_ } values %EXPORT_TAGS;
$EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
=head1 CAVEATS
-If you store a magic object in the private data slot, the magic won't be accessible by L</getdata> since it's not copied by assignation.
+If you store a magic object in the private data slot, the magic won't be accessible by L</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 C<free> callback and cast it on itself, this destructor won't be called because the wizard will be destroyed first.
=head1 DEPENDENCIES
-L<perl> 5.7.3.
+L<perl> 5.8.
L<Carp> (standard since perl 5), L<XSLoader> (standard since perl 5.006).
projects / perl / modules / Variable-Magic.git / blobdiff