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