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>.
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.