lib/Carp.pm

   1 package Carp;
   2
   3 our $VERSION = '1.03';
   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
 182 $CarpInternal{Carp}++;
 183 $CarpInternal{warnings}++;
 184 $CarpLevel = 0;     # How many extra package levels to skip on carp.
 185                     # How many calls to skip on confess.
 186                     # Reconciling these notions is hard, use
 187                     # %Internal and %CarpInternal instead.
 188 $MaxEvalLen = 0;    # How much eval '...text...' to show. 0 = all.
 189 $MaxArgLen = 64;    # How much of each argument to print. 0 = all.
 190 $MaxArgNums = 8;    # How many arguments to print. 0 = all.
 191 $Verbose = 0;       # If true then make shortmess call longmess instead
 192
 193 require Exporter;
 194 @ISA = ('Exporter');
 195 @EXPORT = qw(confess croak carp);
 196 @EXPORT_OK = qw(cluck verbose longmess shortmess);
 197 @EXPORT_FAIL = qw(verbose);     # hook to enable verbose mode
 198
 199 =head1 BUGS
 200
 201 The Carp routines don't handle exception objects currently.
 202 If called with a first argument that is a reference, they simply
 203 call die() or warn(), as appropriate.
 204
 205 =cut
 206
 207 # if the caller specifies verbose usage ("perl -MCarp=verbose script.pl")
 208 # then the following method will be called by the Exporter which knows
 209 # to do this thanks to @EXPORT_FAIL, above.  $_[1] will contain the word
 210 # 'verbose'.
 211
 212 sub export_fail {
 213     shift;
 214     $Verbose = shift if $_[0] eq 'verbose';
 215     return @_;
 216 }
 217
 218
 219 # longmess() crawls all the way up the stack reporting on all the function
 220 # calls made.  The error string, $error, is originally constructed from the
 221 # arguments passed into longmess() via confess(), cluck() or shortmess().
 222 # This gets appended with the stack trace messages which are generated for
 223 # each function call on the stack.
 224
 225 sub longmess {
 226     {
 227         local $@;
 228         # XXX fix require to not clear $@?
 229         # don't use require unless we need to (for Safe compartments)
 230         require Carp::Heavy unless $INC{"Carp/Heavy.pm"};
 231     }
 232     # Icky backwards compatibility wrapper. :-(
 233     my $call_pack = caller();
 234     if ($Internal{$call_pack} or $CarpInternal{$call_pack}) {
 235       return longmess_heavy(@_);
 236     }
 237     else {
 238       local $CarpLevel = $CarpLevel + 1;
 239       return longmess_heavy(@_);
 240     }
 241 }
 242
 243
 244 # shortmess() is called by carp() and croak() to skip all the way up to
 245 # the top-level caller's package and report the error from there.  confess()
 246 # and cluck() generate a full stack trace so they call longmess() to
 247 # generate that.  In verbose mode shortmess() calls longmess() so
 248 # you always get a stack trace
 249
 250 sub shortmess { # Short-circuit &longmess if called via multiple packages
 251     {
 252         local $@;
 253         # XXX fix require to not clear $@?
 254         # don't use require unless we need to (for Safe compartments)
 255         require Carp::Heavy unless $INC{"Carp/Heavy.pm"};
 256     }
 257     # Icky backwards compatibility wrapper. :-(
 258     my $call_pack = caller();
 259     local @CARP_NOT = caller();
 260     shortmess_heavy(@_);
 261 }
 262
 263
 264 # the following four functions call longmess() or shortmess() depending on
 265 # whether they should generate a full stack trace (confess() and cluck())
 266 # or simply report the caller's package (croak() and carp()), respectively.
 267 # confess() and croak() die, carp() and cluck() warn.
 268
 269 sub croak   { die  shortmess @_ }
 270 sub confess { die  longmess  @_ }
 271 sub carp    { warn shortmess @_ }
 272 sub cluck   { warn longmess  @_ }
 273
 274 1;