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.29'; # 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    use feature qw(switch);
120
121    eval {
122        use autodie;
123
124        open(my $fh, '<', $some_file);
125
126        my @records = <$fh>;
127
128        # Do things with @records...
129
130        close($fh);
131
132    };
133
134    given ($@) {
135        when (undef)   { say "No error";                    }
136        when ('open')  { say "Error from open";             }
137        when (':io')   { say "Non-open, IO error.";         }
138        when (':all')  { say "All other autodie errors."    }
139        default        { say "Not an autodie error at all." }
140    }
141
142Under Perl 5.8, the C<given/when> structure is not available, so the
143following structure may be used:
144
145    eval {
146        use autodie;
147
148        open(my $fh, '<', $some_file);
149
150        my @records = <$fh>;
151
152        # Do things with @records...
153
154        close($fh);
155    };
156
157    if ($@ and $@->isa('autodie::exception')) {
158        if ($@->matches('open')) { print "Error from open\n";   }
159        if ($@->matches(':io' )) { print "Non-open, IO error."; }
160    } elsif ($@) {
161        # A non-autodie exception.
162    }
163
164See L<autodie::exception> for further information on interrogating
165exceptions.
166
167=head1 CATEGORIES
168
169Autodie uses a simple set of categories to group together similar
170built-ins.  Requesting a category type (starting with a colon) will
171enable autodie for all built-ins beneath that category.  For example,
172requesting C<:file> will enable autodie for C<close>, C<fcntl>,
173C<open> and C<sysopen>.
174
175The categories are currently:
176
177    :all
178        :default
179            :io
180                read
181                seek
182                sysread
183                sysseek
184                syswrite
185                :dbm
186                    dbmclose
187                    dbmopen
188                :file
189                    binmode
190                    close
191                    chmod
192                    chown
193                    fcntl
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                    kill
212                    pipe
213                    :msg
214                        msgctl
215                        msgget
216                        msgrcv
217                        msgsnd
218                    :semaphore
219                        semctl
220                        semget
221                        semop
222                    :shm
223                        shmctl
224                        shmget
225                        shmread
226                :socket
227                    accept
228                    bind
229                    connect
230                    getsockopt
231                    listen
232                    recv
233                    send
234                    setsockopt
235                    shutdown
236                    socketpair
237            :threads
238                fork
239        :system
240            system
241            exec
242
243
244Note that while the above category system is presently a strict
245hierarchy, this should not be assumed.
246
247A plain C<use autodie> implies C<use autodie qw(:default)>.  Note that
248C<system> and C<exec> are not enabled by default.  C<system> requires
249the optional L<IPC::System::Simple> module to be installed, and enabling
250C<system> or C<exec> will invalidate their exotic forms.  See L</BUGS>
251below for more details.
252
253The syntax:
254
255    use autodie qw(:1.994);
256
257allows the C<:default> list from a particular version to be used.  This
258provides the convenience of using the default methods, but the surety
259that no behavioral changes will occur if the C<autodie> module is
260upgraded.
261
262C<autodie> can be enabled for all of Perl's built-ins, including
263C<system> and C<exec> with:
264
265    use autodie qw(:all);
266
267=head1 FUNCTION SPECIFIC NOTES
268
269=head2 print
270
271The autodie pragma B<<does not check calls to C<print>>>.
272
273=head2 flock
274
275It is not considered an error for C<flock> to return false if it fails
276due to an C<EWOULDBLOCK> (or equivalent) condition.  This means one can
277still use the common convention of testing the return value of
278C<flock> when called with the C<LOCK_NB> option:
279
280    use autodie;
281
282    if ( flock($fh, LOCK_EX | LOCK_NB) ) {
283        # We have a lock
284    }
285
286Autodying C<flock> will generate an exception if C<flock> returns
287false with any other error.
288
289=head2 system/exec
290
291The C<system> built-in is considered to have failed in the following
292circumstances:
293
294=over 4
295
296=item *
297
298The command does not start.
299
300=item *
301
302The command is killed by a signal.
303
304=item *
305
306The command returns a non-zero exit value (but see below).
307
308=back
309
310On success, the autodying form of C<system> returns the I<exit value>
311rather than the contents of C<$?>.
312
313Additional allowable exit values can be supplied as an optional first
314argument to autodying C<system>:
315
316    system( [ 0, 1, 2 ], $cmd, @args);  # 0,1,2 are good exit values
317
318C<autodie> uses the L<IPC::System::Simple> module to change C<system>.
319See its documentation for further information.
320
321Applying C<autodie> to C<system> or C<exec> causes the exotic
322forms C<system { $cmd } @args > or C<exec { $cmd } @args>
323to be considered a syntax error until the end of the lexical scope.
324If you really need to use the exotic form, you can call C<CORE::system>
325or C<CORE::exec> instead, or use C<no autodie qw(system exec)> before
326calling the exotic form.
327
328=head1 GOTCHAS
329
330Functions called in list context are assumed to have failed if they
331return an empty list, or a list consisting only of a single undef
332element.
333
334Some builtins (e.g. C<chdir> or C<truncate>) has a call signature that
335cannot completely be representated with a Perl prototype.  This means
336that some valid Perl code will be invalid under autodie.  As an example:
337
338  chdir(BAREWORD);
339
340Without autodie (and assuming BAREWORD is an open
341filehandle/dirhandle) this is a valid call to chdir.  But under
342autodie, C<chdir> will behave like it had the prototype ";$" and thus
343BAREWORD will be a syntax error (under "use strict".  Without strict, it
344will interpreted as a filename).
345
346=head1 DIAGNOSTICS
347
348=over 4
349
350=item :void cannot be used with lexical scope
351
352The C<:void> option is supported in L<Fatal>, but not
353C<autodie>.  To workaround this, C<autodie> may be explicitly disabled until
354the end of the current block with C<no autodie>.
355To disable autodie for only a single function (eg, open)
356use C<no autodie qw(open)>.
357
358C<autodie> performs no checking of called context to determine whether to throw
359an exception; the explicitness of error handling with C<autodie> is a deliberate
360feature.
361
362=item No user hints defined for %s
363
364You've insisted on hints for user-subroutines, either by pre-pending
365a C<!> to the subroutine name itself, or earlier in the list of arguments
366to C<autodie>.  However the subroutine in question does not have
367any hints available.
368
369=back
370
371See also L<Fatal/DIAGNOSTICS>.
372
373=head1 BUGS
374
375"Used only once" warnings can be generated when C<autodie> or C<Fatal>
376is used with package filehandles (eg, C<FILE>).  Scalar filehandles are
377strongly recommended instead.
378
379When using C<autodie> or C<Fatal> with user subroutines, the
380declaration of those subroutines must appear before the first use of
381C<Fatal> or C<autodie>, or have been exported from a module.
382Attempting to use C<Fatal> or C<autodie> on other user subroutines will
383result in a compile-time error.
384
385Due to a bug in Perl, C<autodie> may "lose" any format which has the
386same name as an autodying built-in or function.
387
388C<autodie> may not work correctly if used inside a file with a
389name that looks like a string eval, such as F<eval (3)>.
390
391=head2 autodie and string eval
392
393Due to the current implementation of C<autodie>, unexpected results
394may be seen when used near or with the string version of eval.
395I<None of these bugs exist when using block eval>.
396
397Under Perl 5.8 only, C<autodie> I<does not> propagate into string C<eval>
398statements, although it can be explicitly enabled inside a string
399C<eval>.
400
401Under Perl 5.10 only, using a string eval when C<autodie> is in
402effect can cause the autodie behaviour to leak into the surrounding
403scope.  This can be worked around by using a C<no autodie> at the
404end of the scope to explicitly remove autodie's effects, or by
405avoiding the use of string eval.
406
407I<None of these bugs exist when using block eval>.  The use of
408C<autodie> with block eval is considered good practice.
409
410=head2 REPORTING BUGS
411
412Please report bugs via the GitHub Issue Tracker at
413L<https://github.com/pjf/autodie/issues> or via the CPAN Request
414Tracker at L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>.
415
416=head1 FEEDBACK
417
418If you find this module useful, please consider rating it on the
419CPAN Ratings service at
420L<http://cpanratings.perl.org/rate?distribution=autodie> .
421
422The module author loves to hear how C<autodie> has made your life
423better (or worse).  Feedback can be sent to
424E<lt>pjf@perltraining.com.auE<gt>.
425
426=head1 AUTHOR
427
428Copyright 2008-2009, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt>
429
430=head1 LICENSE
431
432This module is free software.  You may distribute it under the
433same terms as Perl itself.
434
435=head1 SEE ALSO
436
437L<Fatal>, L<autodie::exception>, L<autodie::hints>, L<IPC::System::Simple>
438
439I<Perl tips, autodie> at
440L<http://perltraining.com.au/tips/2008-08-20.html>
441
442=head1 ACKNOWLEDGEMENTS
443
444Mark Reed and Roland Giersig -- Klingon translators.
445
446See the F<AUTHORS> file for full credits.  The latest version of this
447file can be found at
448L<https://github.com/pjf/autodie/tree/master/AUTHORS> .
449
450=cut
451