1*0Sstevel@tonic-gatepackage Carp; 2*0Sstevel@tonic-gate 3*0Sstevel@tonic-gateour $VERSION = '1.02'; 4*0Sstevel@tonic-gate 5*0Sstevel@tonic-gate=head1 NAME 6*0Sstevel@tonic-gate 7*0Sstevel@tonic-gatecarp - warn of errors (from perspective of caller) 8*0Sstevel@tonic-gate 9*0Sstevel@tonic-gatecluck - warn of errors with stack backtrace 10*0Sstevel@tonic-gate (not exported by default) 11*0Sstevel@tonic-gate 12*0Sstevel@tonic-gatecroak - die of errors (from perspective of caller) 13*0Sstevel@tonic-gate 14*0Sstevel@tonic-gateconfess - die of errors with stack backtrace 15*0Sstevel@tonic-gate 16*0Sstevel@tonic-gateshortmess - return the message that carp and croak produce 17*0Sstevel@tonic-gate 18*0Sstevel@tonic-gatelongmess - return the message that cluck and confess produce 19*0Sstevel@tonic-gate 20*0Sstevel@tonic-gate=head1 SYNOPSIS 21*0Sstevel@tonic-gate 22*0Sstevel@tonic-gate use Carp; 23*0Sstevel@tonic-gate croak "We're outta here!"; 24*0Sstevel@tonic-gate 25*0Sstevel@tonic-gate use Carp qw(cluck); 26*0Sstevel@tonic-gate cluck "This is how we got here!"; 27*0Sstevel@tonic-gate 28*0Sstevel@tonic-gate print FH Carp::shortmess("This will have caller's details added"); 29*0Sstevel@tonic-gate print FH Carp::longmess("This will have stack backtrace added"); 30*0Sstevel@tonic-gate 31*0Sstevel@tonic-gate=head1 DESCRIPTION 32*0Sstevel@tonic-gate 33*0Sstevel@tonic-gateThe Carp routines are useful in your own modules because 34*0Sstevel@tonic-gatethey act like die() or warn(), but with a message which is more 35*0Sstevel@tonic-gatelikely to be useful to a user of your module. In the case of 36*0Sstevel@tonic-gatecluck, confess, and longmess that context is a summary of every 37*0Sstevel@tonic-gatecall in the call-stack. For a shorter message you can use carp, 38*0Sstevel@tonic-gatecroak or shortmess which report the error as being from where 39*0Sstevel@tonic-gateyour module was called. There is no guarantee that that is where 40*0Sstevel@tonic-gatethe error was, but it is a good educated guess. 41*0Sstevel@tonic-gate 42*0Sstevel@tonic-gateHere is a more complete description of how shortmess works. What 43*0Sstevel@tonic-gateit does is search the call-stack for a function call stack where 44*0Sstevel@tonic-gateit hasn't been told that there shouldn't be an error. If every 45*0Sstevel@tonic-gatecall is marked safe, it then gives up and gives a full stack 46*0Sstevel@tonic-gatebacktrace instead. In other words it presumes that the first likely 47*0Sstevel@tonic-gatelooking potential suspect is guilty. Its rules for telling whether 48*0Sstevel@tonic-gatea call shouldn't generate errors work as follows: 49*0Sstevel@tonic-gate 50*0Sstevel@tonic-gate=over 4 51*0Sstevel@tonic-gate 52*0Sstevel@tonic-gate=item 1. 53*0Sstevel@tonic-gate 54*0Sstevel@tonic-gateAny call from a package to itself is safe. 55*0Sstevel@tonic-gate 56*0Sstevel@tonic-gate=item 2. 57*0Sstevel@tonic-gate 58*0Sstevel@tonic-gatePackages claim that there won't be errors on calls to or from 59*0Sstevel@tonic-gatepackages explicitly marked as safe by inclusion in @CARP_NOT, or 60*0Sstevel@tonic-gate(if that array is empty) @ISA. The ability to override what 61*0Sstevel@tonic-gate@ISA says is new in 5.8. 62*0Sstevel@tonic-gate 63*0Sstevel@tonic-gate=item 3. 64*0Sstevel@tonic-gate 65*0Sstevel@tonic-gateThe trust in item 2 is transitive. If A trusts B, and B 66*0Sstevel@tonic-gatetrusts C, then A trusts C. So if you do not override @ISA 67*0Sstevel@tonic-gatewith @CARP_NOT, then this trust relationship is identical to, 68*0Sstevel@tonic-gate"inherits from". 69*0Sstevel@tonic-gate 70*0Sstevel@tonic-gate=item 4. 71*0Sstevel@tonic-gate 72*0Sstevel@tonic-gateAny call from an internal Perl module is safe. (Nothing keeps 73*0Sstevel@tonic-gateuser modules from marking themselves as internal to Perl, but 74*0Sstevel@tonic-gatethis practice is discouraged.) 75*0Sstevel@tonic-gate 76*0Sstevel@tonic-gate=item 5. 77*0Sstevel@tonic-gate 78*0Sstevel@tonic-gateAny call to Carp is safe. (This rule is what keeps it from 79*0Sstevel@tonic-gatereporting the error where you call carp/croak/shortmess.) 80*0Sstevel@tonic-gate 81*0Sstevel@tonic-gate=back 82*0Sstevel@tonic-gate 83*0Sstevel@tonic-gate=head2 Forcing a Stack Trace 84*0Sstevel@tonic-gate 85*0Sstevel@tonic-gateAs a debugging aid, you can force Carp to treat a croak as a confess 86*0Sstevel@tonic-gateand a carp as a cluck across I<all> modules. In other words, force a 87*0Sstevel@tonic-gatedetailed stack trace to be given. This can be very helpful when trying 88*0Sstevel@tonic-gateto understand why, or from where, a warning or error is being generated. 89*0Sstevel@tonic-gate 90*0Sstevel@tonic-gateThis feature is enabled by 'importing' the non-existent symbol 91*0Sstevel@tonic-gate'verbose'. You would typically enable it by saying 92*0Sstevel@tonic-gate 93*0Sstevel@tonic-gate perl -MCarp=verbose script.pl 94*0Sstevel@tonic-gate 95*0Sstevel@tonic-gateor by including the string C<MCarp=verbose> in the PERL5OPT 96*0Sstevel@tonic-gateenvironment variable. 97*0Sstevel@tonic-gate 98*0Sstevel@tonic-gate=head1 BUGS 99*0Sstevel@tonic-gate 100*0Sstevel@tonic-gateThe Carp routines don't handle exception objects currently. 101*0Sstevel@tonic-gateIf called with a first argument that is a reference, they simply 102*0Sstevel@tonic-gatecall die() or warn(), as appropriate. 103*0Sstevel@tonic-gate 104*0Sstevel@tonic-gate=cut 105*0Sstevel@tonic-gate 106*0Sstevel@tonic-gate# This package is heavily used. Be small. Be fast. Be good. 107*0Sstevel@tonic-gate 108*0Sstevel@tonic-gate# Comments added by Andy Wardley <abw@kfs.org> 09-Apr-98, based on an 109*0Sstevel@tonic-gate# _almost_ complete understanding of the package. Corrections and 110*0Sstevel@tonic-gate# comments are welcome. 111*0Sstevel@tonic-gate 112*0Sstevel@tonic-gate# The members of %Internal are packages that are internal to perl. 113*0Sstevel@tonic-gate# Carp will not report errors from within these packages if it 114*0Sstevel@tonic-gate# can. The members of %CarpInternal are internal to Perl's warning 115*0Sstevel@tonic-gate# system. Carp will not report errors from within these packages 116*0Sstevel@tonic-gate# either, and will not report calls *to* these packages for carp and 117*0Sstevel@tonic-gate# croak. They replace $CarpLevel, which is deprecated. The 118*0Sstevel@tonic-gate# $Max(EvalLen|(Arg(Len|Nums)) variables are used to specify how the eval 119*0Sstevel@tonic-gate# text and function arguments should be formatted when printed. 120*0Sstevel@tonic-gate 121*0Sstevel@tonic-gate$CarpInternal{Carp}++; 122*0Sstevel@tonic-gate$CarpInternal{warnings}++; 123*0Sstevel@tonic-gate$CarpLevel = 0; # How many extra package levels to skip on carp. 124*0Sstevel@tonic-gate # How many calls to skip on confess. 125*0Sstevel@tonic-gate # Reconciling these notions is hard, use 126*0Sstevel@tonic-gate # %Internal and %CarpInternal instead. 127*0Sstevel@tonic-gate$MaxEvalLen = 0; # How much eval '...text...' to show. 0 = all. 128*0Sstevel@tonic-gate$MaxArgLen = 64; # How much of each argument to print. 0 = all. 129*0Sstevel@tonic-gate$MaxArgNums = 8; # How many arguments to print. 0 = all. 130*0Sstevel@tonic-gate$Verbose = 0; # If true then make shortmess call longmess instead 131*0Sstevel@tonic-gate 132*0Sstevel@tonic-gaterequire Exporter; 133*0Sstevel@tonic-gate@ISA = ('Exporter'); 134*0Sstevel@tonic-gate@EXPORT = qw(confess croak carp); 135*0Sstevel@tonic-gate@EXPORT_OK = qw(cluck verbose longmess shortmess); 136*0Sstevel@tonic-gate@EXPORT_FAIL = qw(verbose); # hook to enable verbose mode 137*0Sstevel@tonic-gate 138*0Sstevel@tonic-gate 139*0Sstevel@tonic-gate# if the caller specifies verbose usage ("perl -MCarp=verbose script.pl") 140*0Sstevel@tonic-gate# then the following method will be called by the Exporter which knows 141*0Sstevel@tonic-gate# to do this thanks to @EXPORT_FAIL, above. $_[1] will contain the word 142*0Sstevel@tonic-gate# 'verbose'. 143*0Sstevel@tonic-gate 144*0Sstevel@tonic-gatesub export_fail { 145*0Sstevel@tonic-gate shift; 146*0Sstevel@tonic-gate $Verbose = shift if $_[0] eq 'verbose'; 147*0Sstevel@tonic-gate return @_; 148*0Sstevel@tonic-gate} 149*0Sstevel@tonic-gate 150*0Sstevel@tonic-gate 151*0Sstevel@tonic-gate# longmess() crawls all the way up the stack reporting on all the function 152*0Sstevel@tonic-gate# calls made. The error string, $error, is originally constructed from the 153*0Sstevel@tonic-gate# arguments passed into longmess() via confess(), cluck() or shortmess(). 154*0Sstevel@tonic-gate# This gets appended with the stack trace messages which are generated for 155*0Sstevel@tonic-gate# each function call on the stack. 156*0Sstevel@tonic-gate 157*0Sstevel@tonic-gatesub longmess { 158*0Sstevel@tonic-gate { local $@; require Carp::Heavy; } # XXX fix require to not clear $@? 159*0Sstevel@tonic-gate # Icky backwards compatibility wrapper. :-( 160*0Sstevel@tonic-gate my $call_pack = caller(); 161*0Sstevel@tonic-gate if ($Internal{$call_pack} or $CarpInternal{$call_pack}) { 162*0Sstevel@tonic-gate return longmess_heavy(@_); 163*0Sstevel@tonic-gate } 164*0Sstevel@tonic-gate else { 165*0Sstevel@tonic-gate local $CarpLevel = $CarpLevel + 1; 166*0Sstevel@tonic-gate return longmess_heavy(@_); 167*0Sstevel@tonic-gate } 168*0Sstevel@tonic-gate} 169*0Sstevel@tonic-gate 170*0Sstevel@tonic-gate 171*0Sstevel@tonic-gate# shortmess() is called by carp() and croak() to skip all the way up to 172*0Sstevel@tonic-gate# the top-level caller's package and report the error from there. confess() 173*0Sstevel@tonic-gate# and cluck() generate a full stack trace so they call longmess() to 174*0Sstevel@tonic-gate# generate that. In verbose mode shortmess() calls longmess() so 175*0Sstevel@tonic-gate# you always get a stack trace 176*0Sstevel@tonic-gate 177*0Sstevel@tonic-gatesub shortmess { # Short-circuit &longmess if called via multiple packages 178*0Sstevel@tonic-gate { local $@; require Carp::Heavy; } # XXX fix require to not clear $@? 179*0Sstevel@tonic-gate # Icky backwards compatibility wrapper. :-( 180*0Sstevel@tonic-gate my $call_pack = caller(); 181*0Sstevel@tonic-gate local @CARP_NOT = caller(); 182*0Sstevel@tonic-gate shortmess_heavy(@_); 183*0Sstevel@tonic-gate} 184*0Sstevel@tonic-gate 185*0Sstevel@tonic-gate 186*0Sstevel@tonic-gate# the following four functions call longmess() or shortmess() depending on 187*0Sstevel@tonic-gate# whether they should generate a full stack trace (confess() and cluck()) 188*0Sstevel@tonic-gate# or simply report the caller's package (croak() and carp()), respectively. 189*0Sstevel@tonic-gate# confess() and croak() die, carp() and cluck() warn. 190*0Sstevel@tonic-gate 191*0Sstevel@tonic-gatesub croak { die shortmess @_ } 192*0Sstevel@tonic-gatesub confess { die longmess @_ } 193*0Sstevel@tonic-gatesub carp { warn shortmess @_ } 194*0Sstevel@tonic-gatesub cluck { warn longmess @_ } 195*0Sstevel@tonic-gate 196*0Sstevel@tonic-gate1; 197