[Summary view] [Print] [Text view]

   1  package Carp;
   2  
   3  our $VERSION = '1.08';
   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  our $MaxEvalLen = 0;
   9  our $Verbose    = 0;
  10  our $CarpLevel  = 0;
  11  our $MaxArgLen  = 64;   # How much of each argument to print. 0 = all.
  12  our $MaxArgNums = 8;    # How many arguments to print. 0 = all.
  13  
  14  require Exporter;
  15  our @ISA = ('Exporter');
  16  our @EXPORT = qw(confess croak carp);
  17  our @EXPORT_OK = qw(cluck verbose longmess shortmess);
  18  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;
  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 %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