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
1 package Carp;
2
3 our $VERSION = '1.02';
4
5 =head1 NAME
6
7 carp    - warn of errors (from perspective of caller)
8
9 cluck   - warn of errors with stack backtrace
10           (not exported by default)
11
12 croak   - die of errors (from perspective of caller)
13
14 confess - die of errors with stack backtrace
15
16 shortmess - return the message that carp and croak produce
17
18 longmess - return the message that cluck and confess produce
19
20 =head1 SYNOPSIS
21
22     use Carp;
23     croak "We're outta here!";
24
25     use Carp qw(cluck);
26     cluck "This is how we got here!";
27
28     print FH Carp::shortmess("This will have caller's details added");
29     print FH Carp::longmess("This will have stack backtrace added");
30
31 =head1 DESCRIPTION
32
33 The Carp routines are useful in your own modules because
34 they act like die() or warn(), but with a message which is more
35 likely to be useful to a user of your module.  In the case of
36 cluck, confess, and longmess that context is a summary of every
37 call in the call-stack.  For a shorter message you can use carp,
38 croak or shortmess which report the error as being from where
39 your module was called.  There is no guarantee that that is where
40 the error was, but it is a good educated guess.
41
42 Here is a more complete description of how shortmess works.  What
43 it does is search the call-stack for a function call stack where
44 it hasn't been told that there shouldn't be an error.  If every
45 call is marked safe, it then gives up and gives a full stack
46 backtrace instead.  In other words it presumes that the first likely
47 looking potential suspect is guilty.  Its rules for telling whether
48 a call shouldn't generate errors work as follows:
49
50 =over 4
51
52 =item 1.
53
54 Any call from a package to itself is safe. 
55
56 =item 2.
57
58 Packages claim that there won't be errors on calls to or from
59 packages 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.
64
65 The trust in item 2 is transitive.  If A trusts B, and B
66 trusts C, then A trusts C.  So if you do not override @ISA
67 with @CARP_NOT, then this trust relationship is identical to,
68 "inherits from".
69
70 =item 4.
71
72 Any call from an internal Perl module is safe.  (Nothing keeps
73 user modules from marking themselves as internal to Perl, but
74 this practice is discouraged.)
75
76 =item 5.
77
78 Any call to Carp is safe.  (This rule is what keeps it from
79 reporting the error where you call carp/croak/shortmess.)
80
81 =back
82
83 =head2 Forcing a Stack Trace
84
85 As a debugging aid, you can force Carp to treat a croak as a confess
86 and a carp as a cluck across I<all> modules. In other words, force a
87 detailed stack trace to be given.  This can be very helpful when trying
88 to understand why, or from where, a warning or error is being generated.
89
90 This feature is enabled by 'importing' the non-existent symbol
91 'verbose'. You would typically enable it by saying
92
93     perl -MCarp=verbose script.pl
94
95 or by including the string C<MCarp=verbose> in the PERL5OPT
96 environment variable.
97
98 =head1 BUGS
99
100 The Carp routines don't handle exception objects currently.
101 If called with a first argument that is a reference, they simply
102 call die() or warn(), as appropriate.
103
104 =cut
105
106 # This package is heavily used. Be small. Be fast. Be good.
107
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
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
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
121 $CarpInternal{Carp}++;
122 $CarpInternal{warnings}++;
123 $CarpLevel = 0;         # How many extra package levels to skip on carp.
124                         # How many calls to skip on confess.
125                         # Reconciling these notions is hard, use
126                         # %Internal and %CarpInternal instead.
127 $MaxEvalLen = 0;        # How much eval '...text...' to show. 0 = all.
128 $MaxArgLen = 64;        # How much of each argument to print. 0 = all.
129 $MaxArgNums = 8;        # How many arguments to print. 0 = all.
130 $Verbose = 0;           # If true then make shortmess call longmess instead
131
132 require Exporter;
133 @ISA = ('Exporter');
134 @EXPORT = qw(confess croak carp);
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
144 sub export_fail {
145     shift;
146     $Verbose = shift if $_[0] eq 'verbose';
147     return @_;
148 }
149
150
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
157 sub longmess {
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     }
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     }
173 }
174
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
179 # generate that.  In verbose mode shortmess() calls longmess() so
180 # you always get a stack trace
181
182 sub shortmess { # Short-circuit &longmess if called via multiple packages
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     }
189     # Icky backwards compatibility wrapper. :-(
190     my $call_pack = caller();
191     local @CARP_NOT = caller();
192     shortmess_heavy(@_);
193 }
194
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
201 sub croak   { die  shortmess @_ }
202 sub confess { die  longmess  @_ }
203 sub carp    { warn shortmess @_ }
204 sub cluck   { warn longmess  @_ }
205
206 1;