| 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.997"; |
| 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 |