X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FVariable-Magic.git;a=blobdiff_plain;f=README;h=b10ea32ae8d3002cad4bf5842eddb182b843218d;hp=a7c09596b439f0f84ca65e2e4514f7c2b4a7a846;hb=810a63159661ab3e66c139d6f62fcd28f19ab7be;hpb=22768b2c966463cd2574d2f7f7ea5c1cf494456b diff --git a/README b/README index a7c0959..b10ea32 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.57 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* @@ -353,6 +371,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 +395,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. @@ -548,12 +574,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. @@ -581,8 +602,8 @@ SUPPORT . 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.