README

   1 NAME
   2     autovivification - Lexically disable autovivification.
   3
   4 VERSION
   5     Version 0.10
   6
   7 SYNOPSIS
   8         no autovivification;
   9
  10         my $hashref;
  11
  12         my $a = $hashref->{key_a};       # $hashref stays undef
  13
  14         if (exists $hashref->{option}) { # Still undef
  15          ...
  16         }
  17
  18         delete $hashref->{old};          # Still undef again
  19
  20         $hashref->{new} = $value;        # Vivifies to { new => $value }
  21
  22 DESCRIPTION
  23     When an undefined variable is dereferenced, it gets silently upgraded to
  24     an array or hash reference (depending of the type of the dereferencing).
  25     This behaviour is called *autovivification* and usually does what you
  26     mean (e.g. when you store a value) but it's sometimes unnatural or
  27     surprising because your variables gets populated behind your back. This
  28     is especially true when several levels of dereferencing are involved, in
  29     which case all levels are vivified up to the last, or when it happens in
  30     intuitively read-only constructs like "exists".
  31
  32     This pragma lets you disable autovivification for some constructs and
  33     optionally throws a warning or an error when it would have happened.
  34
  35 METHODS
  36   "unimport @opts"
  37     Magically called when "no autovivification @opts" is encountered.
  38     Enables the features given in @opts, which can be :
  39
  40     *   'fetch'
  41
  42         Turns off autovivification for rvalue dereferencing expressions,
  43         such as :
  44
  45             $value = $arrayref->[$idx]
  46             $value = $hashref->{$key}
  47             keys %$hashref
  48             values %$hashref
  49
  50         Starting from perl 5.11, it also covers "keys" and "values" on array
  51         references :
  52
  53             keys @$arrayref
  54             values @$arrayref
  55
  56         When the expression would have autovivified, "undef" is returned for
  57         a plain fetch, while "keys" and "values" return 0 in scalar context
  58         and the empty list in list context.
  59
  60     *   'exists'
  61
  62         Turns off autovivification for dereferencing expressions that are
  63         parts of an "exists", such as :
  64
  65             exists $arrayref->[$idx]
  66             exists $hashref->{$key}
  67
  68         '' is returned when the expression would have autovivified.
  69
  70     *   'delete'
  71
  72         Turns off autovivification for dereferencing expressions that are
  73         parts of a "delete", such as :
  74
  75             delete $arrayref->[$idx]
  76             delete $hashref->{$key}
  77
  78         "undef" is returned when the expression would have autovivified.
  79
  80     *   'store'
  81
  82         Turns off autovivification for lvalue dereferencing expressions,
  83         such as :
  84
  85             $arrayref->[$idx] = $value
  86             $hashref->{$key} = $value
  87             for ($arrayref->[$idx]) { ... }
  88             for ($hashref->{$key}) { ... }
  89             function($arrayref->[$idx])
  90             function($hashref->{$key})
  91
  92         An exception is thrown if vivification is needed to store the value,
  93         which means that effectively you can only assign to levels that are
  94         already defined In the example, this would require $arrayref (resp.
  95         $hashref) to already be an array (resp. hash) reference.
  96
  97     *   'warn'
  98
  99         Emits a warning when an autovivification is avoided.
 100
 101     *   'strict'
 102
 103         Throws an exception when an autovivification is avoided.
 104
 105     Each call to "unimport" adds the specified features to the ones already
 106     in use in the current lexical scope.
 107
 108     When @opts is empty, it defaults to "qw<fetch exists delete>".
 109
 110   "import @opts"
 111     Magically called when "use autovivification @opts" is encountered.
 112     Disables the features given in @opts, which can be the same as for
 113     "unimport".
 114
 115     Each call to "import" removes the specified features to the ones already
 116     in use in the current lexical scope.
 117
 118     When @opts is empty, it defaults to restoring the original Perl
 119     autovivification behaviour.
 120
 121 CONSTANTS
 122   "A_THREADSAFE"
 123     True iff the module could have been built with thread-safety features
 124     enabled. This constant only has a meaning with your perl is threaded ;
 125     otherwise, it'll always be false.
 126
 127   "A_FORKSAFE"
 128     True iff this module could have been built with fork-safety features
 129     enabled. This will always be true except on Windows where it's false for
 130     perl 5.10.0 and below .
 131
 132 CAVEATS
 133     The pragma doesn't apply when one dereferences the returned value of an
 134     array or hash slice, as in "@array[$id]->{member}" or
 135     @hash{$key}->{member}. This syntax is valid Perl, yet it's discouraged
 136     as the slice is here useless since the dereferencing enforces scalar
 137     context. If warnings are turned on, Perl will complain about one-element
 138     slices.
 139
 140 DEPENDENCIES
 141     perl 5.8.3.
 142
 143     A C compiler. This module may happen to build with a C++ compiler as
 144     well, but don't rely on it, as no guarantee is made in this regard.
 145
 146     XSLoader (standard since perl 5.006).
 147
 148 SEE ALSO
 149     perlref.
 150
 151 AUTHOR
 152     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 153
 154     You can contact me by mail or on "irc.perl.org" (vincent).
 155
 156 BUGS
 157     Please report any bugs or feature requests to "bug-autovivification at
 158     rt.cpan.org", or through the web interface at
 159     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=autovivification>. I
 160     will be notified, and then you'll automatically be notified of progress
 161     on your bug as I make changes.
 162
 163 SUPPORT
 164     You can find documentation for this module with the perldoc command.
 165
 166         perldoc autovivification
 167
 168     Tests code coverage report is available at
 169     <http://www.profvince.com/perl/cover/autovivification>.
 170
 171 ACKNOWLEDGEMENTS
 172     Matt S. Trout asked for it.
 173
 174 COPYRIGHT & LICENSE
 175     Copyright 2009,2010,2011 Vincent Pit, all rights reserved.
 176
 177     This program is free software; you can redistribute it and/or modify it
 178     under the same terms as Perl itself.
 179