[ PATCH ] mymalloc on HP-UX
[p5sagit/p5-mst-13.2.git] / lib / Carp.pm
CommitLineData
a0d0e21e 1package Carp;
2
a3775ca3 3our $VERSION = '1.01';
b75c8c73 4
f06db76b 5=head1 NAME
6
4d935a29 7carp - warn of errors (from perspective of caller)
f06db76b 8
4d935a29 9cluck - warn of errors with stack backtrace
10 (not exported by default)
11
12croak - die of errors (from perspective of caller)
f06db76b 13
14confess - die of errors with stack backtrace
15
af80c6a7 16shortmess - return the message that carp and croak produce
17
18longmess - return the message that cluck and confess produce
19
f06db76b 20=head1 SYNOPSIS
21
22 use Carp;
23 croak "We're outta here!";
24
4d935a29 25 use Carp qw(cluck);
26 cluck "This is how we got here!";
27
af80c6a7 28 print FH Carp::shortmess("This will have caller's details added");
29 print FH Carp::longmess("This will have stack backtrace added");
30
f06db76b 31=head1 DESCRIPTION
32
33The Carp routines are useful in your own modules because
a3775ca3 34they act like die() or warn(), but with a message which is more
35likely to be useful to a user of your module. In the case of
af80c6a7 36cluck, confess, and longmess that context is a summary of every
37call in the call-stack. For a shorter message you can use carp,
38croak or shortmess which report the error as being from where
a3775ca3 39your module was called. There is no guarantee that that is where
40the error was, but it is a good educated guess.
41
af80c6a7 42Here is a more complete description of how shortmess works. What
43it does is search the call-stack for a function call stack where
a3775ca3 44it hasn't been told that there shouldn't be an error. If every
45call is marked safe, it then gives up and gives a full stack
46backtrace instead. In other words it presumes that the first likely
47looking potential suspect is guilty. Its rules for telling whether
48a call shouldn't generate errors work as follows:
49
50=over 4
51
52=item 1.
53
54Any call from a package to itself is safe.
55
56=item 2.
57
58Packages claim that there won't be errors on calls to or from
59packages explicitly marked as safe by inclusion in @CARP_NOT, or
60(if that array is empty) @ISA. The ability to override what
61@ISA says is new in 5.8.
62
63=item 3.
f06db76b 64
a3775ca3 65The trust in item 2 is transitive. If A trusts B, and B
66trusts C, then A trusts C. So if you do not override @ISA
67with @CARP_NOT, then this trust relationship is identical to,
68"inherits from".
69
70=item 4.
71
72Any call from an internal Perl module is safe. (Nothing keeps
73user modules from marking themselves as internal to Perl, but
74this practice is discouraged.)
75
76=item 5.
77
78Any call to Carp is safe. (This rule is what keeps it from
af80c6a7 79reporting the error where you call carp/croak/shortmess.)
a3775ca3 80
81=back
9120d252 82
4d935a29 83=head2 Forcing a Stack Trace
84
85As a debugging aid, you can force Carp to treat a croak as a confess
86and a carp as a cluck across I<all> modules. In other words, force a
87detailed stack trace to be given. This can be very helpful when trying
88to understand why, or from where, a warning or error is being generated.
89
f610777f 90This feature is enabled by 'importing' the non-existent symbol
4d935a29 91'verbose'. You would typically enable it by saying
92
93 perl -MCarp=verbose script.pl
94
042e981a 95or by including the string C<MCarp=verbose> in the PERL5OPT
4d935a29 96environment variable.
97
d2fe67be 98=head1 BUGS
99
100The Carp routines don't handle exception objects currently.
101If called with a first argument that is a reference, they simply
102call die() or warn(), as appropriate.
103
f06db76b 104=cut
105
4d935a29 106# This package is heavily used. Be small. Be fast. Be good.
a0d0e21e 107
7b8d334a 108# Comments added by Andy Wardley <abw@kfs.org> 09-Apr-98, based on an
109# _almost_ complete understanding of the package. Corrections and
110# comments are welcome.
111
a3775ca3 112# The members of %Internal are packages that are internal to perl.
113# Carp will not report errors from within these packages if it
114# can. The members of %CarpInternal are internal to Perl's warning
115# system. Carp will not report errors from within these packages
116# either, and will not report calls *to* these packages for carp and
117# croak. They replace $CarpLevel, which is deprecated. The
7b8d334a 118# $Max(EvalLen|(Arg(Len|Nums)) variables are used to specify how the eval
119# text and function arguments should be formatted when printed.
120
a3775ca3 121$CarpInternal{Carp}++;
c3186b65 122$CarpInternal{warnings}++;
748a9306 123$CarpLevel = 0; # How many extra package levels to skip on carp.
a3775ca3 124 # How many calls to skip on confess.
125 # Reconciling these notions is hard, use
126 # %Internal and %CarpInternal instead.
c07a80fd 127$MaxEvalLen = 0; # How much eval '...text...' to show. 0 = all.
55497cff 128$MaxArgLen = 64; # How much of each argument to print. 0 = all.
129$MaxArgNums = 8; # How many arguments to print. 0 = all.
6ff81951 130$Verbose = 0; # If true then make shortmess call longmess instead
748a9306 131
a0d0e21e 132require Exporter;
fb73857a 133@ISA = ('Exporter');
a0d0e21e 134@EXPORT = qw(confess croak carp);
af80c6a7 135@EXPORT_OK = qw(cluck verbose longmess shortmess);
136@EXPORT_FAIL = qw(verbose); # hook to enable verbose mode
137
138
139# if the caller specifies verbose usage ("perl -MCarp=verbose script.pl")
140# then the following method will be called by the Exporter which knows
141# to do this thanks to @EXPORT_FAIL, above. $_[1] will contain the word
142# 'verbose'.
143
144sub export_fail {
145 shift;
146 $Verbose = shift if $_[0] eq 'verbose';
147 return @_;
4d935a29 148}
149
a0d0e21e 150
7b8d334a 151# longmess() crawls all the way up the stack reporting on all the function
152# calls made. The error string, $error, is originally constructed from the
153# arguments passed into longmess() via confess(), cluck() or shortmess().
154# This gets appended with the stack trace messages which are generated for
155# each function call on the stack.
156
a0d0e21e 157sub longmess {
0bcd2fea 158 { local $@; require Carp::Heavy; } # XXX fix require to not clear $@?
c01c1f0d 159 # Icky backwards compatibility wrapper. :-(
160 my $call_pack = caller();
161 if ($Internal{$call_pack} or $CarpInternal{$call_pack}) {
162 return longmess_heavy(@_);
163 }
164 else {
165 local $CarpLevel = $CarpLevel + 1;
166 return longmess_heavy(@_);
167 }
a0d0e21e 168}
169
7b8d334a 170
171# shortmess() is called by carp() and croak() to skip all the way up to
172# the top-level caller's package and report the error from there. confess()
173# and cluck() generate a full stack trace so they call longmess() to
6ff81951 174# generate that. In verbose mode shortmess() calls longmess() so
7b8d334a 175# you always get a stack trace
176
748a9306 177sub shortmess { # Short-circuit &longmess if called via multiple packages
0bcd2fea 178 { local $@; require Carp::Heavy; } # XXX fix require to not clear $@?
c01c1f0d 179 # Icky backwards compatibility wrapper. :-(
180 my $call_pack = caller();
181 local @CARP_NOT = caller();
182 shortmess_heavy(@_);
a0d0e21e 183}
184
7b8d334a 185
186# the following four functions call longmess() or shortmess() depending on
187# whether they should generate a full stack trace (confess() and cluck())
188# or simply report the caller's package (croak() and carp()), respectively.
189# confess() and croak() die, carp() and cluck() warn.
190
191sub croak { die shortmess @_ }
192sub confess { die longmess @_ }
193sub carp { warn shortmess @_ }
194sub cluck { warn longmess @_ }
a0d0e21e 195
748a9306 1961;