]> git.vpit.fr Git - perl/modules/autovivification.git/blob - README
Add a testdeb target to Makefiles
[perl/modules/autovivification.git] / README
1 NAME
2     autovivification - Lexically disable autovivification.
3
4 VERSION
5     Version 0.12
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     The pragma doesn't apply when one dereferences the returned value of an
142     array or hash slice, as in "@array[$id]->{member}" or
143     @hash{$key}->{member}. This syntax is valid Perl, yet it is discouraged
144     as the slice is here useless since the dereferencing enforces scalar
145     context. If warnings are turned on, Perl will complain about one-element
146     slices.
147
148 DEPENDENCIES
149     perl 5.8.3.
150
151     A C compiler. This module may happen to build with a C++ compiler as
152     well, but don't rely on it, as no guarantee is made in this regard.
153
154     XSLoader (standard since perl 5.6.0).
155
156 SEE ALSO
157     perlref.
158
159 AUTHOR
160     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
161
162     You can contact me by mail or on "irc.perl.org" (vincent).
163
164 BUGS
165     Please report any bugs or feature requests to "bug-autovivification at
166     rt.cpan.org", or through the web interface at
167     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=autovivification>. I
168     will be notified, and then you'll automatically be notified of progress
169     on your bug as I make changes.
170
171 SUPPORT
172     You can find documentation for this module with the perldoc command.
173
174         perldoc autovivification
175
176     Tests code coverage report is available at
177     <http://www.profvince.com/perl/cover/autovivification>.
178
179 ACKNOWLEDGEMENTS
180     Matt S. Trout asked for it.
181
182 COPYRIGHT & LICENSE
183     Copyright 2009,2010,2011,2012,2013 Vincent Pit, all rights reserved.
184
185     This program is free software; you can redistribute it and/or modify it
186     under the same terms as Perl itself.
187