X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2Fautovivification.git;a=blobdiff_plain;f=README;h=22adc68d4cc7432abfffecac801aea6e2e3158ca;hp=2163a42b6db912538bc41006ca0540cd72bc58d9;hb=HEAD;hpb=45b4c5c2fa9d50471d929ed8561ada3201d58389 diff --git a/README b/README index 2163a42..22adc68 100644 --- a/README +++ b/README @@ -2,7 +2,7 @@ NAME autovivification - Lexically disable autovivification. VERSION - Version 0.03 + Version 0.18 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,102 @@ 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 + no autovivification qw; + no autovivification warn => @categories; + no autovivification strict => @categories; + + 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 for the + categories specified in @opts. + + Note that "no autovivification 'warn'" currently does nothing by + itself, in particular it does not make the default categories warn. + This behaviour may change in a future version of this pragma. * 'strict' - Throw an exception when an autovivification is avoided. + Throws an exception when an autovivification is avoided for the + categories specified in @opts. + + Note that "no autovivification 'strict'" currently does nothing by + itself, in particular it does not make the default categories die. + This behaviour may change in a future version of this pragma. 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". - "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; + + 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,10 +136,41 @@ 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 + Using this pragma will cause a slight global slowdown of any subsequent + compilation phase that happens anywere in your code - even outside of + the scope of use of "no autovivification" - which may become noticeable + if you rely heavily on numerous calls to "eval STRING". + + 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. + + Autovivifications that happen in code "eval"'d during the global + destruction phase of a spawned thread or pseudo-fork (the processes used + internally for the "fork" emulation on Windows) are not reported. + DEPENDENCIES - perl 5.8. + perl 5.8.3. - XSLoader (standard since perl 5.006). + 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.6.0). SEE ALSO perlref. @@ -117,14 +192,12 @@ SUPPORT perldoc autovivification - Tests code coverage report is available at - . - ACKNOWLEDGEMENTS Matt S. Trout asked for it. COPYRIGHT & LICENSE - Copyright 2009 Vincent Pit, all rights reserved. + Copyright 2009,2010,2011,2012,2013,2014,2015,2017 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.