Make a_map_fetch() a simple macro around ptable_fetch() in the non-threaded case

[perl/modules/autovivification.git] / README

diff --git a/README b/README
index bc02476f9e3f05f259c232398cd3f16c35f6deb9..de9502192868d947569efe4e648b007ceb2705af 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     autovivification - Lexically disable autovivification.
 
 VERSION
-    Version 0.01
+    Version 0.06
 
 SYNOPSIS
         no autovivification;
@@ -40,8 +40,12 @@ METHODS
     *   'fetch'
 
         Turn off autovivification for rvalue dereferencing expressions, such
-        as "$value = $hashref->{key}[$idx]{$field}". "undef" is returned
-        when the expression would have autovivified.
+        as "$value = $hashref->{key}[$idx]{$field}", "keys
+        %{$hashref->{key}}" or "values %{$hashref->{key}}". Starting from
+        perl 5.11, it also covers "keys" and "values" on array references.
+        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'
 
@@ -59,8 +63,9 @@ METHODS
     *   'store'
 
         Turn off autovivification for lvalue dereferencing expressions, such
-        as "$hashref->{key}[$idx]{$field} = $value". An exception is thrown
-        if vivification is needed to store the value, which means that
+        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).
@@ -88,6 +93,25 @@ METHODS
     When @opts is empty, it defaults to restoring the original Perl
     autovivification behaviour.
 
+CONSTANTS
+  "A_THREADSAFE"
+    True iff the module could have been built with thread-safety features
+    enabled. This constant only has a meaning with your perl is threaded ;
+    otherwise, it'll always be false.
+
+  "A_FORKSAFE"
+    True iff this module could have been built with fork-safety features
+    enabled. This will always be true except on Windows where it's 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's 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.
 
@@ -120,7 +144,7 @@ ACKNOWLEDGEMENTS
     Matt S. Trout asked for it.
 
 COPYRIGHT & LICENSE
-    Copyright 2009 Vincent Pit, all rights reserved.
+    Copyright 2009,2010 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.