5 carp - warn of errors (from perspective of caller)
7 cluck - warn of errors with stack backtrace
8 (not exported by default)
10 croak - die of errors (from perspective of caller)
12 confess - die of errors with stack backtrace
17 croak "We're outta here!";
20 cluck "This is how we got here!";
24 The Carp routines are useful in your own modules because
25 they act like die() or warn(), but report where the error
26 was in the code they were called from. Thus if you have a
27 routine Foo() that has a carp() in it, then the carp()
28 will report the error as occurring where Foo() was called,
29 not where carp() was called.
31 =head2 Forcing a Stack Trace
33 As a debugging aid, you can force Carp to treat a croak as a confess
34 and a carp as a cluck across I<all> modules. In other words, force a
35 detailed stack trace to be given. This can be very helpful when trying
36 to understand why, or from where, a warning or error is being generated.
38 This feature is enabled by 'importing' the non-existent symbol
39 'verbose'. You would typically enable it by saying
41 perl -MCarp=verbose script.pl
43 or by including the string C<MCarp=verbose> in the L<PERL5OPT>
48 The Carp routines don't handle exception objects currently.
49 If called with a first argument that is a reference, they simply
50 call die() or warn(), as appropriate.
54 # This package is heavily used. Be small. Be fast. Be good.
56 # Comments added by Andy Wardley <abw@kfs.org> 09-Apr-98, based on an
57 # _almost_ complete understanding of the package. Corrections and
58 # comments are welcome.
60 # The $CarpLevel variable can be set to "strip off" extra caller levels for
61 # those times when Carp calls are buried inside other functions. The
62 # $Max(EvalLen|(Arg(Len|Nums)) variables are used to specify how the eval
63 # text and function arguments should be formatted when printed.
65 $CarpLevel = 0; # How many extra package levels to skip on carp.
66 $MaxEvalLen = 0; # How much eval '...text...' to show. 0 = all.
67 $MaxArgLen = 64; # How much of each argument to print. 0 = all.
68 $MaxArgNums = 8; # How many arguments to print. 0 = all.
69 $Verbose = 0; # If true then make shortmess call longmess instead
73 @EXPORT = qw(confess croak carp);
74 @EXPORT_OK = qw(cluck verbose);
75 @EXPORT_FAIL = qw(verbose); # hook to enable verbose mode
78 # if the caller specifies verbose usage ("perl -MCarp=verbose script.pl")
79 # then the following method will be called by the Exporter which knows
80 # to do this thanks to @EXPORT_FAIL, above. $_[1] will contain the word
85 $Verbose = shift if $_[0] eq 'verbose';
90 # longmess() crawls all the way up the stack reporting on all the function
91 # calls made. The error string, $error, is originally constructed from the
92 # arguments passed into longmess() via confess(), cluck() or shortmess().
93 # This gets appended with the stack trace messages which are generated for
94 # each function call on the stack.
97 return @_ if ref $_[0];
98 my $error = join '', @_;
100 my $i = 1 + $CarpLevel;
101 my ($pack,$file,$line,$sub,$hargs,$eval,$require);
104 # crawl up the stack....
106 while (do { { package DB; @a = caller($i++) } } ) {
107 # get copies of the variables returned from caller()
108 ($pack,$file,$line,$sub,$hargs,undef,$eval,$require) = @a;
110 # if the $error error string is newline terminated then it
111 # is copied into $mess. Otherwise, $mess gets set (at the end of
112 # the 'else {' section below) to one of two things. The first time
113 # through, it is set to the "$error at $file line $line" message.
114 # $error is then set to 'called' which triggers subsequent loop
115 # iterations to append $sub to $mess before appending the "$error
116 # at $file line $line" which now actually reads "called at $file line
117 # $line". Thus, the stack trace message is constructed:
119 # first time: $mess = $error at $file line $line
120 # subsequent times: $mess .= $sub $error at $file line $line
123 if ($error =~ m/\n$/) {
126 # Build a string, $sub, which names the sub-routine called.
127 # This may also be "require ...", "eval '...' or "eval {...}"
130 $sub = "require $eval";
132 $eval =~ s/([\\\'])/\\$1/g;
133 if ($MaxEvalLen && length($eval) > $MaxEvalLen) {
134 substr($eval,$MaxEvalLen) = '...';
136 $sub = "eval '$eval'";
138 } elsif ($sub eq '(eval)') {
141 # if there are any arguments in the sub-routine call, format
142 # them according to the format variables defined earlier in
143 # this file and join them onto the $sub sub-routine string
145 # we may trash some of the args so we take a copy
146 @a = @DB::args; # must get local copy of args
147 # don't print any more than $MaxArgNums
148 if ($MaxArgNums and @a > $MaxArgNums) {
149 # cap the length of $#a and set the last element to '...'
154 # set args to the string "undef" if undefined
155 $_ = "undef", next unless defined $_;
157 # dunno what this is for...
163 # terminate the string early with '...' if too long
164 substr($_,$MaxArgLen) = '...'
165 if $MaxArgLen and $MaxArgLen < length;
167 # 'quote' arg unless it looks like a number
168 $_ = "'$_'" unless /^-?[\d.]+$/;
169 # print high-end chars as 'M-<char>' or '^<char>'
170 s/([\200-\377])/sprintf("M-%c",ord($1)&0177)/eg;
171 s/([\0-\37\177])/sprintf("^%c",ord($1)^64)/eg;
173 # append ('all', 'the', 'arguments') to the $sub string
174 $sub .= '(' . join(', ', @a) . ')';
176 # here's where the error message, $mess, gets constructed
177 $mess .= "\t$sub " if $error eq "called";
178 $mess .= "$error at $file line $line";
179 $mess .= " thread " . Thread->self->tid
180 if exists $main::{'Thread::'};
183 # we don't need to print the actual error message again so we can
184 # change this to "called" so that the string "$error at $file line
185 # $line" makes sense as "called at $file line $line".
188 # this kludge circumvents die's incorrect handling of NUL
189 my $msg = \($mess || $error);
195 # shortmess() is called by carp() and croak() to skip all the way up to
196 # the top-level caller's package and report the error from there. confess()
197 # and cluck() generate a full stack trace so they call longmess() to
198 # generate that. In verbose mode shortmess() calls longmess() so
199 # you always get a stack trace
201 sub shortmess { # Short-circuit &longmess if called via multiple packages
202 goto &longmess if $Verbose;
203 return @_ if ref $_[0];
204 my $error = join '', @_;
205 my ($prevpack) = caller(1);
206 my $extra = $CarpLevel;
208 my ($pack,$file,$line);
209 # when reporting an error, we want to report it from the context of the
210 # calling package. So what is the calling package? Within a module,
211 # there may be many calls between methods and perhaps between sub-classes
212 # and super-classes, but the user isn't interested in what happens
213 # inside the package. We start by building a hash array which keeps
214 # track of all the packages to which the calling package belongs. We
215 # do this by examining its @ISA variable. Any call from a base class
216 # method (one of our caller's @ISA packages) can be ignored
217 my %isa = ($prevpack,1);
219 # merge all the caller's @ISA packages into %isa.
220 @isa{@{"${prevpack}::ISA"}} = ()
221 if(@{"${prevpack}::ISA"});
223 # now we crawl up the calling stack and look at all the packages in
224 # there. For each package, we look to see if it has an @ISA and then
225 # we see if our caller features in that list. That would imply that
226 # our caller is a derived class of that package and its calls can also
228 while (($pack,$file,$line) = caller($i++)) {
229 if(@{$pack . "::ISA"}) {
230 my @i = @{$pack . "::ISA"};
233 # merge any relevant packages into %isa
235 if(exists $i{$prevpack} || exists $isa{$pack});
238 # and here's where we do the ignoring... if the package in
239 # question is one of our caller's base or derived packages then
240 # we can ignore it (skip it) and go onto the next (but note that
241 # the continue { } block below gets called every time)
243 if(exists $isa{$pack});
245 # Hey! We've found a package that isn't one of our caller's
246 # clan....but wait, $extra refers to the number of 'extra' levels
247 # we should skip up. If $extra > 0 then this is a false alarm.
248 # We must merge the package into the %isa hash (so we can ignore it
249 # if it pops up again), decrement $extra, and continue.
252 @isa{@{$pack . "::ISA"}} = ()
253 if(@{$pack . "::ISA"});
256 # OK! We've got a candidate package. Time to construct the
257 # relevant error message and return it. die() doesn't like
258 # to be given NUL characters (which $msg may contain) so we
261 $msg = "$error at $file line $line";
262 $msg .= " thread " . Thread->self->tid
263 if exists $main::{'Thread::'};
273 # uh-oh! It looks like we crawled all the way up the stack and
274 # never found a candidate package. Oh well, let's call longmess
275 # to generate a full stack trace. We use the magical form of 'goto'
276 # so that this shortmess() function doesn't appear on the stack
277 # to further confuse longmess() about it's calling package.
282 # the following four functions call longmess() or shortmess() depending on
283 # whether they should generate a full stack trace (confess() and cluck())
284 # or simply report the caller's package (croak() and carp()), respectively.
285 # confess() and croak() die, carp() and cluck() warn.
287 sub croak { die shortmess @_ }
288 sub confess { die longmess @_ }
289 sub carp { warn shortmess @_ }
290 sub cluck { warn longmess @_ }