X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCarp.pm;h=5dbae299fdbd11d1218e52a2fdbd1b20e0c7d144;hb=917211f59b1d5210f3944956e717bae1a2ca7565;hp=cd2cfdb087253e9083f92de44dee9957abf80455;hpb=042e981a9d7db562893cb666e399d7ed2acc518d;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/lib/Carp.pm b/lib/Carp.pm
index cd2cfdb..5dbae29 100644
--- a/lib/Carp.pm
+++ b/lib/Carp.pm
@@ -1,6 +1,6 @@
 package Carp;
 
-our $VERSION = '1.00';
+our $VERSION = '1.01';
 
 =head1 NAME
 
@@ -13,6 +13,10 @@ croak   - die of errors (from perspective of caller)
 
 confess - die of errors with stack backtrace
 
+shortmess - return the message that carp and croak produce
+
+longmess - return the message that cluck and confess produce
+
 =head1 SYNOPSIS
 
     use Carp;
@@ -27,16 +31,54 @@ confess - die of errors with stack backtrace
 =head1 DESCRIPTION
 
 The Carp routines are useful in your own modules because
-they act like die() or warn(), but report where the error
-was in the code they were called from.  Thus if you have a 
-routine Foo() that has a carp() in it, then the carp() 
-will report the error as occurring where Foo() was called, 
-not where carp() was called.
+they act like die() or warn(), but with a message which is more
+likely to be useful to a user of your module.  In the case of
+cluck, confess, and longmess that context is a summary of every
+call in the call-stack.  For a shorter message you can use carp,
+croak or shortmess which report the error as being from where
+your module was called.  There is no guarantee that that is where
+the error was, but it is a good educated guess.
+
+Here is a more complete description of how shortmess works.  What
+it does is search the call-stack for a function call stack where
+it hasn't been told that there shouldn't be an error.  If every
+call is marked safe, it then gives up and gives a full stack
+backtrace instead.  In other words it presumes that the first likely
+looking potential suspect is guilty.  Its rules for telling whether
+a call shouldn't generate errors work as follows:
+
+=over 4
+
+=item 1.
+
+Any call from a package to itself is safe. 
+
+=item 2.
+
+Packages claim that there won't be errors on calls to or from
+packages explicitly marked as safe by inclusion in @CARP_NOT, or
+(if that array is empty) @ISA.  The ability to override what
+@ISA says is new in 5.8.
+
+=item 3.
 
-The routine shortmess() can be used to generate the string that
-carp/croak would have produced.   The routine longmess() can be
-used to generate the backtrace that cluck/confess would have
-produced.
+The trust in item 2 is transitive.  If A trusts B, and B
+trusts C, then A trusts C.  So if you do not override @ISA
+with @CARP_NOT, then this trust relationship is identical to,
+"inherits from".
+
+=item 4.
+
+Any call from an internal Perl module is safe.  (Nothing keeps
+user modules from marking themselves as internal to Perl, but
+this practice is discouraged.)
+
+=item 5.
+
+Any call to Carp is safe.  (This rule is what keeps it from
+reporting the error where you call carp/croak/shortmess.)
+
+=back
 
 =head2 Forcing a Stack Trace
 
@@ -67,19 +109,25 @@ call die() or warn(), as appropriate.
 # _almost_ complete understanding of the package.  Corrections and
 # comments are welcome.
 
-# The $CarpLevel variable can be set to "strip off" extra caller levels for
-# those times when Carp calls are buried inside other functions.  The
+# The members of %Internal are packages that are internal to perl.
+# Carp will not report errors from within these packages if it
+# can.  The members of %CarpInternal are internal to Perl's warning
+# system.  Carp will not report errors from within these packages
+# either, and will not report calls *to* these packages for carp and
+# croak.  They replace $CarpLevel, which is deprecated.    The
 # $Max(EvalLen|(Arg(Len|Nums)) variables are used to specify how the eval
 # text and function arguments should be formatted when printed.
 
+$CarpInternal{Carp}++;
 $CarpLevel = 0;		# How many extra package levels to skip on carp.
+                        # How many calls to skip on confess.
+                        # Reconciling these notions is hard, use
+                        # %Internal and %CarpInternal instead.
 $MaxEvalLen = 0;	# How much eval '...text...' to show. 0 = all.
 $MaxArgLen = 64;        # How much of each argument to print. 0 = all.
 $MaxArgNums = 8;        # How many arguments to print. 0 = all.
 $Verbose = 0;		# If true then make shortmess call longmess instead
 
-$CarpInternal{Carp}++;
-
 require Exporter;
 @ISA = ('Exporter');
 @EXPORT = qw(confess croak carp);
@@ -107,7 +155,15 @@ sub export_fail {
 
 sub longmess {
     { local $@; require Carp::Heavy; }	# XXX fix require to not clear $@?
-    goto &longmess_heavy;
+    # Icky backwards compatibility wrapper. :-(
+    my $call_pack = caller();
+    if ($Internal{$call_pack} or $CarpInternal{$call_pack}) {
+      return longmess_heavy(@_);
+    }
+    else {
+      local $CarpLevel = $CarpLevel + 1;
+      return longmess_heavy(@_);
+    }
 }
 
 
@@ -119,7 +175,10 @@ sub longmess {
 
 sub shortmess {	# Short-circuit &longmess if called via multiple packages
     { local $@; require Carp::Heavy; }	# XXX fix require to not clear $@?
-    goto &shortmess_heavy;
+    # Icky backwards compatibility wrapper. :-(
+    my $call_pack = caller();
+    local @CARP_NOT = caller();
+    shortmess_heavy(@_);
 }