1package autodie; 2use 5.008; 3use strict; 4use warnings; 5 6use Fatal (); 7our @ISA = qw(Fatal); 8our $VERSION; 9 10BEGIN { 11 $VERSION = '2.06_01'; 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 76 use autodie; # Recommended: implies 'use autodie qw(:default)' 77 78 use autodie qw(:all); # Recommended more: defaults and system/exec. 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 253provides the convenience of using the default methods, but the surety 254that no behavorial changes will occur if the C<autodie> module is 255upgraded. 256 257C<autodie> can be enabled for all of Perl's built-ins, including 258C<system> and C<exec> with: 259 260 use autodie qw(:all); 261 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 267to an C<EWOULDBLOCK> (or equivalent) condition. This means one can 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 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 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 332C<autodie>. To workaround this, C<autodie> may be explicitly disabled until 333the end of the current block with C<no autodie>. 334To disable autodie for only a single function (eg, open) 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. 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> 351is used with package filehandles (eg, C<FILE>). Scalar filehandles are 352strongly recommended instead. 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. 357Attempting to use C<Fatal> or C<autodie> on other user subroutines will 358result in a compile-time error. 359 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 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 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 402Copyright 2008-2009, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt> 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 411L<Fatal>, L<autodie::exception>, L<autodie::hints>, L<IPC::System::Simple> 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 422L<http://github.com/pfenwick/autodie/tree/master/AUTHORS> . 423 424=cut 425