diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/autodie.pm')
-rw-r--r-- | Master/tlpkg/tlperl/lib/autodie.pm | 424 |
1 files changed, 424 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/autodie.pm b/Master/tlpkg/tlperl/lib/autodie.pm new file mode 100644 index 00000000000..8e8e7094c7c --- /dev/null +++ b/Master/tlpkg/tlperl/lib/autodie.pm @@ -0,0 +1,424 @@ +package autodie; +use 5.008; +use strict; +use warnings; + +use Fatal (); +our @ISA = qw(Fatal); +our $VERSION; + +BEGIN { + $VERSION = '2.06_01'; +} + +use constant ERROR_WRONG_FATAL => q{ +Incorrect version of Fatal.pm loaded by autodie. + +The autodie pragma uses an updated version of Fatal to do its +heavy lifting. We seem to have loaded Fatal version %s, which is +probably the version that came with your version of Perl. However +autodie needs version %s, which would have come bundled with +autodie. + +You may be able to solve this problem by adding the following +line of code to your main program, before any use of Fatal or +autodie. + + use lib "%s"; + +}; + +# We have to check we've got the right version of Fatal before we +# try to compile the rest of our code, lest we use a constant +# that doesn't exist. + +BEGIN { + + # If we have the wrong Fatal, then we've probably loaded the system + # one, not our own. Complain, and give a useful hint. ;) + + if ($Fatal::VERSION ne $VERSION) { + my $autodie_path = $INC{'autodie.pm'}; + + $autodie_path =~ s/autodie\.pm//; + + require Carp; + + Carp::croak sprintf( + ERROR_WRONG_FATAL, $Fatal::VERSION, $VERSION, $autodie_path + ); + } +} + +# When passing args to Fatal we want to keep the first arg +# (our package) in place. Hence the splice. + +sub import { + splice(@_,1,0,Fatal::LEXICAL_TAG); + goto &Fatal::import; +} + +sub unimport { + splice(@_,1,0,Fatal::LEXICAL_TAG); + goto &Fatal::unimport; +} + +1; + +__END__ + +=head1 NAME + +autodie - Replace functions with ones that succeed or die with lexical scope + +=head1 SYNOPSIS + + use autodie; # Recommended: implies 'use autodie qw(:default)' + + use autodie qw(:all); # Recommended more: defaults and system/exec. + + use autodie qw(open close); # open/close succeed or die + + open(my $fh, "<", $filename); # No need to check! + + { + no autodie qw(open); # open failures won't die + open(my $fh, "<", $filename); # Could fail silently! + no autodie; # disable all autodies + } + +=head1 DESCRIPTION + + bIlujDI' yIchegh()Qo'; yIHegh()! + + It is better to die() than to return() in failure. + + -- Klingon programming proverb. + +The C<autodie> pragma provides a convenient way to replace functions +that normally return false on failure with equivalents that throw +an exception on failure. + +The C<autodie> pragma has I<lexical scope>, meaning that functions +and subroutines altered with C<autodie> will only change their behaviour +until the end of the enclosing block, file, or C<eval>. + +If C<system> is specified as an argument to C<autodie>, then it +uses L<IPC::System::Simple> to do the heavy lifting. See the +description of that module for more information. + +=head1 EXCEPTIONS + +Exceptions produced by the C<autodie> pragma are members of the +L<autodie::exception> class. The preferred way to work with +these exceptions under Perl 5.10 is as follows: + + use feature qw(switch); + + eval { + use autodie; + + open(my $fh, '<', $some_file); + + my @records = <$fh>; + + # Do things with @records... + + close($fh); + + }; + + given ($@) { + when (undef) { say "No error"; } + when ('open') { say "Error from open"; } + when (':io') { say "Non-open, IO error."; } + when (':all') { say "All other autodie errors." } + default { say "Not an autodie error at all." } + } + +Under Perl 5.8, the C<given/when> structure is not available, so the +following structure may be used: + + eval { + use autodie; + + open(my $fh, '<', $some_file); + + my @records = <$fh>; + + # Do things with @records... + + close($fh); + }; + + if ($@ and $@->isa('autodie::exception')) { + if ($@->matches('open')) { print "Error from open\n"; } + if ($@->matches(':io' )) { print "Non-open, IO error."; } + } elsif ($@) { + # A non-autodie exception. + } + +See L<autodie::exception> for further information on interrogating +exceptions. + +=head1 CATEGORIES + +Autodie uses a simple set of categories to group together similar +built-ins. Requesting a category type (starting with a colon) will +enable autodie for all built-ins beneath that category. For example, +requesting C<:file> will enable autodie for C<close>, C<fcntl>, +C<fileno>, C<open> and C<sysopen>. + +The categories are currently: + + :all + :default + :io + read + seek + sysread + sysseek + syswrite + :dbm + dbmclose + dbmopen + :file + binmode + close + fcntl + fileno + flock + ioctl + open + sysopen + truncate + :filesys + chdir + closedir + opendir + link + mkdir + readlink + rename + rmdir + symlink + unlink + :ipc + pipe + :msg + msgctl + msgget + msgrcv + msgsnd + :semaphore + semctl + semget + semop + :shm + shmctl + shmget + shmread + :socket + accept + bind + connect + getsockopt + listen + recv + send + setsockopt + shutdown + socketpair + :threads + fork + :system + system + exec + + +Note that while the above category system is presently a strict +hierarchy, this should not be assumed. + +A plain C<use autodie> implies C<use autodie qw(:default)>. Note that +C<system> and C<exec> are not enabled by default. C<system> requires +the optional L<IPC::System::Simple> module to be installed, and enabling +C<system> or C<exec> will invalidate their exotic forms. See L</BUGS> +below for more details. + +The syntax: + + use autodie qw(:1.994); + +allows the C<:default> list from a particular version to be used. This +provides the convenience of using the default methods, but the surety +that no behavorial changes will occur if the C<autodie> module is +upgraded. + +C<autodie> can be enabled for all of Perl's built-ins, including +C<system> and C<exec> with: + + use autodie qw(:all); + +=head1 FUNCTION SPECIFIC NOTES + +=head2 flock + +It is not considered an error for C<flock> to return false if it fails +to an C<EWOULDBLOCK> (or equivalent) condition. This means one can +still use the common convention of testing the return value of +C<flock> when called with the C<LOCK_NB> option: + + use autodie; + + if ( flock($fh, LOCK_EX | LOCK_NB) ) { + # We have a lock + } + +Autodying C<flock> will generate an exception if C<flock> returns +false with any other error. + +=head2 system/exec + +The C<system> built-in is considered to have failed in the following +circumstances: + +=over 4 + +=item * + +The command does not start. + +=item * + +The command is killed by a signal. + +=item * + +The command returns a non-zero exit value (but see below). + +=back + +On success, the autodying form of C<system> returns the I<exit value> +rather than the contents of C<$?>. + +Additional allowable exit values can be supplied as an optional first +argument to autodying C<system>: + + system( [ 0, 1, 2 ], $cmd, @args); # 0,1,2 are good exit values + +C<autodie> uses the L<IPC::System::Simple> module to change C<system>. +See its documentation for further information. + +Applying C<autodie> to C<system> or C<exec> causes the exotic +forms C<system { $cmd } @args > or C<exec { $cmd } @args> +to be considered a syntax error until the end of the lexical scope. +If you really need to use the exotic form, you can call C<CORE::system> +or C<CORE::exec> instead, or use C<no autodie qw(system exec)> before +calling the exotic form. + +=head1 GOTCHAS + +Functions called in list context are assumed to have failed if they +return an empty list, or a list consisting only of a single undef +element. + +=head1 DIAGNOSTICS + +=over 4 + +=item :void cannot be used with lexical scope + +The C<:void> option is supported in L<Fatal>, but not +C<autodie>. To workaround this, C<autodie> may be explicitly disabled until +the end of the current block with C<no autodie>. +To disable autodie for only a single function (eg, open) +use C<no autodie qw(open)>. + +=item No user hints defined for %s + +You've insisted on hints for user-subroutines, either by pre-pending +a C<!> to the subroutine name itself, or earlier in the list of arguments +to C<autodie>. However the subroutine in question does not have +any hints available. + +=back + +See also L<Fatal/DIAGNOSTICS>. + +=head1 BUGS + +"Used only once" warnings can be generated when C<autodie> or C<Fatal> +is used with package filehandles (eg, C<FILE>). Scalar filehandles are +strongly recommended instead. + +When using C<autodie> or C<Fatal> with user subroutines, the +declaration of those subroutines must appear before the first use of +C<Fatal> or C<autodie>, or have been exported from a module. +Attempting to use C<Fatal> or C<autodie> on other user subroutines will +result in a compile-time error. + +Due to a bug in Perl, C<autodie> may "lose" any format which has the +same name as an autodying built-in or function. + +C<autodie> may not work correctly if used inside a file with a +name that looks like a string eval, such as F<eval (3)>. + +=head2 autodie and string eval + +Due to the current implementation of C<autodie>, unexpected results +may be seen when used near or with the string version of eval. +I<None of these bugs exist when using block eval>. + +Under Perl 5.8 only, C<autodie> I<does not> propagate into string C<eval> +statements, although it can be explicitly enabled inside a string +C<eval>. + +Under Perl 5.10 only, using a string eval when C<autodie> is in +effect can cause the autodie behaviour to leak into the surrounding +scope. This can be worked around by using a C<no autodie> at the +end of the scope to explicitly remove autodie's effects, or by +avoiding the use of string eval. + +I<None of these bugs exist when using block eval>. The use of +C<autodie> with block eval is considered good practice. + +=head2 REPORTING BUGS + +Please report bugs via the CPAN Request Tracker at +L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>. + +=head1 FEEDBACK + +If you find this module useful, please consider rating it on the +CPAN Ratings service at +L<http://cpanratings.perl.org/rate?distribution=autodie> . + +The module author loves to hear how C<autodie> has made your life +better (or worse). Feedback can be sent to +E<lt>pjf@perltraining.com.auE<gt>. + +=head1 AUTHOR + +Copyright 2008-2009, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt> + +=head1 LICENSE + +This module is free software. You may distribute it under the +same terms as Perl itself. + +=head1 SEE ALSO + +L<Fatal>, L<autodie::exception>, L<autodie::hints>, L<IPC::System::Simple> + +I<Perl tips, autodie> at +L<http://perltraining.com.au/tips/2008-08-20.html> + +=head1 ACKNOWLEDGEMENTS + +Mark Reed and Roland Giersig -- Klingon translators. + +See the F<AUTHORS> file for full credits. The latest version of this +file can be found at +L<http://github.com/pfenwick/autodie/tree/master/AUTHORS> . + +=cut |