extra code in pp_concat, Take 2
[p5sagit/p5-mst-13.2.git] / lib / Carp.pm
CommitLineData
a0d0e21e 1package Carp;
2
09e96b99 3our $VERSION = '1.04';
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
22dc90ad 42You can also alter the way the output and logic of C<Carp> works, by
43changing some global variables in the C<Carp> namespace. See the
44section on C<GLOBAL VARIABLES> below.
45
af80c6a7 46Here is a more complete description of how shortmess works. What
47it does is search the call-stack for a function call stack where
a3775ca3 48it hasn't been told that there shouldn't be an error. If every
49call is marked safe, it then gives up and gives a full stack
50backtrace instead. In other words it presumes that the first likely
51looking potential suspect is guilty. Its rules for telling whether
52a call shouldn't generate errors work as follows:
53
54=over 4
55
56=item 1.
57
22dc90ad 58Any call from a package to itself is safe.
a3775ca3 59
60=item 2.
61
62Packages claim that there won't be errors on calls to or from
63packages 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.
f06db76b 68
a3775ca3 69The trust in item 2 is transitive. If A trusts B, and B
70trusts C, then A trusts C. So if you do not override @ISA
71with @CARP_NOT, then this trust relationship is identical to,
72"inherits from".
73
74=item 4.
75
76Any call from an internal Perl module is safe. (Nothing keeps
77user modules from marking themselves as internal to Perl, but
78this practice is discouraged.)
79
80=item 5.
81
82Any call to Carp is safe. (This rule is what keeps it from
af80c6a7 83reporting the error where you call carp/croak/shortmess.)
a3775ca3 84
85=back
9120d252 86
4d935a29 87=head2 Forcing a Stack Trace
88
89As a debugging aid, you can force Carp to treat a croak as a confess
90and a carp as a cluck across I<all> modules. In other words, force a
91detailed stack trace to be given. This can be very helpful when trying
92to understand why, or from where, a warning or error is being generated.
93
f610777f 94This feature is enabled by 'importing' the non-existent symbol
4d935a29 95'verbose'. You would typically enable it by saying
96
97 perl -MCarp=verbose script.pl
98
042e981a 99or by including the string C<MCarp=verbose> in the PERL5OPT
4d935a29 100environment variable.
101
22dc90ad 102Alternately, you can set the global variable C<$Carp::Verbose> to true.
103See the C<GLOBAL VARIABLES> section below.
d2fe67be 104
f06db76b 105=cut
106
4d935a29 107# This package is heavily used. Be small. Be fast. Be good.
a0d0e21e 108
7b8d334a 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
a3775ca3 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
7b8d334a 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
22dc90ad 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
134This variable determines how many call frames are to be skipped when
135reporting where an error occurred on a call to one of C<Carp>'s
136functions. For example:
137
138 $Carp::CarpLevel = 1;
139 sub bar { .... or _error('Wrong input') }
140 sub _error { Carp::carp(@_) }
141
142This would make Carp report the error as coming from C<bar>'s caller,
143rather than from C<_error>'s caller, as it normally would.
144
145Defaults to C<0>.
146
147=head2 $Carp::MaxEvalLen
148
149This variable determines how many characters of a string-eval are to
150be shown in the output. Use a value of C<0> to show all text.
151
152Defaults to C<0>.
153
154=head2 $Carp::MaxArgLen
155
156This variable determines how many characters of each argument to a
157function to print. Use a value of C<0> to show the full length of the
158argument.
159
160Defaults to C<64>.
161
162=head2 $Carp::MaxArgNums
163
164This variable determines how many arguments to each function to show.
165Use a value of C<0> to show all arguments to a function call.
166
167Defaults to C<8>.
168
169=head2 $Carp::Verbose
170
171This variable makes C<Carp> use the C<longmess> function at all times.
172This effectively means that all calls to C<carp> become C<cluck> and
173all calls to C<croak> become C<confess>.
174
175Note, this is analogous to using C<use Carp 'verbose'>.
176
177Defaults to C<0>.
178
179=cut
180
09e96b99 181# disable these by default, so they can live w/o require Carp
a3775ca3 182$CarpInternal{Carp}++;
c3186b65 183$CarpInternal{warnings}++;
09e96b99 184$Internal{Exporter}++;
185$Internal{'Exporter::Heavy'}++;
22dc90ad 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
748a9306 194
a0d0e21e 195require Exporter;
fb73857a 196@ISA = ('Exporter');
a0d0e21e 197@EXPORT = qw(confess croak carp);
af80c6a7 198@EXPORT_OK = qw(cluck verbose longmess shortmess);
199@EXPORT_FAIL = qw(verbose); # hook to enable verbose mode
200
22dc90ad 201=head1 BUGS
202
203The Carp routines don't handle exception objects currently.
204If called with a first argument that is a reference, they simply
205call die() or warn(), as appropriate.
206
207=cut
af80c6a7 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
214sub export_fail {
215 shift;
216 $Verbose = shift if $_[0] eq 'verbose';
217 return @_;
4d935a29 218}
219
a0d0e21e 220
7b8d334a 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
a0d0e21e 227sub longmess {
b27d3831 228 {
229 local $@;
230 # XXX fix require to not clear $@?
231 # don't use require unless we need to (for Safe compartments)
232 require Carp::Heavy unless $INC{"Carp/Heavy.pm"};
233 }
c01c1f0d 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 }
a0d0e21e 243}
244
7b8d334a 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
6ff81951 249# generate that. In verbose mode shortmess() calls longmess() so
7b8d334a 250# you always get a stack trace
251
748a9306 252sub shortmess { # Short-circuit &longmess if called via multiple packages
b27d3831 253 {
254 local $@;
255 # XXX fix require to not clear $@?
256 # don't use require unless we need to (for Safe compartments)
257 require Carp::Heavy unless $INC{"Carp/Heavy.pm"};
258 }
c01c1f0d 259 # Icky backwards compatibility wrapper. :-(
260 my $call_pack = caller();
261 local @CARP_NOT = caller();
262 shortmess_heavy(@_);
a0d0e21e 263}
264
7b8d334a 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
271sub croak { die shortmess @_ }
272sub confess { die longmess @_ }
273sub carp { warn shortmess @_ }
274sub cluck { warn longmess @_ }
a0d0e21e 275
748a9306 2761;