]> git.vpit.fr Git - perl/modules/autovivification.git/blob - README
Revamp module setup/teardown
[perl/modules/autovivification.git] / README
1 NAME
2     autovivification - Lexically disable autovivification.
3
4 VERSION
5     Version 0.14
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 may be unnatural or surprising
27     because your variables gets populated behind your back. This is
28     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"
37         no autovivification; # defaults to qw<fetch exists delete>
38         no autovivification qw<fetch store exists delete>;
39         no autovivification 'warn';
40         no autovivification 'strict';
41
42     Magically called when "no autovivification @opts" is encountered.
43     Enables the features given in @opts, which can be :
44
45     *   'fetch'
46
47         Turns off autovivification for rvalue dereferencing expressions,
48         such as :
49
50             $value = $arrayref->[$idx]
51             $value = $hashref->{$key}
52             keys %$hashref
53             values %$hashref
54
55         Starting from perl 5.11, it also covers "keys" and "values" on array
56         references :
57
58             keys @$arrayref
59             values @$arrayref
60
61         When the expression would have autovivified, "undef" is returned for
62         a plain fetch, while "keys" and "values" return 0 in scalar context
63         and the empty list in list context.
64
65     *   'exists'
66
67         Turns off autovivification for dereferencing expressions that are
68         parts of an "exists", such as :
69
70             exists $arrayref->[$idx]
71             exists $hashref->{$key}
72
73         '' is returned when the expression would have autovivified.
74
75     *   'delete'
76
77         Turns off autovivification for dereferencing expressions that are
78         parts of a "delete", such as :
79
80             delete $arrayref->[$idx]
81             delete $hashref->{$key}
82
83         "undef" is returned when the expression would have autovivified.
84
85     *   'store'
86
87         Turns off autovivification for lvalue dereferencing expressions,
88         such as :
89
90             $arrayref->[$idx] = $value
91             $hashref->{$key} = $value
92             for ($arrayref->[$idx]) { ... }
93             for ($hashref->{$key}) { ... }
94             function($arrayref->[$idx])
95             function($hashref->{$key})
96
97         An exception is thrown if vivification is needed to store the value,
98         which means that effectively you can only assign to levels that are
99         already defined. In the example, this would require $arrayref (resp.
100         $hashref) to already be an array (resp. hash) reference.
101
102     *   'warn'
103
104         Emits a warning when an autovivification is avoided.
105
106     *   'strict'
107
108         Throws an exception when an autovivification is avoided.
109
110     Each call to "unimport" adds the specified features to the ones already
111     in use in the current lexical scope.
112
113     When @opts is empty, it defaults to "qw<fetch exists delete>".
114
115   "import"
116         use autovivification; # default Perl behaviour
117         use autovivification qw<fetch store exists delete>;
118
119     Magically called when "use autovivification @opts" is encountered.
120     Disables the features given in @opts, which can be the same as for
121     "unimport".
122
123     Each call to "import" removes the specified features to the ones already
124     in use in the current lexical scope.
125
126     When @opts is empty, it defaults to restoring the original Perl
127     autovivification behaviour.
128
129 CONSTANTS
130   "A_THREADSAFE"
131     True if and only if the module could have been built with thread-safety
132     features enabled. This constant only has a meaning when your perl is
133     threaded, otherwise it will always be false.
134
135   "A_FORKSAFE"
136     True if and only if this module could have been built with fork-safety
137     features enabled. This constant will always be true, except on Windows
138     where it is false for perl 5.10.0 and below.
139
140 CAVEATS
141     Using this pragma will cause a slight global slowdown of any subsequent
142     compilation phase that happens anywere in your code - even outside of
143     the scope of use of "no autovivification" - which may become noticeable
144     if you rely heavily on numerous calls to "eval STRING".
145
146     The pragma doesn't apply when one dereferences the returned value of an
147     array or hash slice, as in "@array[$id]->{member}" or
148     @hash{$key}->{member}. This syntax is valid Perl, yet it is discouraged
149     as the slice is here useless since the dereferencing enforces scalar
150     context. If warnings are turned on, Perl will complain about one-element
151     slices.
152
153     Autovivifications that happen in code "eval"'d during the global
154     destruction phase of a spawned thread or pseudo-fork (the processes used
155     internally for the "fork" emulation on Windows) are not reported.
156
157 DEPENDENCIES
158     perl 5.8.3.
159
160     A C compiler. This module may happen to build with a C++ compiler as
161     well, but don't rely on it, as no guarantee is made in this regard.
162
163     XSLoader (standard since perl 5.6.0).
164
165 SEE ALSO
166     perlref.
167
168 AUTHOR
169     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
170
171     You can contact me by mail or on "irc.perl.org" (vincent).
172
173 BUGS
174     Please report any bugs or feature requests to "bug-autovivification at
175     rt.cpan.org", or through the web interface at
176     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=autovivification>. I
177     will be notified, and then you'll automatically be notified of progress
178     on your bug as I make changes.
179
180 SUPPORT
181     You can find documentation for this module with the perldoc command.
182
183         perldoc autovivification
184
185     Tests code coverage report is available at
186     <http://www.profvince.com/perl/cover/autovivification>.
187
188 ACKNOWLEDGEMENTS
189     Matt S. Trout asked for it.
190
191 COPYRIGHT & LICENSE
192     Copyright 2009,2010,2011,2012,2013,2014 Vincent Pit, all rights
193     reserved.
194
195     This program is free software; you can redistribute it and/or modify it
196     under the same terms as Perl itself.
197