From: Vincent Pit Date: Sun, 14 Jun 2009 20:08:03 +0000 (+0200) Subject: This is 0.01 X-Git-Tag: v0.01 X-Git-Url: http://git.vpit.fr/?a=commitdiff_plain;h=a103f44a2cfa8ad5f0da194fe6db1c25c674d4d2;p=perl%2Fmodules%2Fautovivification.git This is 0.01 --- diff --git a/Changes b/Changes index 0389cf8..dfd6379 100644 --- a/Changes +++ b/Changes @@ -1,5 +1,5 @@ Revision history for autovivification -0.01 +0.01 2009-06-14 20:10 UTC First version, released on an unsuspecting world. diff --git a/MANIFEST b/MANIFEST index 3c387d5..a4cfc0f 100644 --- a/MANIFEST +++ b/MANIFEST @@ -15,3 +15,5 @@ t/91-pod.t t/92-pod-coverage.t t/95-portability-files.t t/99-kwalitee.t +t/lib/autovivification/TestRequired1.pm +t/lib/autovivification/TestRequired2.pm diff --git a/META.yml b/META.yml index f830880..82d09fd 100644 --- a/META.yml +++ b/META.yml @@ -1,7 +1,7 @@ --- #YAML:1.0 name: autovivification version: 0.01 -abstract: ~ +abstract: Lexically disable autovivification. author: - Vincent Pit license: perl diff --git a/README b/README index 880269e..bc02476 100644 --- a/README +++ b/README @@ -6,24 +6,96 @@ VERSION 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}". "undef" is returned + when the expression would have autovivified. + + * '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. - "import" - Magically called when "use autovivification" is encountered. Turns the - module off. + * '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 + 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. DEPENDENCIES perl 5.8. XSLoader (standard since perl 5.006). +SEE ALSO + perlref. + AUTHOR Vincent Pit, "", . @@ -44,6 +116,9 @@ SUPPORT Tests code coverage report is available at . +ACKNOWLEDGEMENTS + Matt S. Trout asked for it. + COPYRIGHT & LICENSE Copyright 2009 Vincent Pit, all rights reserved.