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