Commit | Line | Data |
a0d0e21e |
1 | package Carp; |
8c3d9721 |
2 | |
3 | our $VERSION = '1.05'; |
29ddba3b |
4 | # this file is an utra-lightweight stub. The first time a function is |
5 | # called, Carp::Heavy is loaded, and the real short/longmessmess_jmp |
6 | # subs are installed |
b75c8c73 |
7 | |
8c3d9721 |
8 | our $MaxEvalLen = 0; |
9 | our $Verbose = 0; |
10 | our $CarpLevel = 0; |
11 | our $MaxArgLen = 64; # How much of each argument to print. 0 = all. |
12 | our $MaxArgNums = 8; # How many arguments to print. 0 = all. |
748a9306 |
13 | |
a0d0e21e |
14 | require Exporter; |
8c3d9721 |
15 | our @ISA = ('Exporter'); |
16 | our @EXPORT = qw(confess croak carp); |
17 | our @EXPORT_OK = qw(cluck verbose longmess shortmess); |
18 | our @EXPORT_FAIL = qw(verbose); # hook to enable verbose mode |
af80c6a7 |
19 | |
af80c6a7 |
20 | # if the caller specifies verbose usage ("perl -MCarp=verbose script.pl") |
21 | # then the following method will be called by the Exporter which knows |
22 | # to do this thanks to @EXPORT_FAIL, above. $_[1] will contain the word |
23 | # 'verbose'. |
24 | |
29ddba3b |
25 | sub export_fail { shift; $Verbose = shift if $_[0] eq 'verbose'; @_ } |
7b8d334a |
26 | |
29ddba3b |
27 | # fixed hooks for stashes to point to |
28 | sub longmess { goto &longmess_jmp } |
29 | sub shortmess { goto &shortmess_jmp } |
30 | # these two are replaced when Carp::Heavy is loaded |
090656d2 |
31 | sub longmess_jmp { |
32 | local($@, $!); |
33 | eval { require Carp::Heavy }; |
34 | return $@ if $@; |
35 | goto &longmess_jmp; |
36 | } |
37 | sub shortmess_jmp { |
38 | local($@, $!); |
39 | eval { require Carp::Heavy }; |
40 | return $@ if $@; |
41 | goto &shortmess_jmp; |
42 | } |
7b8d334a |
43 | |
44 | sub croak { die shortmess @_ } |
45 | sub confess { die longmess @_ } |
46 | sub carp { warn shortmess @_ } |
47 | sub cluck { warn longmess @_ } |
a0d0e21e |
48 | |
748a9306 |
49 | 1; |
0cda2667 |
50 | __END__ |
51 | |
52 | =head1 NAME |
53 | |
54 | carp - warn of errors (from perspective of caller) |
55 | |
56 | cluck - warn of errors with stack backtrace |
57 | (not exported by default) |
58 | |
59 | croak - die of errors (from perspective of caller) |
60 | |
61 | confess - die of errors with stack backtrace |
62 | |
63 | shortmess - return the message that carp and croak produce |
64 | |
65 | longmess - return the message that cluck and confess produce |
66 | |
67 | =head1 SYNOPSIS |
68 | |
69 | use Carp; |
70 | croak "We're outta here!"; |
71 | |
72 | use Carp qw(cluck); |
73 | cluck "This is how we got here!"; |
74 | |
75 | print FH Carp::shortmess("This will have caller's details added"); |
76 | print FH Carp::longmess("This will have stack backtrace added"); |
77 | |
78 | =head1 DESCRIPTION |
79 | |
80 | The Carp routines are useful in your own modules because |
81 | they act like die() or warn(), but with a message which is more |
82 | likely to be useful to a user of your module. In the case of |
83 | cluck, confess, and longmess that context is a summary of every |
84 | call in the call-stack. For a shorter message you can use carp, |
85 | croak or shortmess which report the error as being from where |
86 | your module was called. There is no guarantee that that is where |
87 | the error was, but it is a good educated guess. |
88 | |
89 | You can also alter the way the output and logic of C<Carp> works, by |
90 | changing some global variables in the C<Carp> namespace. See the |
91 | section on C<GLOBAL VARIABLES> below. |
92 | |
93 | Here is a more complete description of how shortmess works. What |
94 | it does is search the call-stack for a function call stack where |
95 | it hasn't been told that there shouldn't be an error. If every |
96 | call is marked safe, it then gives up and gives a full stack |
97 | backtrace instead. In other words it presumes that the first likely |
98 | looking potential suspect is guilty. Its rules for telling whether |
99 | a call shouldn't generate errors work as follows: |
100 | |
101 | =over 4 |
102 | |
103 | =item 1. |
104 | |
105 | Any call from a package to itself is safe. |
106 | |
107 | =item 2. |
108 | |
109 | Packages claim that there won't be errors on calls to or from |
110 | packages explicitly marked as safe by inclusion in @CARP_NOT, or |
111 | (if that array is empty) @ISA. The ability to override what |
112 | @ISA says is new in 5.8. |
113 | |
114 | =item 3. |
115 | |
116 | The trust in item 2 is transitive. If A trusts B, and B |
117 | trusts C, then A trusts C. So if you do not override @ISA |
118 | with @CARP_NOT, then this trust relationship is identical to, |
119 | "inherits from". |
120 | |
121 | =item 4. |
122 | |
123 | Any call from an internal Perl module is safe. (Nothing keeps |
124 | user modules from marking themselves as internal to Perl, but |
125 | this practice is discouraged.) |
126 | |
127 | =item 5. |
128 | |
129 | Any call to Carp is safe. (This rule is what keeps it from |
130 | reporting the error where you call carp/croak/shortmess.) |
131 | |
132 | =back |
133 | |
134 | =head2 Forcing a Stack Trace |
135 | |
136 | As a debugging aid, you can force Carp to treat a croak as a confess |
137 | and a carp as a cluck across I<all> modules. In other words, force a |
138 | detailed stack trace to be given. This can be very helpful when trying |
139 | to understand why, or from where, a warning or error is being generated. |
140 | |
141 | This feature is enabled by 'importing' the non-existent symbol |
142 | 'verbose'. You would typically enable it by saying |
143 | |
144 | perl -MCarp=verbose script.pl |
145 | |
146 | or by including the string C<MCarp=verbose> in the PERL5OPT |
147 | environment variable. |
148 | |
149 | Alternately, you can set the global variable C<$Carp::Verbose> to true. |
150 | See the C<GLOBAL VARIABLES> section below. |
151 | |
152 | =head1 GLOBAL VARIABLES |
153 | |
154 | =head2 $Carp::CarpLevel |
155 | |
156 | This variable determines how many call frames are to be skipped when |
157 | reporting where an error occurred on a call to one of C<Carp>'s |
158 | functions. For example: |
159 | |
160 | $Carp::CarpLevel = 1; |
161 | sub bar { .... or _error('Wrong input') } |
162 | sub _error { Carp::carp(@_) } |
163 | |
164 | This would make Carp report the error as coming from C<bar>'s caller, |
165 | rather than from C<_error>'s caller, as it normally would. |
166 | |
167 | Defaults to C<0>. |
168 | |
169 | =head2 $Carp::MaxEvalLen |
170 | |
171 | This variable determines how many characters of a string-eval are to |
172 | be shown in the output. Use a value of C<0> to show all text. |
173 | |
174 | Defaults to C<0>. |
175 | |
176 | =head2 $Carp::MaxArgLen |
177 | |
178 | This variable determines how many characters of each argument to a |
179 | function to print. Use a value of C<0> to show the full length of the |
180 | argument. |
181 | |
182 | Defaults to C<64>. |
183 | |
184 | =head2 $Carp::MaxArgNums |
185 | |
186 | This variable determines how many arguments to each function to show. |
187 | Use a value of C<0> to show all arguments to a function call. |
188 | |
189 | Defaults to C<8>. |
190 | |
191 | =head2 $Carp::Verbose |
192 | |
193 | This variable makes C<Carp> use the C<longmess> function at all times. |
194 | This effectively means that all calls to C<carp> become C<cluck> and |
195 | all calls to C<croak> become C<confess>. |
196 | |
197 | Note, this is analogous to using C<use Carp 'verbose'>. |
198 | |
199 | Defaults to C<0>. |
200 | |
0cda2667 |
201 | =head1 BUGS |
202 | |
203 | The Carp routines don't handle exception objects currently. |
204 | If called with a first argument that is a reference, they simply |
205 | call die() or warn(), as appropriate. |
206 | |