lib/Carp.pm

   1 package Carp;
   2
   3 our $VERSION = '1.05';
   4 # this file is an utra-lightweight stub. The first time a function is
   5 # called, Carp::Heavy is loaded, and the real short/longmessmess_jmp
   6 # subs are installed
   7
   8 our $MaxEvalLen = 0;
   9 our $Verbose    = 0;
  10 our $CarpLevel  = 0;
  11 our $MaxArgLen  = 64;   # How much of each argument to print. 0 = all.
  12 our $MaxArgNums = 8;    # How many arguments to print. 0 = all.
  13
  14 require Exporter;
  15 our @ISA = ('Exporter');
  16 our @EXPORT = qw(confess croak carp);
  17 our @EXPORT_OK = qw(cluck verbose longmess shortmess);
  18 our @EXPORT_FAIL = qw(verbose); # hook to enable verbose mode
  19
  20 # if the caller specifies verbose usage ("perl -MCarp=verbose script.pl")
  21 # then the following method will be called by the Exporter which knows
  22 # to do this thanks to @EXPORT_FAIL, above.  $_[1] will contain the word
  23 # 'verbose'.
  24
  25 sub export_fail { shift; $Verbose = shift if $_[0] eq 'verbose'; @_ }
  26
  27 # fixed hooks for stashes to point to
  28 sub longmess  { goto &longmess_jmp }
  29 sub shortmess { goto &shortmess_jmp }
  30 # these two are replaced when Carp::Heavy is loaded
  31 sub longmess_jmp  {
  32     local($@, $!);
  33     eval { require Carp::Heavy };
  34     return $@ if $@;
  35     goto &longmess_jmp;
  36 }
  37 sub shortmess_jmp  {
  38     local($@, $!);
  39     eval { require Carp::Heavy };
  40     return $@ if $@;
  41     goto &shortmess_jmp;
  42 }
  43
  44 sub croak   { die  shortmess @_ }
  45 sub confess { die  longmess  @_ }
  46 sub carp    { warn shortmess @_ }
  47 sub cluck   { warn longmess  @_ }
  48
  49 1;
  50 __END__
  51
  52 =head1 NAME
  53
  54 carp    - warn of errors (from perspective of caller)
  55
  56 cluck   - warn of errors with stack backtrace
  57           (not exported by default)
  58
  59 croak   - die of errors (from perspective of caller)
  60
  61 confess - die of errors with stack backtrace
  62
  63 shortmess - return the message that carp and croak produce
  64
  65 longmess - return the message that cluck and confess produce
  66
  67 =head1 SYNOPSIS
  68
  69     use Carp;
  70     croak "We're outta here!";
  71
  72     use Carp qw(cluck);
  73     cluck "This is how we got here!";
  74
  75     print FH Carp::shortmess("This will have caller's details added");
  76     print FH Carp::longmess("This will have stack backtrace added");
  77
  78 =head1 DESCRIPTION
  79
  80 The Carp routines are useful in your own modules because
  81 they act like die() or warn(), but with a message which is more
  82 likely to be useful to a user of your module.  In the case of
  83 cluck, confess, and longmess that context is a summary of every
  84 call in the call-stack.  For a shorter message you can use carp,
  85 croak or shortmess which report the error as being from where
  86 your module was called.  There is no guarantee that that is where
  87 the error was, but it is a good educated guess.
  88
  89 You can also alter the way the output and logic of C<Carp> works, by
  90 changing some global variables in the C<Carp> namespace. See the
  91 section on C<GLOBAL VARIABLES> below.
  92
  93 Here is a more complete description of how shortmess works.  What
  94 it does is search the call-stack for a function call stack where
  95 it hasn't been told that there shouldn't be an error.  If every
  96 call is marked safe, it then gives up and gives a full stack
  97 backtrace instead.  In other words it presumes that the first likely
  98 looking potential suspect is guilty.  Its rules for telling whether
  99 a call shouldn't generate errors work as follows:
 100
 101 =over 4
 102
 103 =item 1.
 104
 105 Any call from a package to itself is safe.
 106
 107 =item 2.
 108
 109 Packages claim that there won't be errors on calls to or from
 110 packages explicitly marked as safe by inclusion in @CARP_NOT, or
 111 (if that array is empty) @ISA.  The ability to override what
 112 @ISA says is new in 5.8.
 113
 114 =item 3.
 115
 116 The trust in item 2 is transitive.  If A trusts B, and B
 117 trusts C, then A trusts C.  So if you do not override @ISA
 118 with @CARP_NOT, then this trust relationship is identical to,
 119 "inherits from".
 120
 121 =item 4.
 122
 123 Any call from an internal Perl module is safe.  (Nothing keeps
 124 user modules from marking themselves as internal to Perl, but
 125 this practice is discouraged.)
 126
 127 =item 5.
 128
 129 Any call to Carp is safe.  (This rule is what keeps it from
 130 reporting the error where you call carp/croak/shortmess.)
 131
 132 =back
 133
 134 =head2 Forcing a Stack Trace
 135
 136 As a debugging aid, you can force Carp to treat a croak as a confess
 137 and a carp as a cluck across I<all> modules. In other words, force a
 138 detailed stack trace to be given.  This can be very helpful when trying
 139 to understand why, or from where, a warning or error is being generated.
 140
 141 This feature is enabled by 'importing' the non-existent symbol
 142 'verbose'. You would typically enable it by saying
 143
 144     perl -MCarp=verbose script.pl
 145
 146 or by including the string C<MCarp=verbose> in the PERL5OPT
 147 environment variable.
 148
 149 Alternately, you can set the global variable C<$Carp::Verbose> to true.
 150 See the C<GLOBAL VARIABLES> section below.
 151
 152 =head1 GLOBAL VARIABLES
 153
 154 =head2 $Carp::CarpLevel
 155
 156 This variable determines how many call frames are to be skipped when
 157 reporting where an error occurred on a call to one of C<Carp>'s
 158 functions. For example:
 159
 160     $Carp::CarpLevel = 1;
 161     sub bar     { .... or _error('Wrong input') }
 162     sub _error  { Carp::carp(@_) }
 163
 164 This would make Carp report the error as coming from C<bar>'s caller,
 165 rather than from C<_error>'s caller, as it normally would.
 166
 167 Defaults to C<0>.
 168
 169 =head2 $Carp::MaxEvalLen
 170
 171 This variable determines how many characters of a string-eval are to
 172 be shown in the output. Use a value of C<0> to show all text.
 173
 174 Defaults to C<0>.
 175
 176 =head2 $Carp::MaxArgLen
 177
 178 This variable determines how many characters of each argument to a
 179 function to print. Use a value of C<0> to show the full length of the
 180 argument.
 181
 182 Defaults to C<64>.
 183
 184 =head2 $Carp::MaxArgNums
 185
 186 This variable determines how many arguments to each function to show.
 187 Use a value of C<0> to show all arguments to a function call.
 188
 189 Defaults to C<8>.
 190
 191 =head2 $Carp::Verbose
 192
 193 This variable makes C<Carp> use the C<longmess> function at all times.
 194 This effectively means that all calls to C<carp> become C<cluck> and
 195 all calls to C<croak> become C<confess>.
 196
 197 Note, this is analogous to using C<use Carp 'verbose'>.
 198
 199 Defaults to C<0>.
 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