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 880269e46da66b1c75e82674b06341158e6a4aac..de9502192868d947569efe4e648b007ceb2705af 100644 (file)
--- a/README
+++ b/README
@@ -2,28 +2,124 @@ NAME
     autovivification - Lexically disable autovivification.
 
 VERSION
-    Version 0.01
+    Version 0.06
 
 SYNOPSIS
         no autovivification;
-        my $x;
-        $x->{foo} = 1; # croaks
+
+        my $hashref;
+
+        my $a = $hashref->{key_a};       # $hashref stays undef
+
+        if (exists $hashref->{option}) { # Still undef
+         ...
+        }
+
+        delete $hashref->{old};          # Still undef again
+
+        $hashref->{new} = $value;        # Vivifies to { new => $value }
 
 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
+    which case all levels are vivified up to the last, or when it happens in
+    intuitively read-only constructs like "exists".
+
+    This pragma lets you disable autovivification for some constructs and
+    optionally throws a warning or an error when it would have happened.
+
 METHODS
-  "unimport"
-    Magically called when "no autovivification" is encountered. Turns the
-    module on.
+  "unimport @opts"
+    Magically called when "no autovivification" 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}}". 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'
+
+        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.
+
+    *   'delete'
+
+        Turn off autovivification for dereferencing expressions that are
+        parts of a "delete", such as "delete $hashref->{key}[$idx]{$field}".
+        "undef" is returned when the expression would have autovivified.
+
+    *   'store'
 
-  "import"
-    Magically called when "use autovivification" is encountered. Turns the
-    module off.
+        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).
+
+    *   'warn'
+
+        Emit a warning when an autovivification is avoided.
+
+    *   'strict'
+
+        Throw 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/".
+
+  "import @opts"
+    Magically called when "use autovivification" 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.
+
+    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.
 
     XSLoader (standard since perl 5.006).
 
+SEE ALSO
+    perlref.
+
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 
@@ -44,8 +140,11 @@ SUPPORT
     Tests code coverage report is available at
     <http://www.profvince.com/perl/cover/autovivification>.
 
+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.