lib/Carp.pm

   1 package Carp;
   2
   3 our $VERSION = '1.04';
   4
   5 =head1 NAME
   6
   7 carp    - warn of errors (from perspective of caller)
   8
   9 cluck   - warn of errors with stack backtrace
  10           (not exported by default)
  11
  12 croak   - die of errors (from perspective of caller)
  13
  14 confess - die of errors with stack backtrace
  15
  16 shortmess - return the message that carp and croak produce
  17
  18 longmess - return the message that cluck and confess produce
  19
  20 =head1 SYNOPSIS
  21
  22     use Carp;
  23     croak "We're outta here!";
  24
  25     use Carp qw(cluck);
  26     cluck "This is how we got here!";
  27
  28     print FH Carp::shortmess("This will have caller's details added");
  29     print FH Carp::longmess("This will have stack backtrace added");
  30
  31 =head1 DESCRIPTION
  32
  33 The Carp routines are useful in your own modules because
  34 they act like die() or warn(), but with a message which is more
  35 likely to be useful to a user of your module.  In the case of
  36 cluck, confess, and longmess that context is a summary of every
  37 call in the call-stack.  For a shorter message you can use carp,
  38 croak or shortmess which report the error as being from where
  39 your module was called.  There is no guarantee that that is where
  40 the error was, but it is a good educated guess.
  41
  42 You can also alter the way the output and logic of C<Carp> works, by
  43 changing some global variables in the C<Carp> namespace. See the
  44 section on C<GLOBAL VARIABLES> below.
  45
  46 Here is a more complete description of how shortmess works.  What
  47 it does is search the call-stack for a function call stack where
  48 it hasn't been told that there shouldn't be an error.  If every
  49 call is marked safe, it then gives up and gives a full stack
  50 backtrace instead.  In other words it presumes that the first likely
  51 looking potential suspect is guilty.  Its rules for telling whether
  52 a call shouldn't generate errors work as follows:
  53
  54 =over 4
  55
  56 =item 1.
  57
  58 Any call from a package to itself is safe.
  59
  60 =item 2.
  61
  62 Packages claim that there won't be errors on calls to or from
  63 packages explicitly marked as safe by inclusion in @CARP_NOT, or
  64 (if that array is empty) @ISA.  The ability to override what
  65 @ISA says is new in 5.8.
  66
  67 =item 3.
  68
  69 The trust in item 2 is transitive.  If A trusts B, and B
  70 trusts C, then A trusts C.  So if you do not override @ISA
  71 with @CARP_NOT, then this trust relationship is identical to,
  72 "inherits from".
  73
  74 =item 4.
  75
  76 Any call from an internal Perl module is safe.  (Nothing keeps
  77 user modules from marking themselves as internal to Perl, but
  78 this practice is discouraged.)
  79
  80 =item 5.
  81
  82 Any call to Carp is safe.  (This rule is what keeps it from
  83 reporting the error where you call carp/croak/shortmess.)
  84
  85 =back
  86
  87 =head2 Forcing a Stack Trace
  88
  89 As a debugging aid, you can force Carp to treat a croak as a confess
  90 and a carp as a cluck across I<all> modules. In other words, force a
  91 detailed stack trace to be given.  This can be very helpful when trying
  92 to understand why, or from where, a warning or error is being generated.
  93
  94 This feature is enabled by 'importing' the non-existent symbol
  95 'verbose'. You would typically enable it by saying
  96
  97     perl -MCarp=verbose script.pl
  98
  99 or by including the string C<MCarp=verbose> in the PERL5OPT
 100 environment variable.
 101
 102 Alternately, you can set the global variable C<$Carp::Verbose> to true.
 103 See the C<GLOBAL VARIABLES> section below.
 104
 105 =cut
 106
 107 # This package is heavily used. Be small. Be fast. Be good.
 108
 109 # Comments added by Andy Wardley <abw@kfs.org> 09-Apr-98, based on an
 110 # _almost_ complete understanding of the package.  Corrections and
 111 # comments are welcome.
 112
 113 # The members of %Internal are packages that are internal to perl.
 114 # Carp will not report errors from within these packages if it
 115 # can.  The members of %CarpInternal are internal to Perl's warning
 116 # system.  Carp will not report errors from within these packages
 117 # either, and will not report calls *to* these packages for carp and
 118 # croak.  They replace $CarpLevel, which is deprecated.    The
 119 # $Max(EvalLen|(Arg(Len|Nums)) variables are used to specify how the eval
 120 # text and function arguments should be formatted when printed.
 121
 122 # Comments added by Jos I. Boumans <kane@dwim.org> 11-Aug-2004
 123 # I can not get %CarpInternal or %Internal to work as advertised,
 124 # therefor leaving it out of the below documentation.
 125 # $CarpLevel may be decprecated according to the last comment, but
 126 # after 6 years, it's still around and in heavy use ;)
 127
 128 =pod
 129
 130 =head1 GLOBAL VARIABLES
 131
 132 =head2 $Carp::CarpLevel
 133
 134 This variable determines how many call frames are to be skipped when
 135 reporting where an error occurred on a call to one of C<Carp>'s
 136 functions. For example:
 137
 138     $Carp::CarpLevel = 1;
 139     sub bar     { .... or _error('Wrong input') }
 140     sub _error  { Carp::carp(@_) }
 141
 142 This would make Carp report the error as coming from C<bar>'s caller,
 143 rather than from C<_error>'s caller, as it normally would.
 144
 145 Defaults to C<0>.
 146
 147 =head2 $Carp::MaxEvalLen
 148
 149 This variable determines how many characters of a string-eval are to
 150 be shown in the output. Use a value of C<0> to show all text.
 151
 152 Defaults to C<0>.
 153
 154 =head2 $Carp::MaxArgLen
 155
 156 This variable determines how many characters of each argument to a
 157 function to print. Use a value of C<0> to show the full length of the
 158 argument.
 159
 160 Defaults to C<64>.
 161
 162 =head2 $Carp::MaxArgNums
 163
 164 This variable determines how many arguments to each function to show.
 165 Use a value of C<0> to show all arguments to a function call.
 166
 167 Defaults to C<8>.
 168
 169 =head2 $Carp::Verbose
 170
 171 This variable makes C<Carp> use the C<longmess> function at all times.
 172 This effectively means that all calls to C<carp> become C<cluck> and
 173 all calls to C<croak> become C<confess>.
 174
 175 Note, this is analogous to using C<use Carp 'verbose'>.
 176
 177 Defaults to C<0>.
 178
 179 =cut
 180
 181 # disable these by default, so they can live w/o require Carp
 182 $CarpInternal{Carp}++;
 183 $CarpInternal{warnings}++;
 184 $Internal{Exporter}++;
 185 $Internal{'Exporter::Heavy'}++;
 186 $CarpLevel = 0;     # How many extra package levels to skip on carp.
 187                     # How many calls to skip on confess.
 188                     # Reconciling these notions is hard, use
 189                     # %Internal and %CarpInternal instead.
 190 $MaxEvalLen = 0;    # How much eval '...text...' to show. 0 = all.
 191 $MaxArgLen = 64;    # How much of each argument to print. 0 = all.
 192 $MaxArgNums = 8;    # How many arguments to print. 0 = all.
 193 $Verbose = 0;       # If true then make shortmess call longmess instead
 194
 195 require Exporter;
 196 @ISA = ('Exporter');
 197 @EXPORT = qw(confess croak carp);
 198 @EXPORT_OK = qw(cluck verbose longmess shortmess);
 199 @EXPORT_FAIL = qw(verbose);     # hook to enable verbose mode
 200
 201 =head1 BUGS
 202
 203 The Carp routines don't handle exception objects currently.
 204 If called with a first argument that is a reference, they simply
 205 call die() or warn(), as appropriate.
 206
 207 =cut
 208
 209 # if the caller specifies verbose usage ("perl -MCarp=verbose script.pl")
 210 # then the following method will be called by the Exporter which knows
 211 # to do this thanks to @EXPORT_FAIL, above.  $_[1] will contain the word
 212 # 'verbose'.
 213
 214 sub export_fail {
 215     shift;
 216     $Verbose = shift if $_[0] eq 'verbose';
 217     return @_;
 218 }
 219
 220
 221 # longmess() crawls all the way up the stack reporting on all the function
 222 # calls made.  The error string, $error, is originally constructed from the
 223 # arguments passed into longmess() via confess(), cluck() or shortmess().
 224 # This gets appended with the stack trace messages which are generated for
 225 # each function call on the stack.
 226
 227 sub longmess {
 228     {
 229         local($@, $!);
 230         # XXX fix require to not clear $@ or $!?
 231         # don't use require unless we need to (for Safe compartments)
 232         require Carp::Heavy unless $INC{"Carp/Heavy.pm"};
 233     }
 234     # Icky backwards compatibility wrapper. :-(
 235     my $call_pack = caller();
 236     if ($Internal{$call_pack} or $CarpInternal{$call_pack}) {
 237       return longmess_heavy(@_);
 238     }
 239     else {
 240       local $CarpLevel = $CarpLevel + 1;
 241       return longmess_heavy(@_);
 242     }
 243 }
 244
 245
 246 # shortmess() is called by carp() and croak() to skip all the way up to
 247 # the top-level caller's package and report the error from there.  confess()
 248 # and cluck() generate a full stack trace so they call longmess() to
 249 # generate that.  In verbose mode shortmess() calls longmess() so
 250 # you always get a stack trace
 251
 252 sub shortmess { # Short-circuit &longmess if called via multiple packages
 253     {
 254         local($@, $!);
 255         # XXX fix require to not clear $@ or $!?
 256         # don't use require unless we need to (for Safe compartments)
 257         require Carp::Heavy unless $INC{"Carp/Heavy.pm"};
 258     }
 259     # Icky backwards compatibility wrapper. :-(
 260     my $call_pack = caller();
 261     local @CARP_NOT = caller();
 262     shortmess_heavy(@_);
 263 }
 264
 265
 266 # the following four functions call longmess() or shortmess() depending on
 267 # whether they should generate a full stack trace (confess() and cluck())
 268 # or simply report the caller's package (croak() and carp()), respectively.
 269 # confess() and croak() die, carp() and cluck() warn.
 270
 271 sub croak   { die  shortmess @_ }
 272 sub confess { die  longmess  @_ }
 273 sub carp    { warn shortmess @_ }
 274 sub cluck   { warn longmess  @_ }
 275
 276 1;