X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=ba89f24cb1cbd48730a3493fddd79f39005723e4;hb=d0d2f5ac7d4406b6158a57cddde7535285703c5e;hp=a7c09596b439f0f84ca65e2e4514f7c2b4a7a846;hpb=22768b2c966463cd2574d2f7f7ea5c1cf494456b;p=perl%2Fmodules%2FVariable-Magic.git diff --git a/README b/README index a7c0959..ba89f24 100644 --- a/README +++ b/README @@ -2,7 +2,7 @@ NAME Variable::Magic - Associate user-defined magic to variables from Perl. VERSION - Version 0.51 + Version 0.59 SYNOPSIS use Variable::Magic qw; @@ -72,7 +72,7 @@ DESCRIPTION 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. @@ -100,11 +100,19 @@ DESCRIPTION * *len* - This magic only applies to scalars and arrays, and is triggered when - the 'size' or the 'length' of the variable has to be known by Perl. - This is typically the magic involved when an array is evaluated in - scalar context, but also on array assignment and loops ("for", "map" - or "grep"). The length is returned from the callback as an integer. + This magic only applies to arrays (though it used to also apply to + scalars), and is triggered when the 'size' or the 'length' of the + variable has to be known by Perl. This is typically the magic + involved when an array is evaluated in scalar context, but also on + array assignment and loops ("for", "map" or "grep"). The length is + returned from the callback as an integer. + + Starting from perl 5.12, this magic is no longer called by the + "length" keyword, and starting from perl 5.17.4 it is also no longer + called for scalars in any situation, making this magic only + meaningful on arrays. You can use the constants + "VMG_COMPAT_SCALAR_LENGTH_NOLEN" and "VMG_COMPAT_SCALAR_NOLEN" to + see if this magic is available for scalars or not. * *clear* @@ -124,8 +132,13 @@ DESCRIPTION * *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* @@ -217,10 +230,15 @@ FUNCTIONS * *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* @@ -247,10 +265,17 @@ FUNCTIONS 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 : @@ -353,6 +378,10 @@ CONSTANTS True for perls that don't call *len* magic when taking the "length" of a magical scalar. + "VMG_COMPAT_SCALAR_NOLEN" + True for perls that don't call *len* magic on scalars. Implies + "VMG_COMPAT_SCALAR_LENGTH_NOLEN". + "VMG_COMPAT_ARRAY_PUSH_NOLEN" True for perls that don't call *len* magic when you push an element in a magical array. Starting from perl 5.11.0, this only refers to pushes in @@ -373,6 +402,10 @@ CONSTANTS 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. @@ -475,6 +508,45 @@ COOKBOOK 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. @@ -548,12 +620,7 @@ DEPENDENCIES 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. @@ -577,12 +644,9 @@ SUPPORT perldoc Variable::Magic - Tests code coverage report is available at - . - COPYRIGHT & LICENSE - Copyright 2007,2008,2009,2010,2011,2012 Vincent Pit, all rights - reserved. + Copyright 2007,2008,2009,2010,2011,2012,2013,2014,2015 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.