Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | package Carp; |
2 | ||
3 | our $VERSION = '1.01'; | |
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 | Here is a more complete description of how shortmess works. What | |
43 | it does is search the call-stack for a function call stack where | |
44 | it hasn't been told that there shouldn't be an error. If every | |
45 | call is marked safe, it then gives up and gives a full stack | |
46 | backtrace instead. In other words it presumes that the first likely | |
47 | looking potential suspect is guilty. Its rules for telling whether | |
48 | a call shouldn't generate errors work as follows: | |
49 | ||
50 | =over 4 | |
51 | ||
52 | =item 1. | |
53 | ||
54 | Any call from a package to itself is safe. | |
55 | ||
56 | =item 2. | |
57 | ||
58 | Packages claim that there won't be errors on calls to or from | |
59 | packages 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. | |
64 | ||
65 | The trust in item 2 is transitive. If A trusts B, and B | |
66 | trusts C, then A trusts C. So if you do not override @ISA | |
67 | with @CARP_NOT, then this trust relationship is identical to, | |
68 | "inherits from". | |
69 | ||
70 | =item 4. | |
71 | ||
72 | Any call from an internal Perl module is safe. (Nothing keeps | |
73 | user modules from marking themselves as internal to Perl, but | |
74 | this practice is discouraged.) | |
75 | ||
76 | =item 5. | |
77 | ||
78 | Any call to Carp is safe. (This rule is what keeps it from | |
79 | reporting the error where you call carp/croak/shortmess.) | |
80 | ||
81 | =back | |
82 | ||
83 | =head2 Forcing a Stack Trace | |
84 | ||
85 | As a debugging aid, you can force Carp to treat a croak as a confess | |
86 | and a carp as a cluck across I<all> modules. In other words, force a | |
87 | detailed stack trace to be given. This can be very helpful when trying | |
88 | to understand why, or from where, a warning or error is being generated. | |
89 | ||
90 | This feature is enabled by 'importing' the non-existent symbol | |
91 | 'verbose'. You would typically enable it by saying | |
92 | ||
93 | perl -MCarp=verbose script.pl | |
94 | ||
95 | or by including the string C<MCarp=verbose> in the PERL5OPT | |
96 | environment variable. | |
97 | ||
98 | =head1 BUGS | |
99 | ||
100 | The Carp routines don't handle exception objects currently. | |
101 | If called with a first argument that is a reference, they simply | |
102 | call die() or warn(), as appropriate. | |
103 | ||
104 | =cut | |
105 | ||
106 | # This package is heavily used. Be small. Be fast. Be good. | |
107 | ||
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 | ||
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 | |
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 | ||
121 | $CarpInternal{Carp}++; | |
122 | $CarpInternal{warnings}++; | |
123 | $CarpLevel = 0; # How many extra package levels to skip on carp. | |
124 | # How many calls to skip on confess. | |
125 | # Reconciling these notions is hard, use | |
126 | # %Internal and %CarpInternal instead. | |
127 | $MaxEvalLen = 0; # How much eval '...text...' to show. 0 = all. | |
128 | $MaxArgLen = 64; # How much of each argument to print. 0 = all. | |
129 | $MaxArgNums = 8; # How many arguments to print. 0 = all. | |
130 | $Verbose = 0; # If true then make shortmess call longmess instead | |
131 | ||
132 | require Exporter; | |
133 | @ISA = ('Exporter'); | |
134 | @EXPORT = qw(confess croak carp); | |
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 | ||
144 | sub export_fail { | |
145 | shift; | |
146 | $Verbose = shift if $_[0] eq 'verbose'; | |
147 | return @_; | |
148 | } | |
149 | ||
150 | ||
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 | ||
157 | sub longmess { | |
158 | { local $@; require Carp::Heavy; } # XXX fix require to not clear $@? | |
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 | } | |
168 | } | |
169 | ||
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 | |
174 | # generate that. In verbose mode shortmess() calls longmess() so | |
175 | # you always get a stack trace | |
176 | ||
177 | sub shortmess { # Short-circuit &longmess if called via multiple packages | |
178 | { local $@; require Carp::Heavy; } # XXX fix require to not clear $@? | |
179 | # Icky backwards compatibility wrapper. :-( | |
180 | my $call_pack = caller(); | |
181 | local @CARP_NOT = caller(); | |
182 | shortmess_heavy(@_); | |
183 | } | |
184 | ||
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 | ||
191 | sub croak { die shortmess @_ } | |
192 | sub confess { die longmess @_ } | |
193 | sub carp { warn shortmess @_ } | |
194 | sub cluck { warn longmess @_ } | |
195 | ||
196 | 1; |