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