| 1 | package Carp; |
| 2 | |
| 3 | our $VERSION = '1.01'; |
| 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 | { local $@; require Carp::Heavy; } # XXX fix require to not clear $@? |
| 159 | # Icky backwards compatibility wrapper. :-( |
| 160 | my $call_pack = caller(); |
| 161 | if ($Internal{$call_pack} or $CarpInternal{$call_pack}) { |
| 162 | return longmess_heavy(@_); |
| 163 | } |
| 164 | else { |
| 165 | local $CarpLevel = $CarpLevel + 1; |
| 166 | return longmess_heavy(@_); |
| 167 | } |
| 168 | } |
| 169 | |
| 170 | |
| 171 | # shortmess() is called by carp() and croak() to skip all the way up to |
| 172 | # the top-level caller's package and report the error from there. confess() |
| 173 | # and cluck() generate a full stack trace so they call longmess() to |
| 174 | # generate that. In verbose mode shortmess() calls longmess() so |
| 175 | # you always get a stack trace |
| 176 | |
| 177 | sub shortmess { # Short-circuit &longmess if called via multiple packages |
| 178 | { local $@; require Carp::Heavy; } # XXX fix require to not clear $@? |
| 179 | # Icky backwards compatibility wrapper. :-( |
| 180 | my $call_pack = caller(); |
| 181 | local @CARP_NOT = caller(); |
| 182 | shortmess_heavy(@_); |
| 183 | } |
| 184 | |
| 185 | |
| 186 | # the following four functions call longmess() or shortmess() depending on |
| 187 | # whether they should generate a full stack trace (confess() and cluck()) |
| 188 | # or simply report the caller's package (croak() and carp()), respectively. |
| 189 | # confess() and croak() die, carp() and cluck() warn. |
| 190 | |
| 191 | sub croak { die shortmess @_ } |
| 192 | sub confess { die longmess @_ } |
| 193 | sub carp { warn shortmess @_ } |
| 194 | sub cluck { warn longmess @_ } |
| 195 | |
| 196 | 1; |