autovivification - Lexically disable autovivification.
VERSION
- Version 0.03
+ Version 0.18
SYNOPSIS
no autovivification;
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".
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 => @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<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.
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.
perldoc autovivification
- 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,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.
projects / perl / modules / autovivification.git / blobdiff