| 1 | package autovivification; | ||||||||||||
| 2 | |||||||||||||
| 3 | 15 | ▶ | use 5.008_003; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 4 | |||||||||||||
| 5 | 15 | ▶ | use strict; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 6 | 15 | ▶ | use warnings; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 7 | |||||||||||||
| 8 | =head1 NAME | ||||||||||||
| 9 | |||||||||||||
| 10 | autovivification - Lexically disable autovivification. | ||||||||||||
| 11 | |||||||||||||
| 12 | =head1 VERSION | ||||||||||||
| 13 | |||||||||||||
| 14 | Version 0.18 | ||||||||||||
| 15 | |||||||||||||
| 16 | =cut | ||||||||||||
| 17 | |||||||||||||
| 18 | 15 | our $VERSION; | |||||||||||
| 19 | 15 | ▶ | BEGIN { | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 20 | 15 | $VERSION = '0.18'; | |||||||||||
| 21 | } | ||||||||||||
| 22 | |||||||||||||
| 23 | =head1 SYNOPSIS | ||||||||||||
| 24 | |||||||||||||
| 25 | no autovivification; | ||||||||||||
| 26 | |||||||||||||
| 27 | my $hashref; | ||||||||||||
| 28 | |||||||||||||
| 29 | my $a = $hashref->{key_a}; # $hashref stays undef | ||||||||||||
| 30 | |||||||||||||
| 31 | if (exists $hashref->{option}) { # Still undef | ||||||||||||
| 32 | ... | ||||||||||||
| 33 | } | ||||||||||||
| 34 | |||||||||||||
| 35 | delete $hashref->{old}; # Still undef again | ||||||||||||
| 36 | |||||||||||||
| 37 | $hashref->{new} = $value; # Vivifies to { new => $value } | ||||||||||||
| 38 | |||||||||||||
| 39 | =head1 DESCRIPTION | ||||||||||||
| 40 | |||||||||||||
| 41 | When an undefined variable is dereferenced, it gets silently upgraded to an array or hash reference (depending of the type of the dereferencing). | ||||||||||||
| 42 | This behaviour is called I<autovivification> and usually does what you mean (e.g. when you store a value) but it may be unnatural or surprising because your variables gets populated behind your back. | ||||||||||||
| 43 | 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 C<exists>. | ||||||||||||
| 44 | |||||||||||||
| 45 | This pragma lets you disable autovivification for some constructs and optionally throws a warning or an error when it would have happened. | ||||||||||||
| 46 | |||||||||||||
| 47 | =cut | ||||||||||||
| 48 | |||||||||||||
| 49 | 15 | ▶ | BEGIN { | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 50 | 15 | require XSLoader; | |||||||||||
| 51 | 15 | XSLoader::load(__PACKAGE__, $VERSION); | |||||||||||
| 52 | } | ||||||||||||
| 53 | |||||||||||||
| 54 | =head1 METHODS | ||||||||||||
| 55 | |||||||||||||
| 56 | =head2 C<unimport> | ||||||||||||
| 57 | |||||||||||||
| 58 | no autovivification; # defaults to qw<fetch exists delete> | ||||||||||||
| 59 | no autovivification qw<fetch store exists delete>; | ||||||||||||
| 60 | no autovivification warn => @categories; | ||||||||||||
| 61 | no autovivification strict => @categories; | ||||||||||||
| 62 | |||||||||||||
| 63 | Magically called when C<no autovivification @opts> is encountered. | ||||||||||||
| 64 | Enables the features given in C<@opts>, which can be : | ||||||||||||
| 65 | |||||||||||||
| 66 | =over 4 | ||||||||||||
| 67 | |||||||||||||
| 68 | =item * | ||||||||||||
| 69 | |||||||||||||
| 70 | C<'fetch'> | ||||||||||||
| 71 | |||||||||||||
| 72 | Turns off autovivification for rvalue dereferencing expressions, such as : | ||||||||||||
| 73 | |||||||||||||
| 74 | $value = $arrayref->[$idx] | ||||||||||||
| 75 | $value = $hashref->{$key} | ||||||||||||
| 76 | keys %$hashref | ||||||||||||
| 77 | values %$hashref | ||||||||||||
| 78 | |||||||||||||
| 79 | Starting from perl C<5.11>, it also covers C<keys> and C<values> on array references : | ||||||||||||
| 80 | |||||||||||||
| 81 | keys @$arrayref | ||||||||||||
| 82 | values @$arrayref | ||||||||||||
| 83 | |||||||||||||
| 84 | When the expression would have autovivified, C<undef> is returned for a plain fetch, while C<keys> and C<values> return C<0> in scalar context and the empty list in list context. | ||||||||||||
| 85 | |||||||||||||
| 86 | =item * | ||||||||||||
| 87 | |||||||||||||
| 88 | C<'exists'> | ||||||||||||
| 89 | |||||||||||||
| 90 | Turns off autovivification for dereferencing expressions that are parts of an C<exists>, such as : | ||||||||||||
| 91 | |||||||||||||
| 92 | exists $arrayref->[$idx] | ||||||||||||
| 93 | exists $hashref->{$key} | ||||||||||||
| 94 | |||||||||||||
| 95 | C<''> is returned when the expression would have autovivified. | ||||||||||||
| 96 | |||||||||||||
| 97 | =item * | ||||||||||||
| 98 | |||||||||||||
| 99 | C<'delete'> | ||||||||||||
| 100 | |||||||||||||
| 101 | Turns off autovivification for dereferencing expressions that are parts of a C<delete>, such as : | ||||||||||||
| 102 | |||||||||||||
| 103 | delete $arrayref->[$idx] | ||||||||||||
| 104 | delete $hashref->{$key} | ||||||||||||
| 105 | |||||||||||||
| 106 | C<undef> is returned when the expression would have autovivified. | ||||||||||||
| 107 | |||||||||||||
| 108 | =item * | ||||||||||||
| 109 | |||||||||||||
| 110 | C<'store'> | ||||||||||||
| 111 | |||||||||||||
| 112 | Turns off autovivification for lvalue dereferencing expressions, such as : | ||||||||||||
| 113 | |||||||||||||
| 114 | $arrayref->[$idx] = $value | ||||||||||||
| 115 | $hashref->{$key} = $value | ||||||||||||
| 116 | for ($arrayref->[$idx]) { ... } | ||||||||||||
| 117 | for ($hashref->{$key}) { ... } | ||||||||||||
| 118 | function($arrayref->[$idx]) | ||||||||||||
| 119 | function($hashref->{$key}) | ||||||||||||
| 120 | |||||||||||||
| 121 | 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. | ||||||||||||
| 122 | In the example, this would require C<$arrayref> (resp. C<$hashref>) to already be an array (resp. hash) reference. | ||||||||||||
| 123 | |||||||||||||
| 124 | =item * | ||||||||||||
| 125 | |||||||||||||
| 126 | C<'warn'> | ||||||||||||
| 127 | |||||||||||||
| 128 | Emits a warning when an autovivification is avoided for the categories specified in C<@opts>. | ||||||||||||
| 129 | |||||||||||||
| 130 | Note that C<no autovivification 'warn'> currently does nothing by itself, in particular it does not make the default categories warn. | ||||||||||||
| 131 | This behaviour may change in a future version of this pragma. | ||||||||||||
| 132 | |||||||||||||
| 133 | =item * | ||||||||||||
| 134 | |||||||||||||
| 135 | C<'strict'> | ||||||||||||
| 136 | |||||||||||||
| 137 | Throws an exception when an autovivification is avoided for the categories specified in C<@opts>. | ||||||||||||
| 138 | |||||||||||||
| 139 | Note that C<no autovivification 'strict'> currently does nothing by itself, in particular it does not make the default categories die. | ||||||||||||
| 140 | This behaviour may change in a future version of this pragma. | ||||||||||||
| 141 | |||||||||||||
| 142 | =back | ||||||||||||
| 143 | |||||||||||||
| 144 | Each call to C<unimport> B<adds> the specified features to the ones already in use in the current lexical scope. | ||||||||||||
| 145 | |||||||||||||
| 146 | When C<@opts> is empty, it defaults to C<< qw<fetch exists delete> >>. | ||||||||||||
| 147 | |||||||||||||
| 148 | =cut | ||||||||||||
| 149 | |||||||||||||
| 150 | 15 | my %bits = ( | |||||||||||
| 151 | strict => A_HINT_STRICT, | ||||||||||||
| 152 | warn => A_HINT_WARN, | ||||||||||||
| 153 | fetch => A_HINT_FETCH|A_HINT_KEYS|A_HINT_VALUES, | ||||||||||||
| 154 | store => A_HINT_STORE, | ||||||||||||
| 155 | exists => A_HINT_EXISTS, | ||||||||||||
| 156 | delete => A_HINT_DELETE, | ||||||||||||
| 157 | ); | ||||||||||||
| 158 | |||||||||||||
| 159 | 20463 | ▶ | sub unimport { | ||||||||||
|
Subroutine
unimport: called CC=4 SCAR=13.9
| |||||||||||||
| 160 | 20463 | shift; | |||||||||||
| 161 | 20463 | ▶ | my $hint = _detag($^H{+(__PACKAGE__)}) || 0; | ||||||||||
|
Condition100%2/2
&_detag($^H{__PACKAGE__()}) || 0
MC/DC100%1/1
&_detag($^H{__PACKAGE__()}) || 0
&_detag($^H{__PACKAGE__()})
Truth table100%2/2
A
A= &_detag($^H{__PACKAGE__()})
| |||||||||||||
| 162 | 20463 | ▶ | @_ = qw<fetch exists delete> unless @_; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 163 | 20463 | $hint |= $bits{$_} for grep exists $bits{$_}, @_; | |||||||||||
| 164 | 20463 | $^H |= 0x00020000; | |||||||||||
| 165 | 20463 | $^H{+(__PACKAGE__)} = _tag($hint); | |||||||||||
| 166 | 20463 | (); | |||||||||||
| 167 | } | ||||||||||||
| 168 | |||||||||||||
| 169 | =head2 C<import> | ||||||||||||
| 170 | |||||||||||||
| 171 | use autovivification; # default Perl behaviour | ||||||||||||
| 172 | use autovivification qw<fetch store exists delete>; | ||||||||||||
| 173 | |||||||||||||
| 174 | Magically called when C<use autovivification @opts> is encountered. | ||||||||||||
| 175 | Disables the features given in C<@opts>, which can be the same as for L</unimport>. | ||||||||||||
| 176 | |||||||||||||
| 177 | Each call to C<import> B<removes> the specified features to the ones already in use in the current lexical scope. | ||||||||||||
| 178 | |||||||||||||
| 179 | When C<@opts> is empty, it defaults to restoring the original Perl autovivification behaviour. | ||||||||||||
| 180 | |||||||||||||
| 181 | =cut | ||||||||||||
| 182 | |||||||||||||
| 183 | 109 | ▶ | sub import { | ||||||||||
|
Subroutine
import: called CC=4 SCAR=13.9
| |||||||||||||
| 184 | 109 | shift; | |||||||||||
| 185 | 109 | my $hint = 0; | |||||||||||
| 186 | 109 | ▶ | if (@_) { | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 187 | 108 | ▶ | $hint = _detag($^H{+(__PACKAGE__)}) || 0; | ||||||||||
|
Condition100%2/2
&_detag($^H{__PACKAGE__()}) || 0
MC/DC100%1/1
&_detag($^H{__PACKAGE__()}) || 0
&_detag($^H{__PACKAGE__()})
Truth table100%2/2
A
A= &_detag($^H{__PACKAGE__()})
| |||||||||||||
| 188 | 108 | $hint &= ~$bits{$_} for grep exists $bits{$_}, @_; | |||||||||||
| 189 | } | ||||||||||||
| 190 | 109 | $^H |= 0x00020000; | |||||||||||
| 191 | 109 | $^H{+(__PACKAGE__)} = _tag($hint); | |||||||||||
| 192 | 109 | (); | |||||||||||
| 193 | } | ||||||||||||
| 194 | |||||||||||||
| 195 | =head1 CONSTANTS | ||||||||||||
| 196 | |||||||||||||
| 197 | =head2 C<A_THREADSAFE> | ||||||||||||
| 198 | |||||||||||||
| 199 | True if and only if the module could have been built with thread-safety features enabled. | ||||||||||||
| 200 | This constant only has a meaning when your perl is threaded, otherwise it will always be false. | ||||||||||||
| 201 | |||||||||||||
| 202 | =head2 C<A_FORKSAFE> | ||||||||||||
| 203 | |||||||||||||
| 204 | True if and only if this module could have been built with fork-safety features enabled. | ||||||||||||
| 205 | This constant will always be true, except on Windows where it is false for perl 5.10.0 and below. | ||||||||||||
| 206 | |||||||||||||
| 207 | =head1 CAVEATS | ||||||||||||
| 208 | |||||||||||||
| 209 | 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 C<no autovivification> - which may become noticeable if you rely heavily on numerous calls to C<eval STRING>. | ||||||||||||
| 210 | |||||||||||||
| 211 | The pragma doesn't apply when one dereferences the returned value of an array or hash slice, as in C<< @array[$id]->{member} >> or C<< @hash{$key}->{member} >>. | ||||||||||||
| 212 | This syntax is valid Perl, yet it is discouraged as the slice is here useless since the dereferencing enforces scalar context. | ||||||||||||
| 213 | If warnings are turned on, Perl will complain about one-element slices. | ||||||||||||
| 214 | |||||||||||||
| 215 | Autovivifications that happen in code C<eval>'d during the global destruction phase of a spawned thread or pseudo-fork (the processes used internally for the C<fork> emulation on Windows) are not reported. | ||||||||||||
| 216 | |||||||||||||
| 217 | =head1 DEPENDENCIES | ||||||||||||
| 218 | |||||||||||||
| 219 | L<perl> 5.8.3. | ||||||||||||
| 220 | |||||||||||||
| 221 | A C compiler. | ||||||||||||
| 222 | 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. | ||||||||||||
| 223 | |||||||||||||
| 224 | L<XSLoader> (standard since perl 5.6.0). | ||||||||||||
| 225 | |||||||||||||
| 226 | =head1 SEE ALSO | ||||||||||||
| 227 | |||||||||||||
| 228 | L<perlref>. | ||||||||||||
| 229 | |||||||||||||
| 230 | =head1 AUTHOR | ||||||||||||
| 231 | |||||||||||||
| 232 | Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>. | ||||||||||||
| 233 | |||||||||||||
| 234 | You can contact me by mail or on C<irc.perl.org> (vincent). | ||||||||||||
| 235 | |||||||||||||
| 236 | =head1 BUGS | ||||||||||||
| 237 | |||||||||||||
| 238 | Please report any bugs or feature requests to C<bug-autovivification at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=autovivification>. | ||||||||||||
| 239 | I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. | ||||||||||||
| 240 | |||||||||||||
| 241 | =head1 SUPPORT | ||||||||||||
| 242 | |||||||||||||
| 243 | You can find documentation for this module with the perldoc command. | ||||||||||||
| 244 | |||||||||||||
| 245 | perldoc autovivification | ||||||||||||
| 246 | |||||||||||||
| 247 | =head1 ACKNOWLEDGEMENTS | ||||||||||||
| 248 | |||||||||||||
| 249 | Matt S. Trout asked for it. | ||||||||||||
| 250 | |||||||||||||
| 251 | =head1 COPYRIGHT & LICENSE | ||||||||||||
| 252 | |||||||||||||
| 253 | Copyright 2009,2010,2011,2012,2013,2014,2015,2017 Vincent Pit, all rights reserved. | ||||||||||||
| 254 | |||||||||||||
| 255 | This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. | ||||||||||||
| 256 | |||||||||||||
| 257 | =cut | ||||||||||||
| 258 | |||||||||||||
| 259 | 15 | 1; # End of autovivification | |||||||||||