14 use constant ERROR_WRONG_FATAL => q{
15 Incorrect version of Fatal.pm loaded by autodie.
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
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
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
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. ;)
40 if ($Fatal::VERSION ne $VERSION) {
41 my $autodie_path = $INC{'autodie.pm'};
43 $autodie_path =~ s/autodie\.pm//;
48 ERROR_WRONG_FATAL, $Fatal::VERSION, $VERSION, $autodie_path
53 # When passing args to Fatal we want to keep the first arg
54 # (our package) in place. Hence the splice.
57 splice(@_,1,0,Fatal::LEXICAL_TAG);
62 splice(@_,1,0,Fatal::LEXICAL_TAG);
63 goto &Fatal::unimport;
72 autodie - Replace functions with ones that succeed or die with lexical scope
76 use autodie; # Recommended, implies 'use autodie qw(:default)'
78 use autodie qw(open close); # open/close succeed or die
80 open(my $fh, "<", $filename); # No need to check!
83 no autodie qw(open); # open failures won't die
84 open(my $fh, "<", $filename); # Could fail silently!
85 no autodie; # disable all autodies
90 bIlujDI' yIchegh()Qo'; yIHegh()!
92 It is better to die() than to return() in failure.
94 -- Klingon programming proverb.
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.
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>.
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.
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:
114 use feature qw(switch);
119 open(my $fh, '<', $some_file);
123 # Do things with @records...
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." }
137 Under Perl 5.8, the C<given/when> structure is not available, so the
138 following structure may be used:
143 open(my $fh, '<', $some_file);
147 # Do things with @records...
152 if ($@ and $@->isa('autodie::exception')) {
153 if ($@->matches('open')) { print "Error from open\n"; }
154 if ($@->matches(':io' )) { print "Non-open, IO error."; }
156 # A non-autodie exception.
159 See L<autodie::exception> for further information on interrogating
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>.
170 The categories are currently:
237 Note that while the above category system is presently a strict
238 hierarchy, this should not be assumed.
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.
248 use autodie qw(:1.994);
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
255 =head1 FUNCTION SPECIFIC NOTES
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:
266 if ( flock($fh, LOCK_EX | LOCK_NB) ) {
270 Autodying C<flock> will generate an exception if C<flock> returns
271 false with any other error.
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.
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
292 =item :void cannot be used with lexical scope
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)>.
302 See also L<Fatal/DIAGNOSTICS>.
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.
310 Under Perl 5.8 only, C<autodie> I<does not> propagate into string C<eval>
311 statements, although it can be explicitly enabled inside a string
312 C<eval>. This bug does not affect block C<eval> statements in
315 When using C<autodie> or C<Fatal> with user subroutines, the
316 declaration of those subroutines must appear before the first use of
317 C<Fatal> or C<autodie>, or have been exported from a module.
318 Attempting to ue C<Fatal> or C<autodie> on other user subroutines will
319 result in a compile-time error.
321 =head2 REPORTING BUGS
323 Please report bugs via the CPAN Request Tracker at
324 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>.
328 If you find this module useful, please consider rating it on the
329 CPAN Ratings service at
330 L<http://cpanratings.perl.org/rate?distribution=autodie> .
332 The module author loves to hear how C<autodie> has made your life
333 better (or worse). Feedback can be sent to
334 E<lt>pjf@perltraining.com.auE<gt>.
338 Copyright 2008, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt>
342 This module is free software. You may distribute it under the
343 same terms as Perl itself.
347 L<Fatal>, L<autodie::exception>, L<IPC::System::Simple>
349 I<Perl tips, autodie> at
350 L<http://perltraining.com.au/tips/2008-08-20.html>
352 =head1 ACKNOWLEDGEMENTS
354 Mark Reed and Roland Giersig -- Klingon translators.
356 See the F<AUTHORS> file for full credits. The latest version of this
358 L<http://github.com/pfenwick/autodie/tree/AUTHORS> .