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