Commit | Line | Data |
a0d0e21e |
1 | package Carp; |
2 | |
b75c8c73 |
3 | our $VERSION = '1.00'; |
4 | |
f06db76b |
5 | =head1 NAME |
6 | |
4d935a29 |
7 | carp - warn of errors (from perspective of caller) |
f06db76b |
8 | |
4d935a29 |
9 | cluck - warn of errors with stack backtrace |
10 | (not exported by default) |
11 | |
12 | croak - die of errors (from perspective of caller) |
f06db76b |
13 | |
14 | confess - die of errors with stack backtrace |
15 | |
16 | =head1 SYNOPSIS |
17 | |
18 | use Carp; |
19 | croak "We're outta here!"; |
20 | |
4d935a29 |
21 | use Carp qw(cluck); |
22 | cluck "This is how we got here!"; |
23 | |
f06db76b |
24 | =head1 DESCRIPTION |
25 | |
26 | The Carp routines are useful in your own modules because |
27 | they act like die() or warn(), but report where the error |
28 | was in the code they were called from. Thus if you have a |
29 | routine Foo() that has a carp() in it, then the carp() |
30 | will report the error as occurring where Foo() was called, |
31 | not where carp() was called. |
32 | |
4d935a29 |
33 | =head2 Forcing a Stack Trace |
34 | |
35 | As a debugging aid, you can force Carp to treat a croak as a confess |
36 | and a carp as a cluck across I<all> modules. In other words, force a |
37 | detailed stack trace to be given. This can be very helpful when trying |
38 | to understand why, or from where, a warning or error is being generated. |
39 | |
f610777f |
40 | This feature is enabled by 'importing' the non-existent symbol |
4d935a29 |
41 | 'verbose'. You would typically enable it by saying |
42 | |
43 | perl -MCarp=verbose script.pl |
44 | |
45 | or by including the string C<MCarp=verbose> in the L<PERL5OPT> |
46 | environment variable. |
47 | |
d2fe67be |
48 | =head1 BUGS |
49 | |
50 | The Carp routines don't handle exception objects currently. |
51 | If called with a first argument that is a reference, they simply |
52 | call die() or warn(), as appropriate. |
53 | |
f43adeb5 |
54 | However, rather than duplicating this effort in your own exception |
55 | object, you can access the caller information that croak() would supply |
56 | as shortmess(), and the full stack trace that confess() would generate |
57 | as longmess() (Neither of these are exported by default.) |
58 | |
f06db76b |
59 | =cut |
60 | |
4d935a29 |
61 | # This package is heavily used. Be small. Be fast. Be good. |
a0d0e21e |
62 | |
7b8d334a |
63 | # Comments added by Andy Wardley <abw@kfs.org> 09-Apr-98, based on an |
64 | # _almost_ complete understanding of the package. Corrections and |
65 | # comments are welcome. |
66 | |
67 | # The $CarpLevel variable can be set to "strip off" extra caller levels for |
68 | # those times when Carp calls are buried inside other functions. The |
69 | # $Max(EvalLen|(Arg(Len|Nums)) variables are used to specify how the eval |
70 | # text and function arguments should be formatted when printed. |
71 | |
748a9306 |
72 | $CarpLevel = 0; # How many extra package levels to skip on carp. |
c07a80fd |
73 | $MaxEvalLen = 0; # How much eval '...text...' to show. 0 = all. |
55497cff |
74 | $MaxArgLen = 64; # How much of each argument to print. 0 = all. |
75 | $MaxArgNums = 8; # How many arguments to print. 0 = all. |
6ff81951 |
76 | $Verbose = 0; # If true then make shortmess call longmess instead |
748a9306 |
77 | |
66a4a569 |
78 | $CarpInternal{Carp}++; |
79 | |
a0d0e21e |
80 | require Exporter; |
fb73857a |
81 | @ISA = ('Exporter'); |
a0d0e21e |
82 | @EXPORT = qw(confess croak carp); |
f43adeb5 |
83 | @EXPORT_OK = qw(cluck verbose longmess shortmess); |
4d935a29 |
84 | @EXPORT_FAIL = qw(verbose); # hook to enable verbose mode |
85 | |
7b8d334a |
86 | |
87 | # if the caller specifies verbose usage ("perl -MCarp=verbose script.pl") |
88 | # then the following method will be called by the Exporter which knows |
89 | # to do this thanks to @EXPORT_FAIL, above. $_[1] will contain the word |
90 | # 'verbose'. |
91 | |
4d935a29 |
92 | sub export_fail { |
93 | shift; |
6ff81951 |
94 | $Verbose = shift if $_[0] eq 'verbose'; |
4d935a29 |
95 | return @_; |
96 | } |
97 | |
a0d0e21e |
98 | |
7b8d334a |
99 | # longmess() crawls all the way up the stack reporting on all the function |
100 | # calls made. The error string, $error, is originally constructed from the |
101 | # arguments passed into longmess() via confess(), cluck() or shortmess(). |
102 | # This gets appended with the stack trace messages which are generated for |
103 | # each function call on the stack. |
104 | |
a0d0e21e |
105 | sub longmess { |
0bcd2fea |
106 | { local $@; require Carp::Heavy; } # XXX fix require to not clear $@? |
3b5ca523 |
107 | goto &longmess_heavy; |
a0d0e21e |
108 | } |
109 | |
7b8d334a |
110 | |
111 | # shortmess() is called by carp() and croak() to skip all the way up to |
112 | # the top-level caller's package and report the error from there. confess() |
113 | # and cluck() generate a full stack trace so they call longmess() to |
6ff81951 |
114 | # generate that. In verbose mode shortmess() calls longmess() so |
7b8d334a |
115 | # you always get a stack trace |
116 | |
748a9306 |
117 | sub shortmess { # Short-circuit &longmess if called via multiple packages |
0bcd2fea |
118 | { local $@; require Carp::Heavy; } # XXX fix require to not clear $@? |
3b5ca523 |
119 | goto &shortmess_heavy; |
a0d0e21e |
120 | } |
121 | |
7b8d334a |
122 | |
123 | # the following four functions call longmess() or shortmess() depending on |
124 | # whether they should generate a full stack trace (confess() and cluck()) |
125 | # or simply report the caller's package (croak() and carp()), respectively. |
126 | # confess() and croak() die, carp() and cluck() warn. |
127 | |
128 | sub croak { die shortmess @_ } |
129 | sub confess { die longmess @_ } |
130 | sub carp { warn shortmess @_ } |
131 | sub cluck { warn longmess @_ } |
a0d0e21e |
132 | |
748a9306 |
133 | 1; |