1 | package Carp; |
---|
2 | |
---|
3 | =head1 NAME |
---|
4 | |
---|
5 | carp - warn of errors (from perspective of caller) |
---|
6 | |
---|
7 | cluck - warn of errors with stack backtrace |
---|
8 | (not exported by default) |
---|
9 | |
---|
10 | croak - die of errors (from perspective of caller) |
---|
11 | |
---|
12 | confess - die of errors with stack backtrace |
---|
13 | |
---|
14 | =head1 SYNOPSIS |
---|
15 | |
---|
16 | use Carp; |
---|
17 | croak "We're outta here!"; |
---|
18 | |
---|
19 | use Carp qw(cluck); |
---|
20 | cluck "This is how we got here!"; |
---|
21 | |
---|
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 | |
---|
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 | |
---|
38 | This feature is enabled by 'importing' the non-existent symbol |
---|
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 | |
---|
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 | |
---|
52 | =cut |
---|
53 | |
---|
54 | # This package is heavily used. Be small. Be fast. Be good. |
---|
55 | |
---|
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 | |
---|
65 | $CarpLevel = 0; # How many extra package levels to skip on carp. |
---|
66 | $MaxEvalLen = 0; # How much eval '...text...' to show. 0 = all. |
---|
67 | $MaxArgLen = 64; # How much of each argument to print. 0 = all. |
---|
68 | $MaxArgNums = 8; # How many arguments to print. 0 = all. |
---|
69 | $Verbose = 0; # If true then make shortmess call longmess instead |
---|
70 | |
---|
71 | require Exporter; |
---|
72 | @ISA = ('Exporter'); |
---|
73 | @EXPORT = qw(confess croak carp); |
---|
74 | @EXPORT_OK = qw(cluck verbose); |
---|
75 | @EXPORT_FAIL = qw(verbose); # hook to enable verbose mode |
---|
76 | |
---|
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 | |
---|
83 | sub export_fail { |
---|
84 | shift; |
---|
85 | $Verbose = shift if $_[0] eq 'verbose'; |
---|
86 | return @_; |
---|
87 | } |
---|
88 | |
---|
89 | |
---|
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 | |
---|
96 | sub longmess { |
---|
97 | { local $@; require Carp::Heavy; } # XXX fix require to not clear $@? |
---|
98 | goto &longmess_heavy; |
---|
99 | } |
---|
100 | |
---|
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 |
---|
105 | # generate that. In verbose mode shortmess() calls longmess() so |
---|
106 | # you always get a stack trace |
---|
107 | |
---|
108 | sub shortmess { # Short-circuit &longmess if called via multiple packages |
---|
109 | { local $@; require Carp::Heavy; } # XXX fix require to not clear $@? |
---|
110 | goto &shortmess_heavy; |
---|
111 | } |
---|
112 | |
---|
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 @_ } |
---|
123 | |
---|
124 | 1; |
---|