[p5sagit/p5-mst-13.2.git] / lib / Carp.pm

package Carp;

=head1 NAME

carp    - warn of errors (from perspective of caller)

cluck   - warn of errors with stack backtrace
          (not exported by default)

croak   - die of errors (from perspective of caller)

confess - die of errors with stack backtrace

=head1 SYNOPSIS

    use Carp;
    croak "We're outta here!";

    use Carp qw(cluck);
    cluck "This is how we got here!";

=head1 DESCRIPTION

The Carp routines are useful in your own modules because
they act like die() or warn(), but report where the error
was in the code they were called from.  Thus if you have a 
routine Foo() that has a carp() in it, then the carp() 
will report the error as occurring where Foo() was called, 
not where carp() was called.

=head2 Forcing a Stack Trace

As a debugging aid, you can force Carp to treat a croak as a confess
and a carp as a cluck across I<all> modules. In other words, force a
detailed stack trace to be given.  This can be very helpful when trying
to understand why, or from where, a warning or error is being generated.

This feature is enabled by 'importing' the non-existant symbol
'verbose'. You would typically enable it by saying

    perl -MCarp=verbose script.pl

or by including the string C<MCarp=verbose> in the L<PERL5OPT>
environment variable.

=cut

# This package is heavily used. Be small. Be fast. Be good.

# Comments added by Andy Wardley <abw@kfs.org> 09-Apr-98, based on an
# _almost_ complete understanding of the package.  Corrections and
# comments are welcome.

# The $CarpLevel variable can be set to "strip off" extra caller levels for
# those times when Carp calls are buried inside other functions.  The
# $Max(EvalLen|(Arg(Len|Nums)) variables are used to specify how the eval
# text and function arguments should be formatted when printed.

$CarpLevel = 0;		# How many extra package levels to skip on carp.
$MaxEvalLen = 0;	# How much eval '...text...' to show. 0 = all.
$MaxArgLen = 64;        # How much of each argument to print. 0 = all.
$MaxArgNums = 8;        # How many arguments to print. 0 = all.

require Exporter;
@ISA = ('Exporter');
@EXPORT = qw(confess croak carp);
@EXPORT_OK = qw(cluck verbose);
@EXPORT_FAIL = qw(verbose);	# hook to enable verbose mode


# if the caller specifies verbose usage ("perl -MCarp=verbose script.pl")
# then the following method will be called by the Exporter which knows
# to do this thanks to @EXPORT_FAIL, above.  $_[1] will contain the word
# 'verbose'.

sub export_fail {
    shift;
    if ($_[0] eq 'verbose') {
	local $^W = 0; # avoid "sub-routine redefined..." warning
	*shortmess = \&longmess; # set shortmess() as an alias to longmess()
	shift; # remove 'verbose' from the args to keep Exporter happy
    }
    return @_;
}


# longmess() crawls all the way up the stack reporting on all the function
# calls made.  The error string, $error, is originally constructed from the
# arguments passed into longmess() via confess(), cluck() or shortmess().
# This gets appended with the stack trace messages which are generated for
# each function call on the stack.

sub longmess {
    my $error = join '', @_;
    my $mess = "";
    my $i = 1 + $CarpLevel;
    my ($pack,$file,$line,$sub,$hargs,$eval,$require);
    my (@a);
    #
    # crawl up the stack....
    #
    while (do { { package DB; @a = caller($i++) } } ) {
	# get copies of the variables returned from caller()
	($pack,$file,$line,$sub,$hargs,undef,$eval,$require) = @a;
	#
	# if the $error error string is newline terminated then it
	# is copied into $mess.  Otherwise, $mess gets set (at the end of
	# the 'else {' section below) to one of two things.  The first time
	# through, it is set to the "$error at $file line $line" message.
	# $error is then set to 'called' which triggers subsequent loop
	# iterations to append $sub to $mess before appending the "$error
	# at $file line $line" which now actually reads "called at $file line
	# $line".  Thus, the stack trace message is constructed:
	#
	#        first time: $mess  = $error at $file line $line
	#  subsequent times: $mess .= $sub $error at $file line $line
	#                                  ^^^^^^
	#                                 "called"
	if ($error =~ m/\n$/) {
	    $mess .= $error;
	} else {
	    # Build a string, $sub, which names the sub-routine called.
	    # This may also be "require ...", "eval '...' or "eval {...}"
	    if (defined $eval) {
		if ($require) {
		    $sub = "require $eval";
		} else {
		    $eval =~ s/([\\\'])/\\$1/g;
		    if ($MaxEvalLen && length($eval) > $MaxEvalLen) {
			substr($eval,$MaxEvalLen) = '...';
		    }
		    $sub = "eval '$eval'";
		}
	    } elsif ($sub eq '(eval)') {
		$sub = 'eval {...}';
	    }
	    # if there are any arguments in the sub-routine call, format
	    # them according to the format variables defined earlier in
	    # this file and join them onto the $sub sub-routine string
	    if ($hargs) {
		# we may trash some of the args so we take a copy
		@a = @DB::args;	# must get local copy of args
		# don't print any more than $MaxArgNums
		if ($MaxArgNums and @a > $MaxArgNums) {
		    # cap the length of $#a and set the last element to '...'
		    $#a = $MaxArgNums;
		    $a[$#a] = "...";
		}
		for (@a) {
		    # set args to the string "undef" if undefined
		    $_ = "undef", next unless defined $_;
		    if (ref $_) {
			# dunno what this is for...
			$_ .= '';
			s/'/\\'/g;
		    }
		    else {
			s/'/\\'/g;
			# terminate the string early with '...' if too long
			substr($_,$MaxArgLen) = '...'
			    if $MaxArgLen and $MaxArgLen < length;
		    }
		    # 'quote' arg unless it looks like a number
		    $_ = "'$_'" unless /^-?[\d.]+$/;
		    # print high-end chars as 'M-<char>' or '^<char>'
		    s/([\200-\377])/sprintf("M-%c",ord($1)&0177)/eg;
		    s/([\0-\37\177])/sprintf("^%c",ord($1)^64)/eg;
		}
		# append ('all', 'the', 'arguments') to the $sub string
		$sub .= '(' . join(', ', @a) . ')';
	    }
	    # here's where the error message, $mess, gets constructed
	    $mess .= "\t$sub " if $error eq "called";
	    $mess .= "$error at $file line $line\n";
	}
	# we don't need to print the actual error message again so we can
	# change this to "called" so that the string "$error at $file line
	# $line" makes sense as "called at $file line $line".
	$error = "called";
    }
    # this kludge circumvents die's incorrect handling of NUL
    my $msg = \($mess || $error);
    $$msg =~ tr/\0//d;
    $$msg;
}


# shortmess() is called by carp() and croak() to skip all the way up to
# the top-level caller's package and report the error from there.  confess()
# and cluck() generate a full stack trace so they call longmess() to
# generate that.  In verbose mode shortmess() is aliased to longmess() so
# you always get a stack trace

sub shortmess {	# Short-circuit &longmess if called via multiple packages
    my $error = join '', @_;
    my ($prevpack) = caller(1);
    my $extra = $CarpLevel;
    my $i = 2;
    my ($pack,$file,$line);
    # when reporting an error, we want to report it from the context of the
    # calling package.  So what is the calling package?  Within a module,
    # there may be many calls between methods and perhaps between sub-classes
    # and super-classes, but the user isn't interested in what happens
    # inside the package.  We start by building a hash array which keeps
    # track of all the packages to which the calling package belongs.  We
    # do this by examining its @ISA variable.  Any call from a base class
    # method (one of our caller's @ISA packages) can be ignored
    my %isa = ($prevpack,1);

    # merge all the caller's @ISA packages into %isa.
    @isa{@{"${prevpack}::ISA"}} = ()
	if(defined @{"${prevpack}::ISA"});

    # now we crawl up the calling stack and look at all the packages in
    # there.  For each package, we look to see if it has an @ISA and then
    # we see if our caller features in that list.  That would imply that
    # our caller is a derived class of that package and its calls can also
    # be ignored
    while (($pack,$file,$line) = caller($i++)) {
	if(defined @{$pack . "::ISA"}) {
	    my @i = @{$pack . "::ISA"};
	    my %i;
	    @i{@i} = ();
	    # merge any relevant packages into %isa
	    @isa{@i,$pack} = ()
		if(exists $i{$prevpack} || exists $isa{$pack});
	}

	# and here's where we do the ignoring... if the package in
	# question is one of our caller's base or derived packages then
	# we can ignore it (skip it) and go onto the next (but note that
	# the continue { } block below gets called every time)
	next
	    if(exists $isa{$pack});

	# Hey!  We've found a package that isn't one of our caller's
	# clan....but wait, $extra refers to the number of 'extra' levels
	# we should skip up.  If $extra > 0 then this is a false alarm.
	# We must merge the package into the %isa hash (so we can ignore it
	# if it pops up again), decrement $extra, and continue.
	if ($extra-- > 0) {
	    %isa = ($pack,1);
	    @isa{@{$pack . "::ISA"}} = ()
		if(defined @{$pack . "::ISA"});
	}
	else {
	    # OK!  We've got a candidate package.  Time to construct the
	    # relevant error message and return it.   die() doesn't like
	    # to be given NUL characters (which $msg may contain) so we
	    # remove them first.
	    (my $msg = "$error at $file line $line\n") =~ tr/\0//d;
	    return $msg;
	}
    }
    continue {
	$prevpack = $pack;
    }

    # uh-oh!  It looks like we crawled all the way up the stack and
    # never found a candidate package.  Oh well, let's call longmess
    # to generate a full stack trace.  We use the magical form of 'goto'
    # so that this shortmess() function doesn't appear on the stack
    # to further confuse longmess() about it's calling package.
    goto &longmess;
}


# the following four functions call longmess() or shortmess() depending on
# whether they should generate a full stack trace (confess() and cluck())
# or simply report the caller's package (croak() and carp()), respectively.
# confess() and croak() die, carp() and cluck() warn.

sub croak   { die  shortmess @_ }
sub confess { die  longmess  @_ }
sub carp    { warn shortmess @_ }
sub cluck   { warn longmess  @_ }

1;
Commit	Line	Data
a0d0e21e	1	package Carp;
a0d0e21e	2
f06db76b	3	=head1 NAME
f06db76b	4
4d935a29	5	carp - warn of errors (from perspective of caller)
f06db76b	6
4d935a29	7	cluck - warn of errors with stack backtrace
	8	(not exported by default)
	9
	10	croak - die of errors (from perspective of caller)
f06db76b	11
	12	confess - die of errors with stack backtrace
	13
	14	=head1 SYNOPSIS
	15
	16	use Carp;
	17	croak "We're outta here!";
	18
4d935a29	19	use Carp qw(cluck);
	20	cluck "This is how we got here!";
	21
f06db76b	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
4d935a29	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-existant 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
f06db76b	46	=cut
f06db76b	47
4d935a29	48	# This package is heavily used. Be small. Be fast. Be good.
a0d0e21e	49
7b8d334a	50	# Comments added by Andy Wardley <abw@kfs.org> 09-Apr-98, based on an
	51	# _almost_ complete understanding of the package. Corrections and
	52	# comments are welcome.
	53
	54	# The $CarpLevel variable can be set to "strip off" extra caller levels for
	55	# those times when Carp calls are buried inside other functions. The
	56	# $Max(EvalLen\|(Arg(Len\|Nums)) variables are used to specify how the eval
	57	# text and function arguments should be formatted when printed.
	58
748a9306	59	$CarpLevel = 0; # How many extra package levels to skip on carp.
c07a80fd	60	$MaxEvalLen = 0; # How much eval '...text...' to show. 0 = all.
55497cff	61	$MaxArgLen = 64; # How much of each argument to print. 0 = all.
55497cff	62	$MaxArgNums = 8; # How many arguments to print. 0 = all.
748a9306	63
a0d0e21e	64	require Exporter;
fb73857a	65	@ISA = ('Exporter');
a0d0e21e	66	@EXPORT = qw(confess croak carp);
4d935a29	67	@EXPORT_OK = qw(cluck verbose);
	68	@EXPORT_FAIL = qw(verbose); # hook to enable verbose mode
	69
7b8d334a	70
	71	# if the caller specifies verbose usage ("perl -MCarp=verbose script.pl")
	72	# then the following method will be called by the Exporter which knows
	73	# to do this thanks to @EXPORT_FAIL, above. $_[1] will contain the word
	74	# 'verbose'.
	75
4d935a29	76	sub export_fail {
	77	shift;
	78	if ($_[0] eq 'verbose') {
7b8d334a	79	local $^W = 0; # avoid "sub-routine redefined..." warning
	80	*shortmess = \&longmess; # set shortmess() as an alias to longmess()
	81	shift; # remove 'verbose' from the args to keep Exporter happy
4d935a29	82	}
	83	return @_;
	84	}
	85
a0d0e21e	86
7b8d334a	87	# longmess() crawls all the way up the stack reporting on all the function
	88	# calls made. The error string, $error, is originally constructed from the
	89	# arguments passed into longmess() via confess(), cluck() or shortmess().
	90	# This gets appended with the stack trace messages which are generated for
	91	# each function call on the stack.
	92
a0d0e21e	93	sub longmess {
d43563dd	94	my $error = join '', @_;
a0d0e21e	95	my $mess = "";
748a9306	96	my $i = 1 + $CarpLevel;
55497cff	97	my ($pack,$file,$line,$sub,$hargs,$eval,$require);
55497cff	98	my (@a);
7b8d334a	99	#
	100	# crawl up the stack....
	101	#
55497cff	102	while (do { { package DB; @a = caller($i++) } } ) {
7b8d334a	103	# get copies of the variables returned from caller()
	104	($pack,$file,$line,$sub,$hargs,undef,$eval,$require) = @a;
	105	#
	106	# if the $error error string is newline terminated then it
	107	# is copied into $mess. Otherwise, $mess gets set (at the end of
	108	# the 'else {' section below) to one of two things. The first time
	109	# through, it is set to the "$error at $file line $line" message.
	110	# $error is then set to 'called' which triggers subsequent loop
	111	# iterations to append $sub to $mess before appending the "$error
	112	# at $file line $line" which now actually reads "called at $file line
	113	# $line". Thus, the stack trace message is constructed:
	114	#
	115	# first time: $mess = $error at $file line $line
	116	# subsequent times: $mess .= $sub $error at $file line $line
	117	# ^^^^^^
	118	# "called"
c1bce5d7	119	if ($error =~ m/\n$/) {
	120	$mess .= $error;
	121	} else {
7b8d334a	122	# Build a string, $sub, which names the sub-routine called.
7b8d334a	123	# This may also be "require ...", "eval '...' or "eval {...}"
c07a80fd	124	if (defined $eval) {
7b8d334a	125	if ($require) {
c07a80fd	126	$sub = "require $eval";
c07a80fd	127	} else {
9c7d8621	128	$eval =~ s/([\\\'])/\\$1/g;
c07a80fd	129	if ($MaxEvalLen && length($eval) > $MaxEvalLen) {
	130	substr($eval,$MaxEvalLen) = '...';
	131	}
	132	$sub = "eval '$eval'";
	133	}
	134	} elsif ($sub eq '(eval)') {
	135	$sub = 'eval {...}';
	136	}
7b8d334a	137	# if there are any arguments in the sub-routine call, format
	138	# them according to the format variables defined earlier in
	139	# this file and join them onto the $sub sub-routine string
55497cff	140	if ($hargs) {
7b8d334a	141	# we may trash some of the args so we take a copy
	142	@a = @DB::args; # must get local copy of args
	143	# don't print any more than $MaxArgNums
	144	if ($MaxArgNums and @a > $MaxArgNums) {
	145	# cap the length of $#a and set the last element to '...'
	146	$#a = $MaxArgNums;
	147	$a[$#a] = "...";
68dc0745	148	}
7b8d334a	149	for (@a) {
	150	# set args to the string "undef" if undefined
	151	$_ = "undef", next unless defined $_;
	152	if (ref $_) {
	153	# dunno what this is for...
	154	$_ .= '';
	155	s/'/\\'/g;
	156	}
	157	else {
	158	s/'/\\'/g;
	159	# terminate the string early with '...' if too long
	160	substr($_,$MaxArgLen) = '...'
	161	if $MaxArgLen and $MaxArgLen < length;
	162	}
	163	# 'quote' arg unless it looks like a number
	164	$_ = "'$_'" unless /^-?[\d.]+$/;
	165	# print high-end chars as 'M-<char>' or '^<char>'
	166	s/([\200-\377])/sprintf("M-%c",ord($1)&0177)/eg;
	167	s/([\0-\37\177])/sprintf("^%c",ord($1)^64)/eg;
68dc0745	168	}
7b8d334a	169	# append ('all', 'the', 'arguments') to the $sub string
7b8d334a	170	$sub .= '(' . join(', ', @a) . ')';
55497cff	171	}
7b8d334a	172	# here's where the error message, $mess, gets constructed
c1bce5d7	173	$mess .= "\t$sub " if $error eq "called";
	174	$mess .= "$error at $file line $line\n";
	175	}
7b8d334a	176	# we don't need to print the actual error message again so we can
	177	# change this to "called" so that the string "$error at $file line
	178	# $line" makes sense as "called at $file line $line".
a0d0e21e	179	$error = "called";
a0d0e21e	180	}
68dc0745	181	# this kludge circumvents die's incorrect handling of NUL
	182	my $msg = \($mess \|\| $error);
	183	$$msg =~ tr/\0//d;
	184	$$msg;
a0d0e21e	185	}
a0d0e21e	186
7b8d334a	187
	188	# shortmess() is called by carp() and croak() to skip all the way up to
	189	# the top-level caller's package and report the error from there. confess()
	190	# and cluck() generate a full stack trace so they call longmess() to
	191	# generate that. In verbose mode shortmess() is aliased to longmess() so
	192	# you always get a stack trace
	193
748a9306	194	sub shortmess { # Short-circuit &longmess if called via multiple packages
d43563dd	195	my $error = join '', @_;
9c7d8621	196	my ($prevpack) = caller(1);
748a9306	197	my $extra = $CarpLevel;
a0d0e21e	198	my $i = 2;
c07a80fd	199	my ($pack,$file,$line);
7b8d334a	200	# when reporting an error, we want to report it from the context of the
	201	# calling package. So what is the calling package? Within a module,
	202	# there may be many calls between methods and perhaps between sub-classes
	203	# and super-classes, but the user isn't interested in what happens
	204	# inside the package. We start by building a hash array which keeps
	205	# track of all the packages to which the calling package belongs. We
	206	# do this by examining its @ISA variable. Any call from a base class
	207	# method (one of our caller's @ISA packages) can be ignored
9c7d8621	208	my %isa = ($prevpack,1);
9c7d8621	209
7b8d334a	210	# merge all the caller's @ISA packages into %isa.
9c7d8621	211	@isa{@{"${prevpack}::ISA"}} = ()
	212	if(defined @{"${prevpack}::ISA"});
	213
7b8d334a	214	# now we crawl up the calling stack and look at all the packages in
	215	# there. For each package, we look to see if it has an @ISA and then
	216	# we see if our caller features in that list. That would imply that
	217	# our caller is a derived class of that package and its calls can also
	218	# be ignored
c07a80fd	219	while (($pack,$file,$line) = caller($i++)) {
9c7d8621	220	if(defined @{$pack . "::ISA"}) {
	221	my @i = @{$pack . "::ISA"};
	222	my %i;
	223	@i{@i} = ();
7b8d334a	224	# merge any relevant packages into %isa
9c7d8621	225	@isa{@i,$pack} = ()
	226	if(exists $i{$prevpack} \|\| exists $isa{$pack});
	227	}
	228
7b8d334a	229	# and here's where we do the ignoring... if the package in
	230	# question is one of our caller's base or derived packages then
	231	# we can ignore it (skip it) and go onto the next (but note that
	232	# the continue { } block below gets called every time)
9c7d8621	233	next
	234	if(exists $isa{$pack});
	235
7b8d334a	236	# Hey! We've found a package that isn't one of our caller's
	237	# clan....but wait, $extra refers to the number of 'extra' levels
	238	# we should skip up. If $extra > 0 then this is a false alarm.
	239	# We must merge the package into the %isa hash (so we can ignore it
	240	# if it pops up again), decrement $extra, and continue.
9c7d8621	241	if ($extra-- > 0) {
	242	%isa = ($pack,1);
	243	@isa{@{$pack . "::ISA"}} = ()
	244	if(defined @{$pack . "::ISA"});
	245	}
	246	else {
7b8d334a	247	# OK! We've got a candidate package. Time to construct the
	248	# relevant error message and return it. die() doesn't like
	249	# to be given NUL characters (which $msg may contain) so we
	250	# remove them first.
68dc0745	251	(my $msg = "$error at $file line $line\n") =~ tr/\0//d;
68dc0745	252	return $msg;
748a9306	253	}
a0d0e21e	254	}
9c7d8621	255	continue {
	256	$prevpack = $pack;
	257	}
	258
7b8d334a	259	# uh-oh! It looks like we crawled all the way up the stack and
	260	# never found a candidate package. Oh well, let's call longmess
	261	# to generate a full stack trace. We use the magical form of 'goto'
	262	# so that this shortmess() function doesn't appear on the stack
	263	# to further confuse longmess() about it's calling package.
748a9306	264	goto &longmess;
a0d0e21e	265	}
a0d0e21e	266
7b8d334a	267
	268	# the following four functions call longmess() or shortmess() depending on
	269	# whether they should generate a full stack trace (confess() and cluck())
	270	# or simply report the caller's package (croak() and carp()), respectively.
	271	# confess() and croak() die, carp() and cluck() warn.
	272
	273	sub croak { die shortmess @_ }
	274	sub confess { die longmess @_ }
	275	sub carp { warn shortmess @_ }
	276	sub cluck { warn longmess @_ }
a0d0e21e	277
748a9306	278	1;