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