X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Fautodie.pm;h=efb93d32bc5641bf8ae8d229a4640007d3345bbe;hb=d00e3d8a4128dcffa1eb58ae423543a07d0589f8;hp=38c12f9e8eac170785a6ebc3caff91027b485278;hpb=0b09a93a0cec34bc5d1740400c4ed9500d2f1dbe;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/lib/autodie.pm b/lib/autodie.pm
index 38c12f9..efb93d3 100644
--- a/lib/autodie.pm
+++ b/lib/autodie.pm
@@ -8,7 +8,7 @@ our @ISA = qw(Fatal);
 our $VERSION;
 
 BEGIN {
-    $VERSION = "1.997";
+    $VERSION = '2.06';
 }
 
 use constant ERROR_WRONG_FATAL => q{
@@ -73,7 +73,9 @@ autodie - Replace functions with ones that succeed or die with lexical scope
 
 =head1 SYNOPSIS
 
-    use autodie;    # Recommended, implies 'use autodie qw(:default)'
+    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
 
@@ -248,10 +250,15 @@ 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 surity
+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
@@ -272,6 +279,36 @@ 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.
@@ -292,10 +329,17 @@ element.
 =item :void cannot be used with lexical scope
 
 The C<:void> option is supported in L<Fatal>, but not
-C<autodie>.  However you can explicitly disable autodie
-end the end of the current block with C<no autodie>.
+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 or C<no autodie qw(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
 
@@ -304,15 +348,40 @@ 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>).  It's strongly recommended
-you use scalar filehandles instead.
+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 ue C<Fatal> or C<autodie> on other user subroutines will
+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
@@ -330,7 +399,7 @@ E<lt>pjf@perltraining.com.auE<gt>.
 
 =head1 AUTHOR
 
-Copyright 2008, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt>
+Copyright 2008-2009, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt>
 
 =head1 LICENSE
 
@@ -339,7 +408,7 @@ same terms as Perl itself.
 
 =head1 SEE ALSO
 
-L<Fatal>, L<autodie::exception>, L<IPC::System::Simple>
+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>
@@ -350,6 +419,6 @@ 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/AUTHORS> .
+L<http://github.com/pfenwick/autodie/tree/master/AUTHORS> .
 
 =cut