Commit | Line | Data |
---|---|---|
a0d0e21e | 1 | package Carp; |
8c3d9721 | 2 | |
9cb6ed42 | 3 | our $VERSION = '1.08'; |
29ddba3b DM |
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 DM |
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 DM |
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 JH |
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 DM |
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 DM |
31 | sub longmess_jmp { |
32 | local($@, $!); | |
33 | eval { require Carp::Heavy }; | |
34 | return $@ if $@; | |
792941b2 | 35 | goto &longmess_real; |
090656d2 DM |
36 | } |
37 | sub shortmess_jmp { | |
38 | local($@, $!); | |
39 | eval { require Carp::Heavy }; | |
40 | return $@ if $@; | |
792941b2 | 41 | goto &shortmess_real; |
090656d2 | 42 | } |
7b8d334a GS |
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 DM |
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 | ||
0cda2667 DM |
63 | =head1 SYNOPSIS |
64 | ||
65 | use Carp; | |
66 | croak "We're outta here!"; | |
67 | ||
68 | use Carp qw(cluck); | |
69 | cluck "This is how we got here!"; | |
70 | ||
0cda2667 DM |
71 | =head1 DESCRIPTION |
72 | ||
73 | The Carp routines are useful in your own modules because | |
74 | they act like die() or warn(), but with a message which is more | |
75 | likely to be useful to a user of your module. In the case of | |
76 | cluck, confess, and longmess that context is a summary of every | |
d735c2ef BT |
77 | call in the call-stack. For a shorter message you can use C<carp> |
78 | or C<croak> which report the error as being from where your module | |
79 | was called. There is no guarantee that that is where the error | |
80 | was, but it is a good educated guess. | |
0cda2667 DM |
81 | |
82 | You can also alter the way the output and logic of C<Carp> works, by | |
83 | changing some global variables in the C<Carp> namespace. See the | |
84 | section on C<GLOBAL VARIABLES> below. | |
85 | ||
d735c2ef BT |
86 | Here is a more complete description of how c<carp> and c<croak> work. |
87 | What they do is search the call-stack for a function call stack where | |
88 | they have not been told that there shouldn't be an error. If every | |
89 | call is marked safe, they give up and give a full stack backtrace | |
90 | instead. In other words they presume that the first likely looking | |
91 | potential suspect is guilty. Their rules for telling whether | |
0cda2667 DM |
92 | a call shouldn't generate errors work as follows: |
93 | ||
94 | =over 4 | |
95 | ||
96 | =item 1. | |
97 | ||
98 | Any call from a package to itself is safe. | |
99 | ||
100 | =item 2. | |
101 | ||
102 | Packages claim that there won't be errors on calls to or from | |
d735c2ef BT |
103 | packages explicitly marked as safe by inclusion in C<@CARP_NOT>, or |
104 | (if that array is empty) C<@ISA>. The ability to override what | |
0cda2667 DM |
105 | @ISA says is new in 5.8. |
106 | ||
107 | =item 3. | |
108 | ||
109 | The trust in item 2 is transitive. If A trusts B, and B | |
d735c2ef BT |
110 | trusts C, then A trusts C. So if you do not override C<@ISA> |
111 | with C<@CARP_NOT>, then this trust relationship is identical to, | |
0cda2667 DM |
112 | "inherits from". |
113 | ||
114 | =item 4. | |
115 | ||
116 | Any call from an internal Perl module is safe. (Nothing keeps | |
117 | user modules from marking themselves as internal to Perl, but | |
118 | this practice is discouraged.) | |
119 | ||
120 | =item 5. | |
121 | ||
d735c2ef BT |
122 | Any call to Perl's warning system (eg Carp itself) is safe. |
123 | (This rule is what keeps it from reporting the error at the | |
124 | point where you call C<carp> or C<croak>.) | |
125 | ||
126 | =item 6. | |
127 | ||
128 | C<$Carp::CarpLevel> can be set to skip a fixed number of additional | |
129 | call levels. Using this is not recommended because it is very | |
130 | difficult to get it to behave correctly. | |
0cda2667 DM |
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 | ||
0cda2667 DM |
154 | =head2 $Carp::MaxEvalLen |
155 | ||
156 | This variable determines how many characters of a string-eval are to | |
157 | be shown in the output. Use a value of C<0> to show all text. | |
158 | ||
159 | Defaults to C<0>. | |
160 | ||
161 | =head2 $Carp::MaxArgLen | |
162 | ||
163 | This variable determines how many characters of each argument to a | |
164 | function to print. Use a value of C<0> to show the full length of the | |
165 | argument. | |
166 | ||
167 | Defaults to C<64>. | |
168 | ||
169 | =head2 $Carp::MaxArgNums | |
170 | ||
171 | This variable determines how many arguments to each function to show. | |
172 | Use a value of C<0> to show all arguments to a function call. | |
173 | ||
174 | Defaults to C<8>. | |
175 | ||
176 | =head2 $Carp::Verbose | |
177 | ||
d735c2ef BT |
178 | This variable makes C<carp> and C<cluck> generate stack backtraces |
179 | just like C<cluck> and C<confess>. This is how C<use Carp 'verbose'> | |
180 | is implemented internally. | |
181 | ||
182 | Defaults to C<0>. | |
183 | ||
184 | =head2 %Carp::Internal | |
185 | ||
186 | This says what packages are internal to Perl. C<Carp> will never | |
187 | report an error as being from a line in a package that is internal to | |
188 | Perl. For example: | |
189 | ||
190 | $Carp::Internal{ __PACKAGE__ }++; | |
191 | # time passes... | |
192 | sub foo { ... or confess("whatever") }; | |
193 | ||
194 | would give a full stack backtrace starting from the first caller | |
195 | outside of __PACKAGE__. (Unless that package was also internal to | |
196 | Perl.) | |
197 | ||
198 | =head2 %Carp::CarpInternal | |
199 | ||
200 | This says which packages are internal to Perl's warning system. For | |
201 | generating a full stack backtrace this is the same as being internal | |
202 | to Perl, the stack backtrace will not start inside packages that are | |
203 | listed in C<%Carp::CarpInternal>. But it is slightly different for | |
204 | the summary message generated by C<carp> or C<croak>. There errors | |
205 | will not be reported on any lines that are calling packages in | |
206 | C<%Carp::CarpInternal>. | |
207 | ||
208 | For example C<Carp> itself is listed in C<%Carp::CarpInternal>. | |
209 | Therefore the full stack backtrace from C<confess> will not start | |
210 | inside of C<Carp>, and the short message from calling C<croak> is | |
211 | not placed on the line where C<croak> was called. | |
212 | ||
213 | =head2 $Carp::CarpLevel | |
0cda2667 | 214 | |
d735c2ef BT |
215 | This variable determines how many additional call frames are to be |
216 | skipped that would not otherwise be when reporting where an error | |
217 | occurred on a call to one of C<Carp>'s functions. It is fairly easy | |
218 | to count these call frames on calls that generate a full stack | |
219 | backtrace. However it is much harder to do this accounting for calls | |
220 | that generate a short message. Usually people skip too many call | |
221 | frames. If they are lucky they skip enough that C<Carp> goes all of | |
222 | the way through the call stack, realizes that something is wrong, and | |
223 | then generates a full stack backtrace. If they are unlucky then the | |
224 | error is reported from somewhere misleading very high in the call | |
225 | stack. | |
226 | ||
227 | Therefore it is best to avoid C<$Carp::CarpLevel>. Instead use | |
228 | C<@CARP_NOT>, C<%Carp::Internal> and %Carp::CarpInternal>. | |
0cda2667 DM |
229 | |
230 | Defaults to C<0>. | |
231 | ||
0cda2667 DM |
232 | =head1 BUGS |
233 | ||
234 | The Carp routines don't handle exception objects currently. | |
235 | If called with a first argument that is a reference, they simply | |
236 | call die() or warn(), as appropriate. | |
237 |