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

Global Variables

$Carp::Trace::DEPTH

Sets the depth to be used by default for trace. Any depth argument to trace will override this setting.

$Carp::Trace::OFFSET

Sets the offset to be used by default for trace. Any offset argument to trace will override this setting.

$Carp::Trace::ARGUMENTS

Sets a flag to indicate that a trace should dump all arguments for every call stack it's printing out. Any args argument to trace will override this setting.

AUTHOR

This module by Jos Boumans <kane@cpan.org>.

COPYRIGHT

This module is copyright (c) 2002 Jos Boumans <kane@cpan.org>. All rights reserved.

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.