Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | package Carp; |
2 | ||
67c7b98e | 3 | our $VERSION = '1.03'; |
b75c8c73 | 4 | |
f06db76b AD |
5 | =head1 NAME |
6 | ||
4d935a29 | 7 | carp - warn of errors (from perspective of caller) |
f06db76b | 8 | |
4d935a29 TB |
9 | cluck - warn of errors with stack backtrace |
10 | (not exported by default) | |
11 | ||
12 | croak - die of errors (from perspective of caller) | |
f06db76b AD |
13 | |
14 | confess - die of errors with stack backtrace | |
15 | ||
af80c6a7 JH |
16 | shortmess - return the message that carp and croak produce |
17 | ||
18 | longmess - return the message that cluck and confess produce | |
19 | ||
f06db76b AD |
20 | =head1 SYNOPSIS |
21 | ||
22 | use Carp; | |
23 | croak "We're outta here!"; | |
24 | ||
4d935a29 TB |
25 | use Carp qw(cluck); |
26 | cluck "This is how we got here!"; | |
27 | ||
af80c6a7 JH |
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 AD |
31 | =head1 DESCRIPTION |
32 | ||
33 | The Carp routines are useful in your own modules because | |
a3775ca3 BT |
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 | |
af80c6a7 JH |
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 | |
a3775ca3 BT |
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 | ||
7830c9a4 NC |
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 | ||
af80c6a7 JH |
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 | |
a3775ca3 BT |
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 | ||
7830c9a4 | 58 | Any call from a package to itself is safe. |
a3775ca3 BT |
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. | |
f06db76b | 68 | |
a3775ca3 BT |
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 | |
af80c6a7 | 83 | reporting the error where you call carp/croak/shortmess.) |
a3775ca3 BT |
84 | |
85 | =back | |
9120d252 | 86 | |
4d935a29 TB |
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 | ||
f610777f | 94 | This feature is enabled by 'importing' the non-existent symbol |
4d935a29 TB |
95 | 'verbose'. You would typically enable it by saying |
96 | ||
97 | perl -MCarp=verbose script.pl | |
98 | ||
042e981a | 99 | or by including the string C<MCarp=verbose> in the PERL5OPT |
4d935a29 TB |
100 | environment variable. |
101 | ||
7830c9a4 NC |
102 | Alternately, you can set the global variable C<$Carp::Verbose> to true. |
103 | See the C<GLOBAL VARIABLES> section below. | |
d2fe67be | 104 | |
f06db76b AD |
105 | =cut |
106 | ||
4d935a29 | 107 | # This package is heavily used. Be small. Be fast. Be good. |
a0d0e21e | 108 | |
7b8d334a GS |
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 BT |
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 GS |
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 | ||
7830c9a4 NC |
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 | ||
a3775ca3 | 182 | $CarpInternal{Carp}++; |
c3186b65 | 183 | $CarpInternal{warnings}++; |
7830c9a4 NC |
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 | |
748a9306 | 192 | |
a0d0e21e | 193 | require Exporter; |
fb73857a | 194 | @ISA = ('Exporter'); |
a0d0e21e | 195 | @EXPORT = qw(confess croak carp); |
af80c6a7 JH |
196 | @EXPORT_OK = qw(cluck verbose longmess shortmess); |
197 | @EXPORT_FAIL = qw(verbose); # hook to enable verbose mode | |
198 | ||
7830c9a4 NC |
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 | |
af80c6a7 JH |
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 @_; | |
4d935a29 TB |
216 | } |
217 | ||
a0d0e21e | 218 | |
7b8d334a GS |
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 | ||
a0d0e21e | 225 | sub longmess { |
ab91823c | 226 | { |
d43b9e2d JD |
227 | local($@, $!); |
228 | # XXX fix require to not clear $@ or $!? | |
ab91823c NC |
229 | # don't use require unless we need to (for Safe compartments) |
230 | require Carp::Heavy unless $INC{"Carp/Heavy.pm"}; | |
231 | } | |
c01c1f0d BT |
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 | } | |
a0d0e21e LW |
241 | } |
242 | ||
7b8d334a GS |
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 | |
6ff81951 | 247 | # generate that. In verbose mode shortmess() calls longmess() so |
7b8d334a GS |
248 | # you always get a stack trace |
249 | ||
748a9306 | 250 | sub shortmess { # Short-circuit &longmess if called via multiple packages |
ab91823c | 251 | { |
d43b9e2d JD |
252 | local($@, $!); |
253 | # XXX fix require to not clear $@ or $!? | |
ab91823c NC |
254 | # don't use require unless we need to (for Safe compartments) |
255 | require Carp::Heavy unless $INC{"Carp/Heavy.pm"}; | |
256 | } | |
c01c1f0d BT |
257 | # Icky backwards compatibility wrapper. :-( |
258 | my $call_pack = caller(); | |
259 | local @CARP_NOT = caller(); | |
260 | shortmess_heavy(@_); | |
a0d0e21e LW |
261 | } |
262 | ||
7b8d334a GS |
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 @_ } | |
a0d0e21e | 273 | |
748a9306 | 274 | 1; |