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