Commit | Line | Data |
0b09a93a |
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 { |
3776a202 |
11 | $VERSION = "1.998"; |
0b09a93a |
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 | When using C<autodie> or C<Fatal> with user subroutines, the |
311 | declaration of those subroutines must appear before the first use of |
312 | C<Fatal> or C<autodie>, or have been exported from a module. |
313 | Attempting to ue C<Fatal> or C<autodie> on other user subroutines will |
314 | result in a compile-time error. |
315 | |
316 | =head2 REPORTING BUGS |
317 | |
318 | Please report bugs via the CPAN Request Tracker at |
319 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>. |
320 | |
321 | =head1 FEEDBACK |
322 | |
323 | If you find this module useful, please consider rating it on the |
324 | CPAN Ratings service at |
325 | L<http://cpanratings.perl.org/rate?distribution=autodie> . |
326 | |
327 | The module author loves to hear how C<autodie> has made your life |
328 | better (or worse). Feedback can be sent to |
329 | E<lt>pjf@perltraining.com.auE<gt>. |
330 | |
331 | =head1 AUTHOR |
332 | |
333 | Copyright 2008, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt> |
334 | |
335 | =head1 LICENSE |
336 | |
337 | This module is free software. You may distribute it under the |
338 | same terms as Perl itself. |
339 | |
340 | =head1 SEE ALSO |
341 | |
342 | L<Fatal>, L<autodie::exception>, L<IPC::System::Simple> |
343 | |
344 | I<Perl tips, autodie> at |
345 | L<http://perltraining.com.au/tips/2008-08-20.html> |
346 | |
347 | =head1 ACKNOWLEDGEMENTS |
348 | |
349 | Mark Reed and Roland Giersig -- Klingon translators. |
350 | |
351 | See the F<AUTHORS> file for full credits. The latest version of this |
352 | file can be found at |
353 | L<http://github.com/pfenwick/autodie/tree/AUTHORS> . |
354 | |
355 | =cut |