lib/autovivification.pm

   1 package autovivification;
   2
   3 use 5.008003;
   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.10
  15
  16 =cut
  17
  18 our $VERSION;
  19 BEGIN {
  20  $VERSION = '0.10';
  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     function($arrayref->[$idx])
 114     function($hashref->{$key})
 115
 116 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.
 117 In the example, this would require C<$arrayref> (resp. C<$hashref>) to already be an array (resp. hash) reference.
 118
 119 =item *
 120
 121 C<'warn'>
 122
 123 Emits a warning when an autovivification is avoided.
 124
 125 =item *
 126
 127 C<'strict'>
 128
 129 Throws an exception when an autovivification is avoided.
 130
 131 =back
 132
 133 Each call to C<unimport> adds the specified features to the ones already in use in the current lexical scope.
 134
 135 When C<@opts> is empty, it defaults to C<< qw<fetch exists delete> >>.
 136
 137 =cut
 138
 139 my %bits = (
 140  strict => A_HINT_STRICT,
 141  warn   => A_HINT_WARN,
 142  fetch  => A_HINT_FETCH,
 143  store  => A_HINT_STORE,
 144  exists => A_HINT_EXISTS,
 145  delete => A_HINT_DELETE,
 146 );
 147
 148 sub unimport {
 149  shift;
 150  my $hint = _detag($^H{+(__PACKAGE__)}) || 0;
 151  @_ = qw<fetch exists delete> unless @_;
 152  $hint |= $bits{$_} for grep exists $bits{$_}, @_;
 153  $^H |= 0x00020000;
 154  $^H{+(__PACKAGE__)} = _tag($hint);
 155  ();
 156 }
 157
 158 =head2 C<import @opts>
 159
 160 Magically called when C<use autovivification @opts> is encountered.
 161 Disables the features given in C<@opts>, which can be the same as for L</unimport>.
 162
 163 Each call to C<import> removes the specified features to the ones already in use in the current lexical scope.
 164
 165 When C<@opts> is empty, it defaults to restoring the original Perl autovivification behaviour.
 166
 167 =cut
 168
 169 sub import {
 170  shift;
 171  my $hint = 0;
 172  if (@_) {
 173   $hint = _detag($^H{+(__PACKAGE__)}) || 0;
 174   $hint &= ~$bits{$_} for grep exists $bits{$_}, @_;
 175  }
 176  $^H |= 0x00020000;
 177  $^H{+(__PACKAGE__)} = _tag($hint);
 178  ();
 179 }
 180
 181 =head1 CONSTANTS
 182
 183 =head2 C<A_THREADSAFE>
 184
 185 True iff the module could have been built with thread-safety features enabled.
 186 This constant only has a meaning with your perl is threaded ; otherwise, it'll always be false.
 187
 188 =head2 C<A_FORKSAFE>
 189
 190 True iff this module could have been built with fork-safety features enabled.
 191 This will always be true except on Windows where it's false for perl 5.10.0 and below.
 192
 193 =head1 CAVEATS
 194
 195 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} >>.
 196 This syntax is valid Perl, yet it's discouraged as the slice is here useless since the dereferencing enforces scalar context.
 197 If warnings are turned on, Perl will complain about one-element slices.
 198
 199 =head1 DEPENDENCIES
 200
 201 L<perl> 5.8.3.
 202
 203 A C compiler.
 204 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.
 205
 206 L<XSLoader> (standard since perl 5.006).
 207
 208 =head1 SEE ALSO
 209
 210 L<perlref>.
 211
 212 =head1 AUTHOR
 213
 214 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 215
 216 You can contact me by mail or on C<irc.perl.org> (vincent).
 217
 218 =head1 BUGS
 219
 220 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>.
 221 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 222
 223 =head1 SUPPORT
 224
 225 You can find documentation for this module with the perldoc command.
 226
 227     perldoc autovivification
 228
 229 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/autovivification>.
 230
 231 =head1 ACKNOWLEDGEMENTS
 232
 233 Matt S. Trout asked for it.
 234
 235 =head1 COPYRIGHT & LICENSE
 236
 237 Copyright 2009,2010,2011 Vincent Pit, all rights reserved.
 238
 239 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 240
 241 =cut
 242
 243 1; # End of autovivification