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