X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2Fautovivification.git;a=blobdiff_plain;f=README;h=7d750e7808d1437e2e9f1ff45299340f0d8e37cf;hp=2163a42b6db912538bc41006ca0540cd72bc58d9;hb=455d083e91062cc7e742f828db98303bc83bbc3b;hpb=45b4c5c2fa9d50471d929ed8561ada3201d58389

diff --git a/README b/README
index 2163a42..7d750e7 100644
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     autovivification - Lexically disable autovivification.
 
 VERSION
-    Version 0.03
+    Version 0.11
 
 SYNOPSIS
         no autovivification;
@@ -23,9 +23,9 @@ DESCRIPTION
     When an undefined variable is dereferenced, it gets silently upgraded to
     an array or hash reference (depending of the type of the dereferencing).
     This behaviour is called *autovivification* and usually does what you
-    mean (e.g. when you store a value) but it's sometimes unnatural or
-    surprising because your variables gets populated behind your back. This
-    is especially true when several levels of dereferencing are involved, in
+    mean (e.g. when you store a value) but it may be unnatural or surprising
+    because your variables gets populated behind your back. This is
+    especially true when several levels of dereferencing are involved, in
     which case all levels are vivified up to the last, or when it happens in
     intuitively read-only constructs like "exists".
 
@@ -33,58 +33,92 @@ DESCRIPTION
     optionally throws a warning or an error when it would have happened.
 
 METHODS
-  "unimport @opts"
-    Magically called when "no autovivification" is encountered. Enables the
-    features given in @opts, which can be :
+  "unimport"
+        no autovivification; # defaults to qw<fetch exists delete>
+        no autovivification qw<fetch store exists delete>;
+        no autovivification 'warn';
+        no autovivification 'strict';
+
+    Magically called when "no autovivification @opts" is encountered.
+    Enables the features given in @opts, which can be :
 
     *   'fetch'
 
-        Turn off autovivification for rvalue dereferencing expressions, such
-        as "$value = $hashref->{key}[$idx]{$field}", "keys
-        %{$hashref->{key}}" or "values %{$hashref->{key}}". When the
-        expression would have autovivified, "undef" is returned for a plain
-        fetch, while "keys" and "values" return 0 in scalar context and the
-        empty list in list context.
+        Turns off autovivification for rvalue dereferencing expressions,
+        such as :
+
+            $value = $arrayref->[$idx]
+            $value = $hashref->{$key}
+            keys %$hashref
+            values %$hashref
+
+        Starting from perl 5.11, it also covers "keys" and "values" on array
+        references :
+
+            keys @$arrayref
+            values @$arrayref
+
+        When the expression would have autovivified, "undef" is returned for
+        a plain fetch, while "keys" and "values" return 0 in scalar context
+        and the empty list in list context.
 
     *   'exists'
 
-        Turn off autovivification for dereferencing expressions that are
-        parts of an "exists", such as "exists
-        $hashref->{key}[$idx]{$field}". '' is returned when the expression
-        would have autovivified.
+        Turns off autovivification for dereferencing expressions that are
+        parts of an "exists", such as :
+
+            exists $arrayref->[$idx]
+            exists $hashref->{$key}
+
+        '' is returned when the expression would have autovivified.
 
     *   'delete'
 
-        Turn off autovivification for dereferencing expressions that are
-        parts of a "delete", such as "delete $hashref->{key}[$idx]{$field}".
+        Turns off autovivification for dereferencing expressions that are
+        parts of a "delete", such as :
+
+            delete $arrayref->[$idx]
+            delete $hashref->{$key}
+
         "undef" is returned when the expression would have autovivified.
 
     *   'store'
 
-        Turn off autovivification for lvalue dereferencing expressions, such
-        as "$hashref->{key}[$idx]{$field} = $value" or "for
-        ($hashref->{key}[$idx]{$field}) { ... }". An exception is thrown if
-        vivification is needed to store the value, which means that
-        effectively you can only assign to levels that are already defined
-        (in the example, this would require "$hashref->{key}[$idx]" to
-        already be a hash reference).
+        Turns off autovivification for lvalue dereferencing expressions,
+        such as :
+
+            $arrayref->[$idx] = $value
+            $hashref->{$key} = $value
+            for ($arrayref->[$idx]) { ... }
+            for ($hashref->{$key}) { ... }
+            function($arrayref->[$idx])
+            function($hashref->{$key})
+
+        An exception is thrown if vivification is needed to store the value,
+        which means that effectively you can only assign to levels that are
+        already defined. In the example, this would require $arrayref (resp.
+        $hashref) to already be an array (resp. hash) reference.
 
     *   'warn'
 
-        Emit a warning when an autovivification is avoided.
+        Emits a warning when an autovivification is avoided.
 
     *   'strict'
 
-        Throw an exception when an autovivification is avoided.
+        Throws an exception when an autovivification is avoided.
 
     Each call to "unimport" adds the specified features to the ones already
     in use in the current lexical scope.
 
-    When @opts is empty, it defaults to "qw/fetch exists delete/".
+    When @opts is empty, it defaults to "qw<fetch exists delete>".
 
-  "import @opts"
-    Magically called when "use autovivification" is encountered. Disables
-    the features given in @opts, which can be the same as for "unimport".
+  "import"
+        use autovivification; # default Perl behaviour
+        use autovivification qw<fetch store exists delete>;
+
+    Magically called when "use autovivification @opts" is encountered.
+    Disables the features given in @opts, which can be the same as for
+    "unimport".
 
     Each call to "import" removes the specified features to the ones already
     in use in the current lexical scope.
@@ -92,8 +126,30 @@ METHODS
     When @opts is empty, it defaults to restoring the original Perl
     autovivification behaviour.
 
+CONSTANTS
+  "A_THREADSAFE"
+    True if and only if the module could have been built with thread-safety
+    features enabled. This constant only has a meaning when your perl is
+    threaded, otherwise it will always be false.
+
+  "A_FORKSAFE"
+    True if and only if this module could have been built with fork-safety
+    features enabled. This constant will always be true, except on Windows
+    where it is false for perl 5.10.0 and below.
+
+CAVEATS
+    The pragma doesn't apply when one dereferences the returned value of an
+    array or hash slice, as in "@array[$id]->{member}" or
+    @hash{$key}->{member}. This syntax is valid Perl, yet it is discouraged
+    as the slice is here useless since the dereferencing enforces scalar
+    context. If warnings are turned on, Perl will complain about one-element
+    slices.
+
 DEPENDENCIES
-    perl 5.8.
+    perl 5.8.3.
+
+    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.
 
     XSLoader (standard since perl 5.006).
 
@@ -124,7 +180,7 @@ ACKNOWLEDGEMENTS
     Matt S. Trout asked for it.
 
 COPYRIGHT & LICENSE
-    Copyright 2009 Vincent Pit, all rights reserved.
+    Copyright 2009,2010,2011,2012,2013 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.