7 carp - warn of errors (from perspective of caller)
9 cluck - warn of errors with stack backtrace
10 (not exported by default)
12 croak - die of errors (from perspective of caller)
14 confess - die of errors with stack backtrace
19 croak "We're outta here!";
22 cluck "This is how we got here!";
24 print FH Carp::shortmess("This will have caller's details added");
25 print FH Carp::longmess("This will have stack backtrace added");
29 The Carp routines are useful in your own modules because
30 they act like die() or warn(), but report where the error
31 was in the code they were called from. Thus if you have a
32 routine Foo() that has a carp() in it, then the carp()
33 will report the error as occurring where Foo() was called,
34 not where carp() was called.
36 The routine shortmess() can be used to generate the string that
37 carp/croak would have produced. The routine longmess() can be
38 used to generate the backtrace that cluck/confess would have
41 =head2 Forcing a Stack Trace
43 As a debugging aid, you can force Carp to treat a croak as a confess
44 and a carp as a cluck across I<all> modules. In other words, force a
45 detailed stack trace to be given. This can be very helpful when trying
46 to understand why, or from where, a warning or error is being generated.
48 This feature is enabled by 'importing' the non-existent symbol
49 'verbose'. You would typically enable it by saying
51 perl -MCarp=verbose script.pl
53 or by including the string C<MCarp=verbose> in the PERL5OPT
58 The Carp routines don't handle exception objects currently.
59 If called with a first argument that is a reference, they simply
60 call die() or warn(), as appropriate.
64 # This package is heavily used. Be small. Be fast. Be good.
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.
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.
75 $CarpLevel = 0; # How many extra package levels to skip on carp.
76 $MaxEvalLen = 0; # How much eval '...text...' to show. 0 = all.
77 $MaxArgLen = 64; # How much of each argument to print. 0 = all.
78 $MaxArgNums = 8; # How many arguments to print. 0 = all.
79 $Verbose = 0; # If true then make shortmess call longmess instead
81 $CarpInternal{Carp}++;
85 @EXPORT = qw(confess croak carp);
86 @EXPORT_OK = qw(cluck verbose longmess shortmess);
87 @EXPORT_FAIL = qw(verbose); # hook to enable verbose mode
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
97 $Verbose = shift if $_[0] eq 'verbose';
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.
109 { local $@; require Carp::Heavy; } # XXX fix require to not clear $@?
110 goto &longmess_heavy;
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
117 # generate that. In verbose mode shortmess() calls longmess() so
118 # you always get a stack trace
120 sub shortmess { # Short-circuit &longmess if called via multiple packages
121 { local $@; require Carp::Heavy; } # XXX fix require to not clear $@?
122 goto &shortmess_heavy;
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.
131 sub croak { die shortmess @_ }
132 sub confess { die longmess @_ }
133 sub carp { warn shortmess @_ }
134 sub cluck { warn longmess @_ }