X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FVariable-Magic.git;a=blobdiff_plain;f=README;h=b77b8453ef9536f4c6eec27afcb6de4103bd444f;hp=cc595c27747557e242836547d9149cf9dcd8842b;hb=ae89b589d2187cf0ed57bbb6132b9d4a8da29abb;hpb=1676b9c5dcfd3a398710ce5476bcff3bf5d83a8f

diff --git a/README b/README
index cc595c2..b77b845 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.53
 
 SYNOPSIS
         use Variable::Magic qw<wizard cast VMG_OP_INFO_NAME>;
@@ -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,9 +124,11 @@ 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*
 
@@ -346,6 +361,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
@@ -541,12 +560,12 @@ 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).
+    Carp (core since perl 5), XSLoader (since 5.6.0).
 
     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).
+    5.002). Some uvar tests need Hash::Util::FieldHash (since 5.9.4). Glob
+    tests need Symbol (since 5.002). Threads tests need threads and
+    threads::shared (both since 5.7.3).
 
 SEE ALSO
     perlguts and perlapi for internal information about magic.
@@ -574,7 +593,7 @@ SUPPORT
     <http://www.profvince.com/perl/cover/Variable-Magic>.
 
 COPYRIGHT & LICENSE
-    Copyright 2007,2008,2009,2010,2011,2012 Vincent Pit, all rights
+    Copyright 2007,2008,2009,2010,2011,2012,2013 Vincent Pit, all rights
     reserved.
 
     This program is free software; you can redistribute it and/or modify it