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