


Devel::StackTraUserpContributed Perl DocumenDevel::StackTrace(3p)


NAME
       Devel::StackTrace - An object representing a stack trace

VERSION
       version 1.26

SYNOPSIS
         use Devel::StackTrace;

         my $trace = Devel::StackTrace->new;

         print $trace->as_string; # like carp

         # from top (most recent) of stack to bottom.
         while (my $frame = $trace->next_frame) {
             print "Has args\n" if $frame->hasargs;
         }

         # from bottom (least recent) of stack to top.
         while (my $frame = $trace->prev_frame) {
             print "Sub: ", $frame->subroutine, "\n";
         }

DESCRIPTION
       The Devel::StackTrace module contains two classes, Devel::StackTrace
       and Devel::StackTrace::Frame.  The goal of this object is to
       encapsulate the information that can found through using the caller()
       function, as well as providing a simple interface to this data.

       The Devel::StackTrace object contains a set of Devel::StackTrace::Frame
       objects, one for each level of the stack.  The frames contain all the
       data available from "caller()".

       This code was created to support my Exception::Class::Base class (part
       of Exception::Class) but may be useful in other contexts.

'TOP' AND 'BOTTOM' OF THE STACK
       When describing the methods of the trace object, I use the words 'top'
       and 'bottom'.  In this context, the 'top' frame on the stack is the
       most recent frame and the 'bottom' is the least recent.

       Here's an example:

         foo();  # bottom frame is here

         sub foo {
            bar();
         }

         sub bar {
            Devel::StackTrace->new;  # top frame is here.
         }





perl v5.12.2                2010-10-15                          1





Devel::StackTraUserpContributed Perl DocumenDevel::StackTrace(3p)


Devel::StackTrace METHODS
       o   Devel::StackTrace->new(%named_params)

           Returns a new Devel::StackTrace object.

           Takes the following parameters:

           o       frame_filter => $sub

                   By default, Devel::StackTrace will include all stack frames
                   before the call to its its constructor.

                   However, you may want to filter out some frames with more
                   granularity than 'ignore_package' or 'ignore_class' allow.

                   You can provide a subroutine which is called with the raw
                   frame data for each frame. This is a hash reference with
                   two keys, "caller", and "args", both of which are array
                   references. The "caller" key is the raw data as returned by
                   Perl's "caller()" function, and the "args" key are the
                   subroutine arguments found in @DB::args.

                   The filter should return true if the frame should be
                   included, or false if it should be skipped.

           o       ignore_package => $package_name OR \@package_names

                   Any frames where the package is one of these packages will
                   not be on the stack.

           o       ignore_class => $package_name OR \@package_names

                   Any frames where the package is a subclass of one of these
                   packages (or is the same package) will not be on the stack.

                   Devel::StackTrace internally adds itself to the
                   'ignore_package' parameter, meaning that the
                   Devel::StackTrace package is ALWAYS ignored.  However, if
                   you create a subclass of Devel::StackTrace it will not be
                   ignored.

           o       no_refs => $boolean

                   If this parameter is true, then Devel::StackTrace will not
                   store references internally when generating stacktrace
                   frames.  This lets your objects go out of scope.

                   Devel::StackTrace replaces any references with their
                   stringified representation.

           o       respect_overload => $boolean

                   By default, Devel::StackTrace will call
                   "overload::AddrRef()" to get the underlying string



perl v5.12.2                2010-10-15                          2





Devel::StackTraUserpContributed Perl DocumenDevel::StackTrace(3p)


                   representation of an object, instead of respecting the
                   object's stringification overloading.  If you would prefer
                   to see the overloaded representation of objects in stack
                   traces, then set this parameter to true.

           o       max_arg_length => $integer

                   By default, Devel::StackTrace will display the entire
                   argument for each subroutine call. Setting this parameter
                   causes it to truncate the argument's string representation
                   if it is longer than this number of characters.

           o       message => $string

                   By default, Devel::StackTrace will use 'Trace begun' as the
                   message for the first stack frame when you call
                   "as_string". You can supply an alternative message using
                   this option.

           o       indent => $boolean

                   If this parameter is true, each stack frame after the first
                   will start with a tab character, just like
                   "Carp::confess()".

       o   $trace->next_frame

           Returns the next Devel::StackTrace::Frame object down on the stack.
           If it hasn't been called before it returns the first frame.  It
           returns undef when it reaches the bottom of the stack and then
           resets its pointer so the next call to "next_frame" or "prev_frame"
           will work properly.

       o   $trace->prev_frame

           Returns the next Devel::StackTrace::Frame object up on the stack.
           If it hasn't been called before it returns the last frame.  It
           returns undef when it reaches the top of the stack and then resets
           its pointer so pointer so the next call to "next_frame" or
           "prev_frame" will work properly.

       o   $trace->reset_pointer

           Resets the pointer so that the next call "next_frame" or
           "prev_frame" will start at the top or bottom of the stack, as
           appropriate.

       o   $trace->frames

           Returns a list of Devel::StackTrace::Frame objects.  The order they
           are returned is from top (most recent) to bottom.

       o   $trace->frame ($index)




perl v5.12.2                2010-10-15                          3





Devel::StackTraUserpContributed Perl DocumenDevel::StackTrace(3p)


           Given an index, returns the relevant frame or undef if there is not
           frame at that index.  The index is exactly like a Perl array.  The
           first frame is 0 and negative indexes are allowed.

       o   $trace->frame_count

           Returns the number of frames in the trace object.

       o   $trace->as_string

           Calls as_string on each frame from top to bottom, producing output
           quite similar to the Carp module's cluck/confess methods.

SUPPORT
       Please submit bugs to the CPAN RT system at
       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Devel%3A%3AStackTrace or
       via email at bug-devel-stacktrace@rt.cpan.org.

AUTHOR
       Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE
       This software is Copyright (c) 2010 by Dave Rolsky.

       This is free software, licensed under:

         The Artistic License 2.0






























perl v5.12.2                2010-10-15                          4


