Forcing a Stack Trace¶

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

    perl -MCarp=verbose script.pl

or by including the string "-MCarp=verbose" in the PERL5OPT environment variable.

Alternately, you can set the global variable $Carp::Verbose to true. See the "GLOBAL VARIABLES" section below.

Stack Trace formatting¶

Carp gives two ways to control this.

1.

For objects, a method, "CARP_TRACE", will be called, if it exists. If this method doesn't exist, or it recurses into "Carp", or it otherwise throws an exception, this is skipped, and Carp moves on to the next option, otherwise checking stops and the string returned is used. It is recommended that the object's type is part of the string to make debugging easier.

2.

For any type of reference, $Carp::RefArgFormatter is checked (see below). This variable is expected to be a code reference, and the current parameter is passed in. If this function doesn't exist (the variable is undef), or it recurses into "Carp", or it otherwise throws an exception, this is skipped, and Carp moves on to the next option, otherwise checking stops and the string returned is used.

3.

Otherwise, if neither "CARP_TRACE" nor $Carp::RefArgFormatter is available, stringify the value ignoring any overloading.

$Carp::MaxEvalLen¶

Defaults to 0.

$Carp::MaxArgLen¶

Defaults to 64.

$Carp::MaxArgNums¶

Defaults to 8.

$Carp::Verbose¶

Defaults to 0.

$Carp::RefArgFormatter¶

local $Carp::RefArgFormatter = sub { require Data::Dumper; Data::Dumper::Dump($_[0]); # not necessarily safe };

@CARP_NOT¶

NB: This variable must be in the package's symbol table, thus:

    # These work
    our @CARP_NOT; # file scope
    use vars qw(@CARP_NOT); # package scope
    @My::Package::CARP_NOT = ... ; # explicit package variable

    # These don't work
    sub xyz { ... @CARP_NOT = ... } # w/o declarations above
    my @CARP_NOT; # even at top-level

Example of use:

    package My::Carping::Package;
    use Carp;
    our @CARP_NOT;
    sub bar     { .... or _error('Wrong input') }
    sub _error  {
        # temporary control of where'ness, __PACKAGE__ is implicit
        local @CARP_NOT = qw(My::Friendly::Caller);
        carp(@_)
    }

This would make "Carp" report the error as coming from a caller not in "My::Carping::Package", nor from "My::Friendly::Caller".

Also read the "DESCRIPTION" section above, about how "Carp" decides where the error is reported from.

Use @CARP_NOT, instead of $Carp::CarpLevel.

Overrides "Carp"'s use of @ISA.

%Carp::Internal¶

    $Carp::Internal{ (__PACKAGE__) }++;
    # time passes...
    sub foo { ... or confess("whatever") };

would give a full stack backtrace starting from the first caller outside of __PACKAGE__. (Unless that package was also internal to Perl.)

%Carp::CarpInternal¶

For example "Carp" itself is listed in %Carp::CarpInternal. Therefore the full stack backtrace from "confess" will not start inside of "Carp", and the short message from calling "croak" is not placed on the line where "croak" was called.

$Carp::CarpLevel¶

Therefore it is best to avoid $Carp::CarpLevel. Instead use @CARP_NOT, %Carp::Internal and %Carp::CarpInternal.

Defaults to 0.