lib/autovivification.pm

   1 package autovivification;
   2
   3 use 5.008001;
   4
   5 use strict;
   6 use warnings;
   7
   8 =head1 NAME
   9
  10 autovivification - Lexically disable autovivification.
  11
  12 =head1 VERSION
  13
  14 Version 0.06
  15
  16 =cut
  17
  18 our $VERSION;
  19 BEGIN {
  20  $VERSION = '0.06';
  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's sometimes 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 BEGIN {
  50  require XSLoader;
  51  XSLoader::load(__PACKAGE__, $VERSION);
  52 }
  53
  54 =head1 METHODS
  55
  56 =head2 C<unimport @opts>
  57
  58 Magically called when C<no autovivification @opts> is encountered.
  59 Enables the features given in C<@opts>, which can be :
  60
  61 =over 4
  62
  63 =item *
  64
  65 C<'fetch'>
  66
  67 Turns off autovivification for rvalue dereferencing expressions, such as :
  68
  69     $value = $arrayref->[$idx]
  70     $value = $hashref->{$key}
  71     keys %$hashref
  72     values %$hashref
  73
  74 Starting from perl C<5.11>, it also covers C<keys> and C<values> on array references :
  75
  76     keys @$arrayref
  77     values @$arrayref
  78
  79 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.
  80
  81 =item *
  82
  83 C<'exists'>
  84
  85 Turns off autovivification for dereferencing expressions that are parts of an C<exists>, such as :
  86
  87     exists $arrayref->[$idx]
  88     exists $hashref->{$key}
  89
  90 C<''> is returned when the expression would have autovivified.
  91
  92 =item *
  93
  94 C<'delete'>
  95
  96 Turns off autovivification for dereferencing expressions that are parts of a C<delete>, such as :
  97
  98     delete $arrayref->[$idx]
  99     delete $hashref->{$key}
 100
 101 C<undef> is returned when the expression would have autovivified.
 102
 103 =item *
 104
 105 C<'store'>
 106
 107 Turns off autovivification for lvalue dereferencing expressions, such as :
 108
 109     $arrayref->[$idx] = $value
 110     $hashref->{$key} = $value
 111     for ($arrayref->[$idx]) { ... }
 112     for ($hashref->{$key}) { ... }
 113
 114 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
 115 In the example, this would require C<$arrayref> (resp. C<$hashref>) to already be an array (resp. hash) reference.
 116
 117 =item *
 118
 119 C<'warn'>
 120
 121 Emits a warning when an autovivification is avoided.
 122
 123 =item *
 124
 125 C<'strict'>
 126
 127 Throws an exception when an autovivification is avoided.
 128
 129 =back
 130
 131 Each call to C<unimport> adds the specified features to the ones already in use in the current lexical scope.
 132
 133 When C<@opts> is empty, it defaults to C<qw/fetch exists delete/>.
 134
 135 =cut
 136
 137 my %bits = (
 138  strict => A_HINT_STRICT,
 139  warn   => A_HINT_WARN,
 140  fetch  => A_HINT_FETCH,
 141  store  => A_HINT_STORE,
 142  exists => A_HINT_EXISTS,
 143  delete => A_HINT_DELETE,
 144 );
 145
 146 sub unimport {
 147  shift;
 148  my $hint = _detag($^H{+(__PACKAGE__)}) || 0;
 149  @_ = qw/fetch exists delete/ unless @_;
 150  $hint |= $bits{$_} for grep exists $bits{$_}, @_;
 151  $^H |= 0x00020000;
 152  $^H{+(__PACKAGE__)} = _tag($hint);
 153  ();
 154 }
 155
 156 =head2 C<import @opts>
 157
 158 Magically called when C<use autovivification @opts> is encountered.
 159 Disables the features given in C<@opts>, which can be the same as for L</unimport>.
 160
 161 Each call to C<import> removes the specified features to the ones already in use in the current lexical scope.
 162
 163 When C<@opts> is empty, it defaults to restoring the original Perl autovivification behaviour.
 164
 165 =cut
 166
 167 sub import {
 168  shift;
 169  my $hint = 0;
 170  if (@_) {
 171   $hint = _detag($^H{+(__PACKAGE__)}) || 0;
 172   $hint &= ~$bits{$_} for grep exists $bits{$_}, @_;
 173  }
 174  $^H |= 0x00020000;
 175  $^H{+(__PACKAGE__)} = _tag($hint);
 176  ();
 177 }
 178
 179 =head1 CONSTANTS
 180
 181 =head2 C<A_THREADSAFE>
 182
 183 True iff the module could have been built with thread-safety features enabled.
 184 This constant only has a meaning with your perl is threaded ; otherwise, it'll always be false.
 185
 186 =head2 C<A_FORKSAFE>
 187
 188 True iff this module could have been built with fork-safety features enabled.
 189 This will always be true except on Windows where it's false for perl 5.10.0 and below .
 190
 191 =head1 CAVEATS
 192
 193 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} >>.
 194 This syntax is valid Perl, yet it's discouraged as the slice is here useless since the dereferencing enforces scalar context.
 195 If warnings are turned on, Perl will complain about one-element slices.
 196
 197 =head1 DEPENDENCIES
 198
 199 L<perl> 5.8.1.
 200
 201 L<XSLoader> (standard since perl 5.006).
 202
 203 =head1 SEE ALSO
 204
 205 L<perlref>.
 206
 207 =head1 AUTHOR
 208
 209 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 210
 211 You can contact me by mail or on C<irc.perl.org> (vincent).
 212
 213 =head1 BUGS
 214
 215 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>.
 216 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 217
 218 =head1 SUPPORT
 219
 220 You can find documentation for this module with the perldoc command.
 221
 222     perldoc autovivification
 223
 224 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/autovivification>.
 225
 226 =head1 ACKNOWLEDGEMENTS
 227
 228 Matt S. Trout asked for it.
 229
 230 =head1 COPYRIGHT & LICENSE
 231
 232 Copyright 2009,2010 Vincent Pit, all rights reserved.
 233
 234 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 235
 236 =cut
 237
 238 1; # End of autovivification