NAME

Carp::Trace - simple traceback of call stacks

SYNOPSIS

    use Carp::Trace;

    sub flubber {
        die "You took this route to get here:\n" .
            trace();
    }

DESCRIPTION

Carp::Trace provides an easy way to see the route your script took to get to a certain place. It uses simple caller calls to determine this.

FUNCTIONS

trace( [DEPTH, OFFSET, ARGS] )

trace is a function, exported by default, that gives a simple traceback of how you got where you are. It returns a formatted string, ready to be sent to STDOUT or STDERR.

Optionally, you can provide a DEPTH argument, which tells trace to only go back so many levels. The OFFSET argument will tell trace to skip the first [OFFSET] layers up.

If you provide a true value for the ARGS parameter, the arguments passed to each callstack will be dumped using Data::Dumper. This might slow down your trace, but is very useful for debugging.

See also the "Global Variables" section.

trace is able to tell you the following things:

The name of the function
The number of callstacks from your current location
The context in which the function was called
Whether a new instance of @_ was created for this function
Whether the function was called in an eval, require or use
If called from a string eval, what the eval-string is
The file the function is in
The line number the function is on

The output from the following code:

    use Carp::Trace;

    sub foo { bar() };
    sub bar { $x = baz() };
    sub baz { @y = zot() };
    sub zot { print trace() };

    eval 'foo(1)';

Might look something like this:

    main::(eval) [5]
        foo(1);
        void - no new stash
        x.pl line 1
    main::foo [4]
        void - new stash
        (eval 1) line 1
    main::bar [3]
        void - new stash
        x.pl line 1
    main::baz [2]
        scalar - new stash
        x.pl line 1
    main::zot [1]
        list - new stash
        x.pl line 1