This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add a header for DJGPP with the function prototypes.
[perl5.git] / lib / Carp.pm
CommitLineData
a0d0e21e
LW
1package Carp;
2
a3775ca3 3our $VERSION = '1.01';
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
a3775ca3
BT
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
9120d252
MG
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
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
39your module was called. There is no guarantee that that is where
40the error was, but it is a good educated guess.
41
42Here is a more complete description of how shortmess works. What
43it does is search the call-stack for a function call stack where
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
79reporting the error where you call carp/croak/shortmess.)
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}++;
748a9306 122$CarpLevel = 0; # How many extra package levels to skip on carp.
a3775ca3
BT
123 # How many calls to skip on confess.
124 # Reconciling these notions is hard, use
125 # %Internal and %CarpInternal instead.
c07a80fd 126$MaxEvalLen = 0; # How much eval '...text...' to show. 0 = all.
55497cff
PP
127$MaxArgLen = 64; # How much of each argument to print. 0 = all.
128$MaxArgNums = 8; # How many arguments to print. 0 = all.
6ff81951 129$Verbose = 0; # If true then make shortmess call longmess instead
748a9306 130
a0d0e21e 131require Exporter;
fb73857a 132@ISA = ('Exporter');
a0d0e21e 133@EXPORT = qw(confess croak carp);
f43adeb5 134@EXPORT_OK = qw(cluck verbose longmess shortmess);
4d935a29
TB
135@EXPORT_FAIL = qw(verbose); # hook to enable verbose mode
136
7b8d334a
GS
137
138# if the caller specifies verbose usage ("perl -MCarp=verbose script.pl")
139# then the following method will be called by the Exporter which knows
140# to do this thanks to @EXPORT_FAIL, above. $_[1] will contain the word
141# 'verbose'.
142
4d935a29
TB
143sub export_fail {
144 shift;
6ff81951 145 $Verbose = shift if $_[0] eq 'verbose';
4d935a29
TB
146 return @_;
147}
148
a0d0e21e 149
7b8d334a
GS
150# longmess() crawls all the way up the stack reporting on all the function
151# calls made. The error string, $error, is originally constructed from the
152# arguments passed into longmess() via confess(), cluck() or shortmess().
153# This gets appended with the stack trace messages which are generated for
154# each function call on the stack.
155
a0d0e21e 156sub longmess {
0bcd2fea 157 { local $@; require Carp::Heavy; } # XXX fix require to not clear $@?
3b5ca523 158 goto &longmess_heavy;
a0d0e21e
LW
159}
160
7b8d334a
GS
161
162# shortmess() is called by carp() and croak() to skip all the way up to
163# the top-level caller's package and report the error from there. confess()
164# and cluck() generate a full stack trace so they call longmess() to
6ff81951 165# generate that. In verbose mode shortmess() calls longmess() so
7b8d334a
GS
166# you always get a stack trace
167
748a9306 168sub shortmess { # Short-circuit &longmess if called via multiple packages
0bcd2fea 169 { local $@; require Carp::Heavy; } # XXX fix require to not clear $@?
3b5ca523 170 goto &shortmess_heavy;
a0d0e21e
LW
171}
172
7b8d334a
GS
173
174# the following four functions call longmess() or shortmess() depending on
175# whether they should generate a full stack trace (confess() and cluck())
176# or simply report the caller's package (croak() and carp()), respectively.
177# confess() and croak() die, carp() and cluck() warn.
178
179sub croak { die shortmess @_ }
180sub confess { die longmess @_ }
181sub carp { warn shortmess @_ }
182sub cluck { warn longmess @_ }
a0d0e21e 183
748a9306 1841;