| 1 | | | | | package Carp; |
| 2 | | | | | |
| 3 | 1 | 500ns | | | our $VERSION = '1.11'; |
| 4 | | | | | # this file is an utra-lightweight stub. The first time a function is |
| 5 | | | | | # called, Carp::Heavy is loaded, and the real short/longmessmess_jmp |
| 6 | | | | | # subs are installed |
| 7 | | | | | |
| 8 | 1 | 100ns | | | our $MaxEvalLen = 0; |
| 9 | 1 | 100ns | | | our $Verbose = 0; |
| 10 | 1 | 100ns | | | our $CarpLevel = 0; |
| 11 | 1 | 0s | | | our $MaxArgLen = 64; # How much of each argument to print. 0 = all. |
| 12 | 1 | 100ns | | | our $MaxArgNums = 8; # How many arguments to print. 0 = all. |
| 13 | | | | | |
| 14 | 1 | 400ns | | | require Exporter; |
| 15 | 1 | 6µs | | | our @ISA = ('Exporter'); |
| 16 | 1 | 700ns | | | our @EXPORT = qw(confess croak carp); |
| 17 | 1 | 700ns | | | our @EXPORT_OK = qw(cluck verbose longmess shortmess); |
| 18 | 1 | 300ns | | | our @EXPORT_FAIL = qw(verbose); # hook to enable verbose mode |
| 19 | | | | | |
| 20 | | | | | # if the caller specifies verbose usage ("perl -MCarp=verbose script.pl") |
| 21 | | | | | # then the following method will be called by the Exporter which knows |
| 22 | | | | | # to do this thanks to @EXPORT_FAIL, above. $_[1] will contain the word |
| 23 | | | | | # 'verbose'. |
| 24 | | | | | |
| 25 | | | | | sub export_fail { shift; $Verbose = shift if $_[0] eq 'verbose'; @_ } |
| 26 | | | | | |
| 27 | | | | | # fixed hooks for stashes to point to |
| 28 | | | | | sub longmess { goto &longmess_jmp } |
| 29 | | | | | sub shortmess { goto &shortmess_jmp } |
| 30 | | | | | # these two are replaced when Carp::Heavy is loaded |
| 31 | | | | | sub longmess_jmp { |
| 32 | | | | | local($@, $!); |
| 33 | | | | | eval { require Carp::Heavy }; |
| 34 | | | | | return $@ if $@; |
| 35 | | | | | goto &longmess_real; |
| 36 | | | | | } |
| 37 | | | | | sub shortmess_jmp { |
| 38 | | | | | local($@, $!); |
| 39 | | | | | eval { require Carp::Heavy }; |
| 40 | | | | | return $@ if $@; |
| 41 | | | | | goto &shortmess_real; |
| 42 | | | | | } |
| 43 | | | | | |
| 44 | | | | | sub croak { die shortmess @_ } |
| 45 | | | | | sub confess { die longmess @_ } |
| 46 | | | | | sub carp { warn shortmess @_ } |
| 47 | | | | | sub cluck { warn longmess @_ } |
| 48 | | | | | |
| 49 | 1 | 12µs | | | 1; |
| 50 | | | | | __END__ |
| 51 | | | | | |
| 52 | | | | | =head1 NAME |
| 53 | | | | | |
| 54 | | | | | carp - warn of errors (from perspective of caller) |
| 55 | | | | | |
| 56 | | | | | cluck - warn of errors with stack backtrace |
| 57 | | | | | (not exported by default) |
| 58 | | | | | |
| 59 | | | | | croak - die of errors (from perspective of caller) |
| 60 | | | | | |
| 61 | | | | | confess - die of errors with stack backtrace |
| 62 | | | | | |
| 63 | | | | | =head1 SYNOPSIS |
| 64 | | | | | |
| 65 | | | | | use Carp; |
| 66 | | | | | croak "We're outta here!"; |
| 67 | | | | | |
| 68 | | | | | use Carp qw(cluck); |
| 69 | | | | | cluck "This is how we got here!"; |
| 70 | | | | | |
| 71 | | | | | =head1 DESCRIPTION |
| 72 | | | | | |
| 73 | | | | | The Carp routines are useful in your own modules because |
| 74 | | | | | they act like die() or warn(), but with a message which is more |
| 75 | | | | | likely to be useful to a user of your module. In the case of |
| 76 | | | | | cluck, confess, and longmess that context is a summary of every |
| 77 | | | | | call in the call-stack. For a shorter message you can use C<carp> |
| 78 | | | | | or C<croak> which report the error as being from where your module |
| 79 | | | | | was called. There is no guarantee that that is where the error |
| 80 | | | | | was, but it is a good educated guess. |
| 81 | | | | | |
| 82 | | | | | You can also alter the way the output and logic of C<Carp> works, by |
| 83 | | | | | changing some global variables in the C<Carp> namespace. See the |
| 84 | | | | | section on C<GLOBAL VARIABLES> below. |
| 85 | | | | | |
| 86 | | | | | Here is a more complete description of how C<carp> and C<croak> work. |
| 87 | | | | | What they do is search the call-stack for a function call stack where |
| 88 | | | | | they have not been told that there shouldn't be an error. If every |
| 89 | | | | | call is marked safe, they give up and give a full stack backtrace |
| 90 | | | | | instead. In other words they presume that the first likely looking |
| 91 | | | | | potential suspect is guilty. Their rules for telling whether |
| 92 | | | | | a call shouldn't generate errors work as follows: |
| 93 | | | | | |
| 94 | | | | | =over 4 |
| 95 | | | | | |
| 96 | | | | | =item 1. |
| 97 | | | | | |
| 98 | | | | | Any call from a package to itself is safe. |
| 99 | | | | | |
| 100 | | | | | =item 2. |
| 101 | | | | | |
| 102 | | | | | Packages claim that there won't be errors on calls to or from |
| 103 | | | | | packages explicitly marked as safe by inclusion in C<@CARP_NOT>, or |
| 104 | | | | | (if that array is empty) C<@ISA>. The ability to override what |
| 105 | | | | | @ISA says is new in 5.8. |
| 106 | | | | | |
| 107 | | | | | =item 3. |
| 108 | | | | | |
| 109 | | | | | The trust in item 2 is transitive. If A trusts B, and B |
| 110 | | | | | trusts C, then A trusts C. So if you do not override C<@ISA> |
| 111 | | | | | with C<@CARP_NOT>, then this trust relationship is identical to, |
| 112 | | | | | "inherits from". |
| 113 | | | | | |
| 114 | | | | | =item 4. |
| 115 | | | | | |
| 116 | | | | | Any call from an internal Perl module is safe. (Nothing keeps |
| 117 | | | | | user modules from marking themselves as internal to Perl, but |
| 118 | | | | | this practice is discouraged.) |
| 119 | | | | | |
| 120 | | | | | =item 5. |
| 121 | | | | | |
| 122 | | | | | Any call to Perl's warning system (eg Carp itself) is safe. |
| 123 | | | | | (This rule is what keeps it from reporting the error at the |
| 124 | | | | | point where you call C<carp> or C<croak>.) |
| 125 | | | | | |
| 126 | | | | | =item 6. |
| 127 | | | | | |
| 128 | | | | | C<$Carp::CarpLevel> can be set to skip a fixed number of additional |
| 129 | | | | | call levels. Using this is not recommended because it is very |
| 130 | | | | | difficult to get it to behave correctly. |
| 131 | | | | | |
| 132 | | | | | =back |
| 133 | | | | | |
| 134 | | | | | =head2 Forcing a Stack Trace |
| 135 | | | | | |
| 136 | | | | | As a debugging aid, you can force Carp to treat a croak as a confess |
| 137 | | | | | and a carp as a cluck across I<all> modules. In other words, force a |
| 138 | | | | | detailed stack trace to be given. This can be very helpful when trying |
| 139 | | | | | to understand why, or from where, a warning or error is being generated. |
| 140 | | | | | |
| 141 | | | | | This feature is enabled by 'importing' the non-existent symbol |
| 142 | | | | | 'verbose'. You would typically enable it by saying |
| 143 | | | | | |
| 144 | | | | | perl -MCarp=verbose script.pl |
| 145 | | | | | |
| 146 | | | | | or by including the string C<-MCarp=verbose> in the PERL5OPT |
| 147 | | | | | environment variable. |
| 148 | | | | | |
| 149 | | | | | Alternately, you can set the global variable C<$Carp::Verbose> to true. |
| 150 | | | | | See the C<GLOBAL VARIABLES> section below. |
| 151 | | | | | |
| 152 | | | | | =head1 GLOBAL VARIABLES |
| 153 | | | | | |
| 154 | | | | | =head2 $Carp::MaxEvalLen |
| 155 | | | | | |
| 156 | | | | | This variable determines how many characters of a string-eval are to |
| 157 | | | | | be shown in the output. Use a value of C<0> to show all text. |
| 158 | | | | | |
| 159 | | | | | Defaults to C<0>. |
| 160 | | | | | |
| 161 | | | | | =head2 $Carp::MaxArgLen |
| 162 | | | | | |
| 163 | | | | | This variable determines how many characters of each argument to a |
| 164 | | | | | function to print. Use a value of C<0> to show the full length of the |
| 165 | | | | | argument. |
| 166 | | | | | |
| 167 | | | | | Defaults to C<64>. |
| 168 | | | | | |
| 169 | | | | | =head2 $Carp::MaxArgNums |
| 170 | | | | | |
| 171 | | | | | This variable determines how many arguments to each function to show. |
| 172 | | | | | Use a value of C<0> to show all arguments to a function call. |
| 173 | | | | | |
| 174 | | | | | Defaults to C<8>. |
| 175 | | | | | |
| 176 | | | | | =head2 $Carp::Verbose |
| 177 | | | | | |
| 178 | | | | | This variable makes C<carp> and C<cluck> generate stack backtraces |
| 179 | | | | | just like C<cluck> and C<confess>. This is how C<use Carp 'verbose'> |
| 180 | | | | | is implemented internally. |
| 181 | | | | | |
| 182 | | | | | Defaults to C<0>. |
| 183 | | | | | |
| 184 | | | | | =head2 %Carp::Internal |
| 185 | | | | | |
| 186 | | | | | This says what packages are internal to Perl. C<Carp> will never |
| 187 | | | | | report an error as being from a line in a package that is internal to |
| 188 | | | | | Perl. For example: |
| 189 | | | | | |
| 190 | | | | | $Carp::Internal{ (__PACKAGE__) }++; |
| 191 | | | | | # time passes... |
| 192 | | | | | sub foo { ... or confess("whatever") }; |
| 193 | | | | | |
| 194 | | | | | would give a full stack backtrace starting from the first caller |
| 195 | | | | | outside of __PACKAGE__. (Unless that package was also internal to |
| 196 | | | | | Perl.) |
| 197 | | | | | |
| 198 | | | | | =head2 %Carp::CarpInternal |
| 199 | | | | | |
| 200 | | | | | This says which packages are internal to Perl's warning system. For |
| 201 | | | | | generating a full stack backtrace this is the same as being internal |
| 202 | | | | | to Perl, the stack backtrace will not start inside packages that are |
| 203 | | | | | listed in C<%Carp::CarpInternal>. But it is slightly different for |
| 204 | | | | | the summary message generated by C<carp> or C<croak>. There errors |
| 205 | | | | | will not be reported on any lines that are calling packages in |
| 206 | | | | | C<%Carp::CarpInternal>. |
| 207 | | | | | |
| 208 | | | | | For example C<Carp> itself is listed in C<%Carp::CarpInternal>. |
| 209 | | | | | Therefore the full stack backtrace from C<confess> will not start |
| 210 | | | | | inside of C<Carp>, and the short message from calling C<croak> is |
| 211 | | | | | not placed on the line where C<croak> was called. |
| 212 | | | | | |
| 213 | | | | | =head2 $Carp::CarpLevel |
| 214 | | | | | |
| 215 | | | | | This variable determines how many additional call frames are to be |
| 216 | | | | | skipped that would not otherwise be when reporting where an error |
| 217 | | | | | occurred on a call to one of C<Carp>'s functions. It is fairly easy |
| 218 | | | | | to count these call frames on calls that generate a full stack |
| 219 | | | | | backtrace. However it is much harder to do this accounting for calls |
| 220 | | | | | that generate a short message. Usually people skip too many call |
| 221 | | | | | frames. If they are lucky they skip enough that C<Carp> goes all of |
| 222 | | | | | the way through the call stack, realizes that something is wrong, and |
| 223 | | | | | then generates a full stack backtrace. If they are unlucky then the |
| 224 | | | | | error is reported from somewhere misleading very high in the call |
| 225 | | | | | stack. |
| 226 | | | | | |
| 227 | | | | | Therefore it is best to avoid C<$Carp::CarpLevel>. Instead use |
| 228 | | | | | C<@CARP_NOT>, C<%Carp::Internal> and C<%Carp::CarpInternal>. |
| 229 | | | | | |
| 230 | | | | | Defaults to C<0>. |
| 231 | | | | | |
| 232 | | | | | =head1 BUGS |
| 233 | | | | | |
| 234 | | | | | The Carp routines don't handle exception objects currently. |
| 235 | | | | | If called with a first argument that is a reference, they simply |
| 236 | | | | | call die() or warn(), as appropriate. |
| 237 | | | | | |