Commit | Line | Data |
---|---|---|
0b09a93a PF |
1 | package autodie; |
2 | use 5.008; | |
3 | use strict; | |
4 | use warnings; | |
5 | ||
6 | use Fatal (); | |
7 | our @ISA = qw(Fatal); | |
8 | our $VERSION; | |
9 | ||
10 | BEGIN { | |
11 | $VERSION = "1.997"; | |
12 | } | |
13 | ||
14 | use constant ERROR_WRONG_FATAL => q{ | |
15 | Incorrect version of Fatal.pm loaded by autodie. | |
16 | ||
17 | The autodie pragma uses an updated version of Fatal to do its | |
18 | heavy lifting. We seem to have loaded Fatal version %s, which is | |
19 | probably the version that came with your version of Perl. However | |
20 | autodie needs version %s, which would have come bundled with | |
21 | autodie. | |
22 | ||
23 | You may be able to solve this problem by adding the following | |
24 | line of code to your main program, before any use of Fatal or | |
25 | autodie. | |
26 | ||
27 | use lib "%s"; | |
28 | ||
29 | }; | |
30 | ||
31 | # We have to check we've got the right version of Fatal before we | |
32 | # try to compile the rest of our code, lest we use a constant | |
33 | # that doesn't exist. | |
34 | ||
35 | BEGIN { | |
36 | ||
37 | # If we have the wrong Fatal, then we've probably loaded the system | |
38 | # one, not our own. Complain, and give a useful hint. ;) | |
39 | ||
40 | if ($Fatal::VERSION ne $VERSION) { | |
41 | my $autodie_path = $INC{'autodie.pm'}; | |
42 | ||
43 | $autodie_path =~ s/autodie\.pm//; | |
44 | ||
45 | require Carp; | |
46 | ||
47 | Carp::croak sprintf( | |
48 | ERROR_WRONG_FATAL, $Fatal::VERSION, $VERSION, $autodie_path | |
49 | ); | |
50 | } | |
51 | } | |
52 | ||
53 | # When passing args to Fatal we want to keep the first arg | |
54 | # (our package) in place. Hence the splice. | |
55 | ||
56 | sub import { | |
57 | splice(@_,1,0,Fatal::LEXICAL_TAG); | |
58 | goto &Fatal::import; | |
59 | } | |
60 | ||
61 | sub unimport { | |
62 | splice(@_,1,0,Fatal::LEXICAL_TAG); | |
63 | goto &Fatal::unimport; | |
64 | } | |
65 | ||
66 | 1; | |
67 | ||
68 | __END__ | |
69 | ||
70 | =head1 NAME | |
71 | ||
72 | autodie - Replace functions with ones that succeed or die with lexical scope | |
73 | ||
74 | =head1 SYNOPSIS | |
75 | ||
76 | use autodie; # Recommended, implies 'use autodie qw(:default)' | |
77 | ||
78 | use autodie qw(open close); # open/close succeed or die | |
79 | ||
80 | open(my $fh, "<", $filename); # No need to check! | |
81 | ||
82 | { | |
83 | no autodie qw(open); # open failures won't die | |
84 | open(my $fh, "<", $filename); # Could fail silently! | |
85 | no autodie; # disable all autodies | |
86 | } | |
87 | ||
88 | =head1 DESCRIPTION | |
89 | ||
90 | bIlujDI' yIchegh()Qo'; yIHegh()! | |
91 | ||
92 | It is better to die() than to return() in failure. | |
93 | ||
94 | -- Klingon programming proverb. | |
95 | ||
96 | The C<autodie> pragma provides a convenient way to replace functions | |
97 | that normally return false on failure with equivalents that throw | |
98 | an exception on failure. | |
99 | ||
100 | The C<autodie> pragma has I<lexical scope>, meaning that functions | |
101 | and subroutines altered with C<autodie> will only change their behaviour | |
102 | until the end of the enclosing block, file, or C<eval>. | |
103 | ||
104 | If C<system> is specified as an argument to C<autodie>, then it | |
105 | uses L<IPC::System::Simple> to do the heavy lifting. See the | |
106 | description of that module for more information. | |
107 | ||
108 | =head1 EXCEPTIONS | |
109 | ||
110 | Exceptions produced by the C<autodie> pragma are members of the | |
111 | L<autodie::exception> class. The preferred way to work with | |
112 | these exceptions under Perl 5.10 is as follows: | |
113 | ||
114 | use feature qw(switch); | |
115 | ||
116 | eval { | |
117 | use autodie; | |
118 | ||
119 | open(my $fh, '<', $some_file); | |
120 | ||
121 | my @records = <$fh>; | |
122 | ||
123 | # Do things with @records... | |
124 | ||
125 | close($fh); | |
126 | ||
127 | }; | |
128 | ||
129 | given ($@) { | |
130 | when (undef) { say "No error"; } | |
131 | when ('open') { say "Error from open"; } | |
132 | when (':io') { say "Non-open, IO error."; } | |
133 | when (':all') { say "All other autodie errors." } | |
134 | default { say "Not an autodie error at all." } | |
135 | } | |
136 | ||
137 | Under Perl 5.8, the C<given/when> structure is not available, so the | |
138 | following structure may be used: | |
139 | ||
140 | eval { | |
141 | use autodie; | |
142 | ||
143 | open(my $fh, '<', $some_file); | |
144 | ||
145 | my @records = <$fh>; | |
146 | ||
147 | # Do things with @records... | |
148 | ||
149 | close($fh); | |
150 | }; | |
151 | ||
152 | if ($@ and $@->isa('autodie::exception')) { | |
153 | if ($@->matches('open')) { print "Error from open\n"; } | |
154 | if ($@->matches(':io' )) { print "Non-open, IO error."; } | |
155 | } elsif ($@) { | |
156 | # A non-autodie exception. | |
157 | } | |
158 | ||
159 | See L<autodie::exception> for further information on interrogating | |
160 | exceptions. | |
161 | ||
162 | =head1 CATEGORIES | |
163 | ||
164 | Autodie uses a simple set of categories to group together similar | |
165 | built-ins. Requesting a category type (starting with a colon) will | |
166 | enable autodie for all built-ins beneath that category. For example, | |
167 | requesting C<:file> will enable autodie for C<close>, C<fcntl>, | |
168 | C<fileno>, C<open> and C<sysopen>. | |
169 | ||
170 | The categories are currently: | |
171 | ||
172 | :all | |
173 | :default | |
174 | :io | |
175 | read | |
176 | seek | |
177 | sysread | |
178 | sysseek | |
179 | syswrite | |
180 | :dbm | |
181 | dbmclose | |
182 | dbmopen | |
183 | :file | |
184 | binmode | |
185 | close | |
186 | fcntl | |
187 | fileno | |
188 | flock | |
189 | ioctl | |
190 | open | |
191 | sysopen | |
192 | truncate | |
193 | :filesys | |
194 | chdir | |
195 | closedir | |
196 | opendir | |
197 | link | |
198 | mkdir | |
199 | readlink | |
200 | rename | |
201 | rmdir | |
202 | symlink | |
203 | unlink | |
204 | :ipc | |
205 | pipe | |
206 | :msg | |
207 | msgctl | |
208 | msgget | |
209 | msgrcv | |
210 | msgsnd | |
211 | :semaphore | |
212 | semctl | |
213 | semget | |
214 | semop | |
215 | :shm | |
216 | shmctl | |
217 | shmget | |
218 | shmread | |
219 | :socket | |
220 | accept | |
221 | bind | |
222 | connect | |
223 | getsockopt | |
224 | listen | |
225 | recv | |
226 | send | |
227 | setsockopt | |
228 | shutdown | |
229 | socketpair | |
230 | :threads | |
231 | fork | |
232 | :system | |
233 | system | |
234 | exec | |
235 | ||
236 | ||
237 | Note that while the above category system is presently a strict | |
238 | hierarchy, this should not be assumed. | |
239 | ||
240 | A plain C<use autodie> implies C<use autodie qw(:default)>. Note that | |
241 | C<system> and C<exec> are not enabled by default. C<system> requires | |
242 | the optional L<IPC::System::Simple> module to be installed, and enabling | |
243 | C<system> or C<exec> will invalidate their exotic forms. See L</BUGS> | |
244 | below for more details. | |
245 | ||
246 | The syntax: | |
247 | ||
248 | use autodie qw(:1.994); | |
249 | ||
250 | allows the C<:default> list from a particular version to be used. This | |
251 | provides the convenience of using the default methods, but the surity | |
252 | that no behavorial changes will occur if the C<autodie> module is | |
253 | upgraded. | |
254 | ||
255 | =head1 FUNCTION SPECIFIC NOTES | |
256 | ||
257 | =head2 flock | |
258 | ||
259 | It is not considered an error for C<flock> to return false if it fails | |
260 | to an C<EWOULDBLOCK> (or equivalent) condition. This means one can | |
261 | still use the common convention of testing the return value of | |
262 | C<flock> when called with the C<LOCK_NB> option: | |
263 | ||
264 | use autodie; | |
265 | ||
266 | if ( flock($fh, LOCK_EX | LOCK_NB) ) { | |
267 | # We have a lock | |
268 | } | |
269 | ||
270 | Autodying C<flock> will generate an exception if C<flock> returns | |
271 | false with any other error. | |
272 | ||
273 | =head2 system/exec | |
274 | ||
275 | Applying C<autodie> to C<system> or C<exec> causes the exotic | |
276 | forms C<system { $cmd } @args > or C<exec { $cmd } @args> | |
277 | to be considered a syntax error until the end of the lexical scope. | |
278 | If you really need to use the exotic form, you can call C<CORE::system> | |
279 | or C<CORE::exec> instead, or use C<no autodie qw(system exec)> before | |
280 | calling the exotic form. | |
281 | ||
282 | =head1 GOTCHAS | |
283 | ||
284 | Functions called in list context are assumed to have failed if they | |
285 | return an empty list, or a list consisting only of a single undef | |
286 | element. | |
287 | ||
288 | =head1 DIAGNOSTICS | |
289 | ||
290 | =over 4 | |
291 | ||
292 | =item :void cannot be used with lexical scope | |
293 | ||
294 | The C<:void> option is supported in L<Fatal>, but not | |
295 | C<autodie>. However you can explicitly disable autodie | |
296 | end the end of the current block with C<no autodie>. | |
297 | To disable autodie for only a single function (eg, open) | |
298 | use or C<no autodie qw(open)>. | |
299 | ||
300 | =back | |
301 | ||
302 | See also L<Fatal/DIAGNOSTICS>. | |
303 | ||
304 | =head1 BUGS | |
305 | ||
306 | "Used only once" warnings can be generated when C<autodie> or C<Fatal> | |
307 | is used with package filehandles (eg, C<FILE>). It's strongly recommended | |
308 | you use scalar filehandles instead. | |
309 | ||
310 | When using C<autodie> or C<Fatal> with user subroutines, the | |
311 | declaration of those subroutines must appear before the first use of | |
312 | C<Fatal> or C<autodie>, or have been exported from a module. | |
313 | Attempting to ue C<Fatal> or C<autodie> on other user subroutines will | |
314 | result in a compile-time error. | |
315 | ||
316 | =head2 REPORTING BUGS | |
317 | ||
318 | Please report bugs via the CPAN Request Tracker at | |
319 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>. | |
320 | ||
321 | =head1 FEEDBACK | |
322 | ||
323 | If you find this module useful, please consider rating it on the | |
324 | CPAN Ratings service at | |
325 | L<http://cpanratings.perl.org/rate?distribution=autodie> . | |
326 | ||
327 | The module author loves to hear how C<autodie> has made your life | |
328 | better (or worse). Feedback can be sent to | |
329 | E<lt>pjf@perltraining.com.auE<gt>. | |
330 | ||
331 | =head1 AUTHOR | |
332 | ||
333 | Copyright 2008, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt> | |
334 | ||
335 | =head1 LICENSE | |
336 | ||
337 | This module is free software. You may distribute it under the | |
338 | same terms as Perl itself. | |
339 | ||
340 | =head1 SEE ALSO | |
341 | ||
342 | L<Fatal>, L<autodie::exception>, L<IPC::System::Simple> | |
343 | ||
344 | I<Perl tips, autodie> at | |
345 | L<http://perltraining.com.au/tips/2008-08-20.html> | |
346 | ||
347 | =head1 ACKNOWLEDGEMENTS | |
348 | ||
349 | Mark Reed and Roland Giersig -- Klingon translators. | |
350 | ||
351 | See the F<AUTHORS> file for full credits. The latest version of this | |
352 | file can be found at | |
353 | L<http://github.com/pfenwick/autodie/tree/AUTHORS> . | |
354 | ||
355 | =cut |