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