Enabling strict on Carp/Heavy, + internal documentation

Date: Sat, 1 Dec 2001 07:01:09 -0500
Message-ID: <3C0D2E39@operamail.com>

Subject: More verbose POD for Carp
From: "Benjamin J. Tilly" <ben_tilly@operamail.com>                
Date: Sat, 1 Dec 2001 08:04:16 -0500
Message-ID: <3C285C2B@operamail.com>

p4raw-id: //depot/perl@13416

1 files changed, 62 insertions, 14 deletions

diff --git a/lib/Carp.pm b/lib/Carp.pm
index cd2cfdb087..84508b20da 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);