home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _b961687322e7f9d0e546ffcdbc073572 < prev    next >
Encoding:
Text File  |  2000-03-15  |  4.2 KB  |  125 lines
  1. package Carp;
  2.  
  3. =head1 NAME
  4.  
  5. carp    - warn of errors (from perspective of caller)
  6.  
  7. cluck   - warn of errors with stack backtrace
  8.           (not exported by default)
  9.  
  10. croak   - die of errors (from perspective of caller)
  11.  
  12. confess - die of errors with stack backtrace
  13.  
  14. =head1 SYNOPSIS
  15.  
  16.     use Carp;
  17.     croak "We're outta here!";
  18.  
  19.     use Carp qw(cluck);
  20.     cluck "This is how we got here!";
  21.  
  22. =head1 DESCRIPTION
  23.  
  24. The Carp routines are useful in your own modules because
  25. they act like die() or warn(), but report where the error
  26. was in the code they were called from.  Thus if you have a 
  27. routine Foo() that has a carp() in it, then the carp() 
  28. will report the error as occurring where Foo() was called, 
  29. not where carp() was called.
  30.  
  31. =head2 Forcing a Stack Trace
  32.  
  33. As a debugging aid, you can force Carp to treat a croak as a confess
  34. and a carp as a cluck across I<all> modules. In other words, force a
  35. detailed stack trace to be given.  This can be very helpful when trying
  36. to understand why, or from where, a warning or error is being generated.
  37.  
  38. This feature is enabled by 'importing' the non-existent symbol
  39. 'verbose'. You would typically enable it by saying
  40.  
  41.     perl -MCarp=verbose script.pl
  42.  
  43. or by including the string C<MCarp=verbose> in the L<PERL5OPT>
  44. environment variable.
  45.  
  46. =head1 BUGS
  47.  
  48. The Carp routines don't handle exception objects currently.
  49. If called with a first argument that is a reference, they simply
  50. call die() or warn(), as appropriate.
  51.  
  52. =cut
  53.  
  54. # This package is heavily used. Be small. Be fast. Be good.
  55.  
  56. # Comments added by Andy Wardley <abw@kfs.org> 09-Apr-98, based on an
  57. # _almost_ complete understanding of the package.  Corrections and
  58. # comments are welcome.
  59.  
  60. # The $CarpLevel variable can be set to "strip off" extra caller levels for
  61. # those times when Carp calls are buried inside other functions.  The
  62. # $Max(EvalLen|(Arg(Len|Nums)) variables are used to specify how the eval
  63. # text and function arguments should be formatted when printed.
  64.  
  65. $CarpLevel = 0;        # How many extra package levels to skip on carp.
  66. $MaxEvalLen = 0;    # How much eval '...text...' to show. 0 = all.
  67. $MaxArgLen = 64;        # How much of each argument to print. 0 = all.
  68. $MaxArgNums = 8;        # How many arguments to print. 0 = all.
  69. $Verbose = 0;        # If true then make shortmess call longmess instead
  70.  
  71. require Exporter;
  72. @ISA = ('Exporter');
  73. @EXPORT = qw(confess croak carp);
  74. @EXPORT_OK = qw(cluck verbose);
  75. @EXPORT_FAIL = qw(verbose);    # hook to enable verbose mode
  76.  
  77.  
  78. # if the caller specifies verbose usage ("perl -MCarp=verbose script.pl")
  79. # then the following method will be called by the Exporter which knows
  80. # to do this thanks to @EXPORT_FAIL, above.  $_[1] will contain the word
  81. # 'verbose'.
  82.  
  83. sub export_fail {
  84.     shift;
  85.     $Verbose = shift if $_[0] eq 'verbose';
  86.     return @_;
  87. }
  88.  
  89.  
  90. # longmess() crawls all the way up the stack reporting on all the function
  91. # calls made.  The error string, $error, is originally constructed from the
  92. # arguments passed into longmess() via confess(), cluck() or shortmess().
  93. # This gets appended with the stack trace messages which are generated for
  94. # each function call on the stack.
  95.  
  96. sub longmess {
  97.     { local $@; require Carp::Heavy; }    # XXX fix require to not clear $@?
  98.     goto &longmess_heavy;
  99. }
  100.  
  101.  
  102. # shortmess() is called by carp() and croak() to skip all the way up to
  103. # the top-level caller's package and report the error from there.  confess()
  104. # and cluck() generate a full stack trace so they call longmess() to
  105. # generate that.  In verbose mode shortmess() calls longmess() so
  106. # you always get a stack trace
  107.  
  108. sub shortmess {    # Short-circuit &longmess if called via multiple packages
  109.     { local $@; require Carp::Heavy; }    # XXX fix require to not clear $@?
  110.     goto &shortmess_heavy;
  111. }
  112.  
  113.  
  114. # the following four functions call longmess() or shortmess() depending on
  115. # whether they should generate a full stack trace (confess() and cluck())
  116. # or simply report the caller's package (croak() and carp()), respectively.
  117. # confess() and croak() die, carp() and cluck() warn.
  118.  
  119. sub croak   { die  shortmess @_ }
  120. sub confess { die  longmess  @_ }
  121. sub carp    { warn shortmess @_ }
  122. sub cluck   { warn longmess  @_ }
  123.  
  124. 1;
  125.