Commit | Line | Data |
0b09a93a |
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 { |
9b657a62 |
11 | $VERSION = '2.00'; |
0b09a93a |
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 | |
9b657a62 |
76 | use autodie; # Recommended: implies 'use autodie qw(:default)' |
77 | |
78 | use autodie qw(:all); # Recommended more: defaults and system/exec. |
0b09a93a |
79 | |
80 | use autodie qw(open close); # open/close succeed or die |
81 | |
82 | open(my $fh, "<", $filename); # No need to check! |
83 | |
84 | { |
85 | no autodie qw(open); # open failures won't die |
86 | open(my $fh, "<", $filename); # Could fail silently! |
87 | no autodie; # disable all autodies |
88 | } |
89 | |
90 | =head1 DESCRIPTION |
91 | |
92 | bIlujDI' yIchegh()Qo'; yIHegh()! |
93 | |
94 | It is better to die() than to return() in failure. |
95 | |
96 | -- Klingon programming proverb. |
97 | |
98 | The C<autodie> pragma provides a convenient way to replace functions |
99 | that normally return false on failure with equivalents that throw |
100 | an exception on failure. |
101 | |
102 | The C<autodie> pragma has I<lexical scope>, meaning that functions |
103 | and subroutines altered with C<autodie> will only change their behaviour |
104 | until the end of the enclosing block, file, or C<eval>. |
105 | |
106 | If C<system> is specified as an argument to C<autodie>, then it |
107 | uses L<IPC::System::Simple> to do the heavy lifting. See the |
108 | description of that module for more information. |
109 | |
110 | =head1 EXCEPTIONS |
111 | |
112 | Exceptions produced by the C<autodie> pragma are members of the |
113 | L<autodie::exception> class. The preferred way to work with |
114 | these exceptions under Perl 5.10 is as follows: |
115 | |
116 | use feature qw(switch); |
117 | |
118 | eval { |
119 | use autodie; |
120 | |
121 | open(my $fh, '<', $some_file); |
122 | |
123 | my @records = <$fh>; |
124 | |
125 | # Do things with @records... |
126 | |
127 | close($fh); |
128 | |
129 | }; |
130 | |
131 | given ($@) { |
132 | when (undef) { say "No error"; } |
133 | when ('open') { say "Error from open"; } |
134 | when (':io') { say "Non-open, IO error."; } |
135 | when (':all') { say "All other autodie errors." } |
136 | default { say "Not an autodie error at all." } |
137 | } |
138 | |
139 | Under Perl 5.8, the C<given/when> structure is not available, so the |
140 | following structure may be used: |
141 | |
142 | eval { |
143 | use autodie; |
144 | |
145 | open(my $fh, '<', $some_file); |
146 | |
147 | my @records = <$fh>; |
148 | |
149 | # Do things with @records... |
150 | |
151 | close($fh); |
152 | }; |
153 | |
154 | if ($@ and $@->isa('autodie::exception')) { |
155 | if ($@->matches('open')) { print "Error from open\n"; } |
156 | if ($@->matches(':io' )) { print "Non-open, IO error."; } |
157 | } elsif ($@) { |
158 | # A non-autodie exception. |
159 | } |
160 | |
161 | See L<autodie::exception> for further information on interrogating |
162 | exceptions. |
163 | |
164 | =head1 CATEGORIES |
165 | |
166 | Autodie uses a simple set of categories to group together similar |
167 | built-ins. Requesting a category type (starting with a colon) will |
168 | enable autodie for all built-ins beneath that category. For example, |
169 | requesting C<:file> will enable autodie for C<close>, C<fcntl>, |
170 | C<fileno>, C<open> and C<sysopen>. |
171 | |
172 | The categories are currently: |
173 | |
174 | :all |
175 | :default |
176 | :io |
177 | read |
178 | seek |
179 | sysread |
180 | sysseek |
181 | syswrite |
182 | :dbm |
183 | dbmclose |
184 | dbmopen |
185 | :file |
186 | binmode |
187 | close |
188 | fcntl |
189 | fileno |
190 | flock |
191 | ioctl |
192 | open |
193 | sysopen |
194 | truncate |
195 | :filesys |
196 | chdir |
197 | closedir |
198 | opendir |
199 | link |
200 | mkdir |
201 | readlink |
202 | rename |
203 | rmdir |
204 | symlink |
205 | unlink |
206 | :ipc |
207 | pipe |
208 | :msg |
209 | msgctl |
210 | msgget |
211 | msgrcv |
212 | msgsnd |
213 | :semaphore |
214 | semctl |
215 | semget |
216 | semop |
217 | :shm |
218 | shmctl |
219 | shmget |
220 | shmread |
221 | :socket |
222 | accept |
223 | bind |
224 | connect |
225 | getsockopt |
226 | listen |
227 | recv |
228 | send |
229 | setsockopt |
230 | shutdown |
231 | socketpair |
232 | :threads |
233 | fork |
234 | :system |
235 | system |
236 | exec |
237 | |
238 | |
239 | Note that while the above category system is presently a strict |
240 | hierarchy, this should not be assumed. |
241 | |
242 | A plain C<use autodie> implies C<use autodie qw(:default)>. Note that |
243 | C<system> and C<exec> are not enabled by default. C<system> requires |
244 | the optional L<IPC::System::Simple> module to be installed, and enabling |
245 | C<system> or C<exec> will invalidate their exotic forms. See L</BUGS> |
246 | below for more details. |
247 | |
248 | The syntax: |
249 | |
250 | use autodie qw(:1.994); |
251 | |
252 | allows the C<:default> list from a particular version to be used. This |
9b657a62 |
253 | provides the convenience of using the default methods, but the surety |
0b09a93a |
254 | that no behavorial changes will occur if the C<autodie> module is |
255 | upgraded. |
256 | |
9b657a62 |
257 | You can enable C<autodie> for all of Perl's built-ins, including |
258 | C<system> and C<exec> with: |
259 | |
260 | use autodie qw(:all); |
261 | |
0b09a93a |
262 | =head1 FUNCTION SPECIFIC NOTES |
263 | |
264 | =head2 flock |
265 | |
266 | It is not considered an error for C<flock> to return false if it fails |
267 | to an C<EWOULDBLOCK> (or equivalent) condition. This means one can |
268 | still use the common convention of testing the return value of |
269 | C<flock> when called with the C<LOCK_NB> option: |
270 | |
271 | use autodie; |
272 | |
273 | if ( flock($fh, LOCK_EX | LOCK_NB) ) { |
274 | # We have a lock |
275 | } |
276 | |
277 | Autodying C<flock> will generate an exception if C<flock> returns |
278 | false with any other error. |
279 | |
280 | =head2 system/exec |
281 | |
9b657a62 |
282 | The C<system> built-in is considered to have failed in the following |
283 | circumstances: |
284 | |
285 | =over 4 |
286 | |
287 | =item * |
288 | |
289 | The command does not start. |
290 | |
291 | =item * |
292 | |
293 | The command is killed by a signal. |
294 | |
295 | =item * |
296 | |
297 | The command returns a non-zero exit value (but see below). |
298 | |
299 | =back |
300 | |
301 | On success, the autodying form of C<system> returns the I<exit value> |
302 | rather than the contents of C<$?>. |
303 | |
304 | Additional allowable exit values can be supplied as an optional first |
305 | argument to autodying C<system>: |
306 | |
307 | system( [ 0, 1, 2 ], $cmd, @args); # 0,1,2 are good exit values |
308 | |
309 | C<autodie> uses the L<IPC::System::Simple> module to change C<system>. |
310 | See its documentation for further information. |
311 | |
0b09a93a |
312 | Applying C<autodie> to C<system> or C<exec> causes the exotic |
313 | forms C<system { $cmd } @args > or C<exec { $cmd } @args> |
314 | to be considered a syntax error until the end of the lexical scope. |
315 | If you really need to use the exotic form, you can call C<CORE::system> |
316 | or C<CORE::exec> instead, or use C<no autodie qw(system exec)> before |
317 | calling the exotic form. |
318 | |
319 | =head1 GOTCHAS |
320 | |
321 | Functions called in list context are assumed to have failed if they |
322 | return an empty list, or a list consisting only of a single undef |
323 | element. |
324 | |
325 | =head1 DIAGNOSTICS |
326 | |
327 | =over 4 |
328 | |
329 | =item :void cannot be used with lexical scope |
330 | |
331 | The C<:void> option is supported in L<Fatal>, but not |
332 | C<autodie>. However you can explicitly disable autodie |
333 | end the end of the current block with C<no autodie>. |
334 | To disable autodie for only a single function (eg, open) |
9b657a62 |
335 | use C<no autodie qw(open)>. |
336 | |
337 | =item No user hints defined for %s |
338 | |
339 | You've insisted on hints for user-subroutines, either by pre-pending |
340 | a C<!> to the subroutine name itself, or earlier in the list of arguments |
341 | to C<autodie>. However the subroutine in question does not have |
342 | any hints available. |
0b09a93a |
343 | |
344 | =back |
345 | |
346 | See also L<Fatal/DIAGNOSTICS>. |
347 | |
348 | =head1 BUGS |
349 | |
350 | "Used only once" warnings can be generated when C<autodie> or C<Fatal> |
351 | is used with package filehandles (eg, C<FILE>). It's strongly recommended |
352 | you use scalar filehandles instead. |
353 | |
db4e6d09 |
354 | Under Perl 5.8 only, C<autodie> I<does not> propagate into string C<eval> |
355 | statements, although it can be explicitly enabled inside a string |
356 | C<eval>. This bug does not affect block C<eval> statements in |
357 | any version of Perl. |
358 | |
0b09a93a |
359 | When using C<autodie> or C<Fatal> with user subroutines, the |
360 | declaration of those subroutines must appear before the first use of |
361 | C<Fatal> or C<autodie>, or have been exported from a module. |
9b657a62 |
362 | Attempting to use C<Fatal> or C<autodie> on other user subroutines will |
0b09a93a |
363 | result in a compile-time error. |
364 | |
9b657a62 |
365 | Due to a bug in Perl, C<autodie> may "lose" any format which has the |
366 | same name as an autodying built-in or function. |
367 | |
0b09a93a |
368 | =head2 REPORTING BUGS |
369 | |
370 | Please report bugs via the CPAN Request Tracker at |
371 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>. |
372 | |
373 | =head1 FEEDBACK |
374 | |
375 | If you find this module useful, please consider rating it on the |
376 | CPAN Ratings service at |
377 | L<http://cpanratings.perl.org/rate?distribution=autodie> . |
378 | |
379 | The module author loves to hear how C<autodie> has made your life |
380 | better (or worse). Feedback can be sent to |
381 | E<lt>pjf@perltraining.com.auE<gt>. |
382 | |
383 | =head1 AUTHOR |
384 | |
9b657a62 |
385 | Copyright 2008-2009, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt> |
0b09a93a |
386 | |
387 | =head1 LICENSE |
388 | |
389 | This module is free software. You may distribute it under the |
390 | same terms as Perl itself. |
391 | |
392 | =head1 SEE ALSO |
393 | |
9b657a62 |
394 | L<Fatal>, L<autodie::exception>, L<autodie::hints>, L<IPC::System::Simple> |
0b09a93a |
395 | |
396 | I<Perl tips, autodie> at |
397 | L<http://perltraining.com.au/tips/2008-08-20.html> |
398 | |
399 | =head1 ACKNOWLEDGEMENTS |
400 | |
401 | Mark Reed and Roland Giersig -- Klingon translators. |
402 | |
403 | See the F<AUTHORS> file for full credits. The latest version of this |
404 | file can be found at |
9b657a62 |
405 | L<http://github.com/pfenwick/autodie/tree/master/AUTHORS> . |
0b09a93a |
406 | |
407 | =cut |