X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=e344be9d5592cfda31f45a83bc479fc8b2672523;hb=aae88f4cf6f2f32553f8cc29cb8f0792cb5cd910;hp=cc595c27747557e242836547d9149cf9dcd8842b;hpb=1676b9c5dcfd3a398710ce5476bcff3bf5d83a8f;p=perl%2Fmodules%2FVariable-Magic.git diff --git a/README b/README index cc595c2..e344be9 100644 --- a/README +++ b/README @@ -2,7 +2,7 @@ NAME Variable::Magic - Associate user-defined magic to variables from Perl. VERSION - Version 0.50 + Version 0.55 SYNOPSIS use Variable::Magic qw; @@ -63,13 +63,18 @@ DESCRIPTION the correct "Tie::Std*" class and overriding individual methods in your own class. + * Magic is multivalued. + + You can safely apply different kinds of magics to the same variable, + and each of them will be invoked successively. + * Magic is 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. + differently depending on the type of the variable. - * Magic is invisible at the Perl level. + * Magic is invisible at Perl level. Magical and non-magical variables cannot be distinguished with "ref", "tied" or another trick. @@ -95,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* @@ -111,14 +124,21 @@ DESCRIPTION * *free* - This magic is called when an object is destroyed as the result of - the variable going out of scope (but not when the variable is - undefined). + This magic is called when a variable is destroyed as the result of + going out of scope (but not when it is undefined). It behaves + roughly like Perl object destructors (i.e. "DESTROY" methods), + except that exceptions thrown from inside a *free* callback will + always be propagated to the surrounding code. * *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* @@ -210,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* @@ -346,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 @@ -366,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. @@ -541,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. @@ -574,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 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.