This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Carp was mostly unusable with Safe because it may require
[perl5.git] / lib / Carp.pm
CommitLineData
a0d0e21e
LW
1package Carp;
2
1798c67d 3our $VERSION = '1.02';
b75c8c73 4
f06db76b
AD
5=head1 NAME
6
4d935a29 7carp - warn of errors (from perspective of caller)
f06db76b 8
4d935a29
TB
9cluck - warn of errors with stack backtrace
10 (not exported by default)
11
12croak - die of errors (from perspective of caller)
f06db76b
AD
13
14confess - die of errors with stack backtrace
15
af80c6a7
JH
16shortmess - return the message that carp and croak produce
17
18longmess - return the message that cluck and confess produce
19
f06db76b
AD
20=head1 SYNOPSIS
21
22 use Carp;
23 croak "We're outta here!";
24
4d935a29
TB
25 use Carp qw(cluck);
26 cluck "This is how we got here!";
27
af80c6a7
JH
28 print FH Carp::shortmess("This will have caller's details added");
29 print FH Carp::longmess("This will have stack backtrace added");
30
f06db76b
AD
31=head1 DESCRIPTION
32
33The Carp routines are useful in your own modules because
a3775ca3
BT
34they act like die() or warn(), but with a message which is more
35likely to be useful to a user of your module. In the case of
af80c6a7
JH
36cluck, confess, and longmess that context is a summary of every
37call in the call-stack. For a shorter message you can use carp,
38croak or shortmess which report the error as being from where
a3775ca3
BT
39your module was called. There is no guarantee that that is where
40the error was, but it is a good educated guess.
41
af80c6a7
JH
42Here is a more complete description of how shortmess works. What
43it does is search the call-stack for a function call stack where
a3775ca3
BT
44it hasn't been told that there shouldn't be an error. If every
45call is marked safe, it then gives up and gives a full stack
46backtrace instead. In other words it presumes that the first likely
47looking potential suspect is guilty. Its rules for telling whether
48a call shouldn't generate errors work as follows:
49
50=over 4
51
52=item 1.
53
54Any call from a package to itself is safe.
55
56=item 2.
57
58Packages claim that there won't be errors on calls to or from
59packages explicitly marked as safe by inclusion in @CARP_NOT, or
60(if that array is empty) @ISA. The ability to override what
61@ISA says is new in 5.8.
62
63=item 3.
f06db76b 64
a3775ca3
BT
65The trust in item 2 is transitive. If A trusts B, and B
66trusts C, then A trusts C. So if you do not override @ISA
67with @CARP_NOT, then this trust relationship is identical to,
68"inherits from".
69
70=item 4.
71
72Any call from an internal Perl module is safe. (Nothing keeps
73user modules from marking themselves as internal to Perl, but
74this practice is discouraged.)
75
76=item 5.
77
78Any call to Carp is safe. (This rule is what keeps it from
af80c6a7 79reporting the error where you call carp/croak/shortmess.)
a3775ca3
BT
80
81=back
9120d252 82
4d935a29
TB
83=head2 Forcing a Stack Trace
84
85As a debugging aid, you can force Carp to treat a croak as a confess
86and a carp as a cluck across I<all> modules. In other words, force a
87detailed stack trace to be given. This can be very helpful when trying
88to understand why, or from where, a warning or error is being generated.
89
f610777f 90This feature is enabled by 'importing' the non-existent symbol
4d935a29
TB
91'verbose'. You would typically enable it by saying
92
93 perl -MCarp=verbose script.pl
94
042e981a 95or by including the string C<MCarp=verbose> in the PERL5OPT
4d935a29
TB
96environment variable.
97
d2fe67be
GS
98=head1 BUGS
99
100The Carp routines don't handle exception objects currently.
101If called with a first argument that is a reference, they simply
102call die() or warn(), as appropriate.
103
f06db76b
AD
104=cut
105
4d935a29 106# This package is heavily used. Be small. Be fast. Be good.
a0d0e21e 107
7b8d334a
GS
108# Comments added by Andy Wardley <abw@kfs.org> 09-Apr-98, based on an
109# _almost_ complete understanding of the package. Corrections and
110# comments are welcome.
111
a3775ca3
BT
112# The members of %Internal are packages that are internal to perl.
113# Carp will not report errors from within these packages if it
114# can. The members of %CarpInternal are internal to Perl's warning
115# system. Carp will not report errors from within these packages
116# either, and will not report calls *to* these packages for carp and
117# croak. They replace $CarpLevel, which is deprecated. The
7b8d334a
GS
118# $Max(EvalLen|(Arg(Len|Nums)) variables are used to specify how the eval
119# text and function arguments should be formatted when printed.
120
a3775ca3 121$CarpInternal{Carp}++;
c3186b65 122$CarpInternal{warnings}++;
748a9306 123$CarpLevel = 0; # How many extra package levels to skip on carp.
a3775ca3
BT
124 # How many calls to skip on confess.
125 # Reconciling these notions is hard, use
126 # %Internal and %CarpInternal instead.
c07a80fd 127$MaxEvalLen = 0; # How much eval '...text...' to show. 0 = all.
55497cff
PP
128$MaxArgLen = 64; # How much of each argument to print. 0 = all.
129$MaxArgNums = 8; # How many arguments to print. 0 = all.
6ff81951 130$Verbose = 0; # If true then make shortmess call longmess instead
748a9306 131
a0d0e21e 132require Exporter;
fb73857a 133@ISA = ('Exporter');
a0d0e21e 134@EXPORT = qw(confess croak carp);
af80c6a7
JH
135@EXPORT_OK = qw(cluck verbose longmess shortmess);
136@EXPORT_FAIL = qw(verbose); # hook to enable verbose mode
137
138
139# if the caller specifies verbose usage ("perl -MCarp=verbose script.pl")
140# then the following method will be called by the Exporter which knows
141# to do this thanks to @EXPORT_FAIL, above. $_[1] will contain the word
142# 'verbose'.
143
144sub export_fail {
145 shift;
146 $Verbose = shift if $_[0] eq 'verbose';
147 return @_;
4d935a29
TB
148}
149
a0d0e21e 150
7b8d334a
GS
151# longmess() crawls all the way up the stack reporting on all the function
152# calls made. The error string, $error, is originally constructed from the
153# arguments passed into longmess() via confess(), cluck() or shortmess().
154# This gets appended with the stack trace messages which are generated for
155# each function call on the stack.
156
a0d0e21e 157sub longmess {
b27d3831
RGS
158 {
159 local $@;
160 # XXX fix require to not clear $@?
161 # don't use require unless we need to (for Safe compartments)
162 require Carp::Heavy unless $INC{"Carp/Heavy.pm"};
163 }
c01c1f0d
BT
164 # Icky backwards compatibility wrapper. :-(
165 my $call_pack = caller();
166 if ($Internal{$call_pack} or $CarpInternal{$call_pack}) {
167 return longmess_heavy(@_);
168 }
169 else {
170 local $CarpLevel = $CarpLevel + 1;
171 return longmess_heavy(@_);
172 }
a0d0e21e
LW
173}
174
7b8d334a
GS
175
176# shortmess() is called by carp() and croak() to skip all the way up to
177# the top-level caller's package and report the error from there. confess()
178# and cluck() generate a full stack trace so they call longmess() to
6ff81951 179# generate that. In verbose mode shortmess() calls longmess() so
7b8d334a
GS
180# you always get a stack trace
181
748a9306 182sub shortmess { # Short-circuit &longmess if called via multiple packages
b27d3831
RGS
183 {
184 local $@;
185 # XXX fix require to not clear $@?
186 # don't use require unless we need to (for Safe compartments)
187 require Carp::Heavy unless $INC{"Carp/Heavy.pm"};
188 }
c01c1f0d
BT
189 # Icky backwards compatibility wrapper. :-(
190 my $call_pack = caller();
191 local @CARP_NOT = caller();
192 shortmess_heavy(@_);
a0d0e21e
LW
193}
194
7b8d334a
GS
195
196# the following four functions call longmess() or shortmess() depending on
197# whether they should generate a full stack trace (confess() and cluck())
198# or simply report the caller's package (croak() and carp()), respectively.
199# confess() and croak() die, carp() and cluck() warn.
200
201sub croak { die shortmess @_ }
202sub confess { die longmess @_ }
203sub carp { warn shortmess @_ }
204sub cluck { warn longmess @_ }
a0d0e21e 205
748a9306 2061;