Allow ~~ overloading on the left side, when the right side is a plain scalar
[perl.git] / lib / autodie.pm
1 package autodie;
2 use 5.008;
3 use strict;
4 use warnings;
5
6 use Fatal ();
7 our @ISA = qw(Fatal);
8 our $VERSION;
9
10 BEGIN {
11     $VERSION = "1.999";
12 }
13
14 use constant ERROR_WRONG_FATAL => q{
15 Incorrect version of Fatal.pm loaded by autodie.
16
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
21 autodie.
22
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
25 autodie.
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
35 BEGIN {
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
56 sub import {
57         splice(@_,1,0,Fatal::LEXICAL_TAG);
58         goto &Fatal::import;
59 }
60
61 sub unimport {
62         splice(@_,1,0,Fatal::LEXICAL_TAG);
63         goto &Fatal::unimport;
64 }
65
66 1;
67
68 __END__
69
70 =head1 NAME
71
72 autodie - Replace functions with ones that succeed or die with lexical scope
73
74 =head1 SYNOPSIS
75
76     use autodie;    # Recommended, implies 'use autodie qw(:default)'
77
78     use autodie qw(open close);   # open/close succeed or die
79
80     open(my $fh, "<", $filename); # No need to check!
81
82     {
83         no autodie qw(open);          # open failures won't die
84         open(my $fh, "<", $filename); # Could fail silently!
85         no autodie;                   # disable all autodies
86     }
87
88 =head1 DESCRIPTION
89
90         bIlujDI' yIchegh()Qo'; yIHegh()!
91
92         It is better to die() than to return() in failure.
93
94                 -- Klingon programming proverb.
95
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.
99
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>.
103
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.
107
108 =head1 EXCEPTIONS
109
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:
113
114     use feature qw(switch);
115
116     eval {
117         use autodie;
118
119         open(my $fh, '<', $some_file);
120
121         my @records = <$fh>;
122
123         # Do things with @records...
124
125         close($fh);
126
127     };
128
129     given ($@) {
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." }
135     }
136
137 Under Perl 5.8, the C<given/when> structure is not available, so the
138 following structure may be used:
139
140     eval {
141         use autodie;
142
143         open(my $fh, '<', $some_file);
144
145         my @records = <$fh>;
146
147         # Do things with @records...
148
149         close($fh);
150     };
151
152     if ($@ and $@->isa('autodie::exception')) {
153         if ($@->matches('open')) { print "Error from open\n";   }
154         if ($@->matches(':io' )) { print "Non-open, IO error."; }
155     } elsif ($@) {
156         # A non-autodie exception.
157     }
158
159 See L<autodie::exception> for further information on interrogating
160 exceptions.
161
162 =head1 CATEGORIES
163
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>.
169
170 The categories are currently:
171
172     :all
173         :default
174             :io
175                 read
176                 seek
177                 sysread
178                 sysseek
179                 syswrite
180                 :dbm
181                     dbmclose
182                     dbmopen
183                 :file
184                     binmode
185                     close
186                     fcntl
187                     fileno
188                     flock
189                     ioctl
190                     open
191                     sysopen
192                     truncate
193                 :filesys
194                     chdir
195                     closedir
196                     opendir
197                     link
198                     mkdir
199                     readlink
200                     rename
201                     rmdir
202                     symlink
203                     unlink
204                 :ipc
205                     pipe
206                     :msg
207                         msgctl
208                         msgget
209                         msgrcv
210                         msgsnd
211                     :semaphore
212                         semctl
213                         semget
214                         semop
215                     :shm
216                         shmctl
217                         shmget
218                         shmread
219                 :socket
220                     accept
221                     bind
222                     connect
223                     getsockopt
224                     listen
225                     recv
226                     send
227                     setsockopt
228                     shutdown
229                     socketpair
230             :threads
231                 fork
232         :system
233             system
234             exec
235
236
237 Note that while the above category system is presently a strict
238 hierarchy, this should not be assumed.
239
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.
245
246 The syntax:
247
248     use autodie qw(:1.994);
249
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
253 upgraded.
254
255 =head1 FUNCTION SPECIFIC NOTES
256
257 =head2 flock
258
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:
263
264     use autodie;
265
266     if ( flock($fh, LOCK_EX | LOCK_NB) ) {
267         # We have a lock
268     }
269
270 Autodying C<flock> will generate an exception if C<flock> returns
271 false with any other error.
272
273 =head2 system/exec
274
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.
281
282 =head1 GOTCHAS
283
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
286 element.
287
288 =head1 DIAGNOSTICS
289
290 =over 4
291
292 =item :void cannot be used with lexical scope
293
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)>.
299
300 =back
301
302 See also L<Fatal/DIAGNOSTICS>.
303
304 =head1 BUGS
305
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.
309
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
313 any version of Perl.
314
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.
320
321 =head2 REPORTING BUGS
322
323 Please report bugs via the CPAN Request Tracker at
324 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>.
325
326 =head1 FEEDBACK
327
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> .
331
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>.
335
336 =head1 AUTHOR
337
338 Copyright 2008, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt>
339
340 =head1 LICENSE
341
342 This module is free software.  You may distribute it under the
343 same terms as Perl itself.
344
345 =head1 SEE ALSO
346
347 L<Fatal>, L<autodie::exception>, L<IPC::System::Simple>
348
349 I<Perl tips, autodie> at
350 L<http://perltraining.com.au/tips/2008-08-20.html>
351
352 =head1 ACKNOWLEDGEMENTS
353
354 Mark Reed and Roland Giersig -- Klingon translators.
355
356 See the F<AUTHORS> file for full credits.  The latest version of this
357 file can be found at
358 L<http://github.com/pfenwick/autodie/tree/AUTHORS> .
359
360 =cut