1package autodie;
2use 5.008;
3use strict;
4use warnings;
5
6use Fatal ();
7our @ISA = qw(Fatal);
8our $VERSION;
9
10# ABSTRACT: Replace functions with ones that succeed or die with lexical scope
11
12BEGIN {
13    our $VERSION = '2.23'; # VERSION: Generated by DZP::OurPkg::Version
14}
15
16use constant ERROR_WRONG_FATAL => q{
17Incorrect version of Fatal.pm loaded by autodie.
18
19The autodie pragma uses an updated version of Fatal to do its
20heavy lifting.  We seem to have loaded Fatal version %s, which is
21probably the version that came with your version of Perl.  However
22autodie needs version %s, which would have come bundled with
23autodie.
24
25You may be able to solve this problem by adding the following
26line of code to your main program, before any use of Fatal or
27autodie.
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
37BEGIN {
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
58sub import {
59        splice(@_,1,0,Fatal::LEXICAL_TAG);
60        goto &Fatal::import;
61}
62
63sub unimport {
64        splice(@_,1,0,Fatal::LEXICAL_TAG);
65        goto &Fatal::unimport;
66}
67
681;
69
70__END__
71
72=head1 NAME
73
74autodie - 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
100The C<autodie> pragma provides a convenient way to replace functions
101that normally return false on failure with equivalents that throw
102an exception on failure.
103
104The C<autodie> pragma has I<lexical scope>, meaning that functions
105and subroutines altered with C<autodie> will only change their behaviour
106until the end of the enclosing block, file, or C<eval>.
107
108If C<system> is specified as an argument to C<autodie>, then it
109uses L<IPC::System::Simple> to do the heavy lifting.  See the
110description of that module for more information.
111
112=head1 EXCEPTIONS
113
114Exceptions produced by the C<autodie> pragma are members of the
115L<autodie::exception> class.  The preferred way to work with
116these 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
141Under Perl 5.8, the C<given/when> structure is not available, so the
142following 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
163See L<autodie::exception> for further information on interrogating
164exceptions.
165
166=head1 CATEGORIES
167
168Autodie uses a simple set of categories to group together similar
169built-ins.  Requesting a category type (starting with a colon) will
170enable autodie for all built-ins beneath that category.  For example,
171requesting C<:file> will enable autodie for C<close>, C<fcntl>,
172C<fileno>, C<open> and C<sysopen>.
173
174The 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
243Note that while the above category system is presently a strict
244hierarchy, this should not be assumed.
245
246A plain C<use autodie> implies C<use autodie qw(:default)>.  Note that
247C<system> and C<exec> are not enabled by default.  C<system> requires
248the optional L<IPC::System::Simple> module to be installed, and enabling
249C<system> or C<exec> will invalidate their exotic forms.  See L</BUGS>
250below for more details.
251
252The syntax:
253
254    use autodie qw(:1.994);
255
256allows the C<:default> list from a particular version to be used.  This
257provides the convenience of using the default methods, but the surety
258that no behavioral changes will occur if the C<autodie> module is
259upgraded.
260
261C<autodie> can be enabled for all of Perl's built-ins, including
262C<system> and C<exec> with:
263
264    use autodie qw(:all);
265
266=head1 FUNCTION SPECIFIC NOTES
267
268=head2 print
269
270The autodie pragma B<<does not check calls to C<print>>>.
271
272=head2 flock
273
274It is not considered an error for C<flock> to return false if it fails
275due to an C<EWOULDBLOCK> (or equivalent) condition.  This means one can
276still use the common convention of testing the return value of
277C<flock> when called with the C<LOCK_NB> option:
278
279    use autodie;
280
281    if ( flock($fh, LOCK_EX | LOCK_NB) ) {
282        # We have a lock
283    }
284
285Autodying C<flock> will generate an exception if C<flock> returns
286false with any other error.
287
288=head2 system/exec
289
290The C<system> built-in is considered to have failed in the following
291circumstances:
292
293=over 4
294
295=item *
296
297The command does not start.
298
299=item *
300
301The command is killed by a signal.
302
303=item *
304
305The command returns a non-zero exit value (but see below).
306
307=back
308
309On success, the autodying form of C<system> returns the I<exit value>
310rather than the contents of C<$?>.
311
312Additional allowable exit values can be supplied as an optional first
313argument to autodying C<system>:
314
315    system( [ 0, 1, 2 ], $cmd, @args);  # 0,1,2 are good exit values
316
317C<autodie> uses the L<IPC::System::Simple> module to change C<system>.
318See its documentation for further information.
319
320Applying C<autodie> to C<system> or C<exec> causes the exotic
321forms C<system { $cmd } @args > or C<exec { $cmd } @args>
322to be considered a syntax error until the end of the lexical scope.
323If you really need to use the exotic form, you can call C<CORE::system>
324or C<CORE::exec> instead, or use C<no autodie qw(system exec)> before
325calling the exotic form.
326
327=head1 GOTCHAS
328
329Functions called in list context are assumed to have failed if they
330return an empty list, or a list consisting only of a single undef
331element.
332
333=head1 DIAGNOSTICS
334
335=over 4
336
337=item :void cannot be used with lexical scope
338
339The C<:void> option is supported in L<Fatal>, but not
340C<autodie>.  To workaround this, C<autodie> may be explicitly disabled until
341the end of the current block with C<no autodie>.
342To disable autodie for only a single function (eg, open)
343use C<no autodie qw(open)>.
344
345C<autodie> performs no checking of called context to determine whether to throw
346an exception; the explicitness of error handling with C<autodie> is a deliberate
347feature.
348
349=item No user hints defined for %s
350
351You've insisted on hints for user-subroutines, either by pre-pending
352a C<!> to the subroutine name itself, or earlier in the list of arguments
353to C<autodie>.  However the subroutine in question does not have
354any hints available.
355
356=back
357
358See also L<Fatal/DIAGNOSTICS>.
359
360=head1 BUGS
361
362"Used only once" warnings can be generated when C<autodie> or C<Fatal>
363is used with package filehandles (eg, C<FILE>).  Scalar filehandles are
364strongly recommended instead.
365
366When using C<autodie> or C<Fatal> with user subroutines, the
367declaration of those subroutines must appear before the first use of
368C<Fatal> or C<autodie>, or have been exported from a module.
369Attempting to use C<Fatal> or C<autodie> on other user subroutines will
370result in a compile-time error.
371
372Due to a bug in Perl, C<autodie> may "lose" any format which has the
373same name as an autodying built-in or function.
374
375C<autodie> may not work correctly if used inside a file with a
376name that looks like a string eval, such as F<eval (3)>.
377
378=head2 autodie and string eval
379
380Due to the current implementation of C<autodie>, unexpected results
381may be seen when used near or with the string version of eval.
382I<None of these bugs exist when using block eval>.
383
384Under Perl 5.8 only, C<autodie> I<does not> propagate into string C<eval>
385statements, although it can be explicitly enabled inside a string
386C<eval>.
387
388Under Perl 5.10 only, using a string eval when C<autodie> is in
389effect can cause the autodie behaviour to leak into the surrounding
390scope.  This can be worked around by using a C<no autodie> at the
391end of the scope to explicitly remove autodie's effects, or by
392avoiding the use of string eval.
393
394I<None of these bugs exist when using block eval>.  The use of
395C<autodie> with block eval is considered good practice.
396
397=head2 REPORTING BUGS
398
399Please report bugs via the CPAN Request Tracker at
400L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>.
401
402=head1 FEEDBACK
403
404If you find this module useful, please consider rating it on the
405CPAN Ratings service at
406L<http://cpanratings.perl.org/rate?distribution=autodie> .
407
408The module author loves to hear how C<autodie> has made your life
409better (or worse).  Feedback can be sent to
410E<lt>pjf@perltraining.com.auE<gt>.
411
412=head1 AUTHOR
413
414Copyright 2008-2009, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt>
415
416=head1 LICENSE
417
418This module is free software.  You may distribute it under the
419same terms as Perl itself.
420
421=head1 SEE ALSO
422
423L<Fatal>, L<autodie::exception>, L<autodie::hints>, L<IPC::System::Simple>
424
425I<Perl tips, autodie> at
426L<http://perltraining.com.au/tips/2008-08-20.html>
427
428=head1 ACKNOWLEDGEMENTS
429
430Mark Reed and Roland Giersig -- Klingon translators.
431
432See the F<AUTHORS> file for full credits.  The latest version of this
433file can be found at
434L<https://github.com/pjf/autodie/tree/master/AUTHORS> .
435
436=cut
437