.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Devel::StackTrace 3"
.TH Devel::StackTrace 3 "2009-07-15" "perl v5.8.7" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Devel::StackTrace \- Stack trace and stack trace frame objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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\en" if $frame\->hasargs;
\&  }
\&
\&  # from bottom (least recent) of stack to top.
\&  while (my $frame = $trace\->prev_frame)
\&  {
\&      print "Sub: ", $frame\->subroutine, "\en";
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Devel::StackTrace module contains two classes, Devel::StackTrace
and Devel::StackTraceFrame.  The goal of this object is to encapsulate
the information that can found through using the \fIcaller()\fR function, as
well as providing a simple interface to this data.
.PP
The Devel::StackTrace object contains a set of Devel::StackTraceFrame
objects, one for each level of the stack.  The frames contain all the
data available from \f(CW\*(C`caller()\*(C'\fR.
.PP
This code was created to support my Exception::Class::Base class
(part of Exception::Class) but may be useful in other contexts.
.SH "'TOP' AND 'BOTTOM' OF THE STACK"
.IX Header "'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.
.PP
Here's an example:
.PP
.Vb 1
\&  foo();  # bottom frame is here
\&
\&  sub foo
\&  {
\&     bar();
\&  }
\&
\&  sub bar
\&  {
\&     Devel::StackTrace\->new;  # top frame is here.
\&  }
.Ve
.SH "Devel::StackTrace METHODS"
.IX Header "Devel::StackTrace METHODS"
.IP "\(bu" 4
Devel::StackTrace\->new(%named_params)
.Sp
Returns a new Devel::StackTrace object.
.Sp
Takes the following parameters:
.RS 4
.IP "\(bu" 8
frame_filter => \f(CW$sub\fR
.Sp
By default, Devel::StackTrace will include all stack frames before the
call to its its constructor.
.Sp
However, you may want to filter out some frames with more granularity
than 'ignore_package' or 'ignore_class' allow.
.Sp
You can provide a subroutine which is called with the raw frame data
for each frame. This is a hash reference with two keys, \*(L"caller\*(R", and
\&\*(L"args\*(R", both of which are array references. The \*(L"caller\*(R" key is the
raw data as returned by Perl's \f(CW\*(C`caller()\*(C'\fR function, and the \*(L"args\*(R"
key are the subroutine arguments found in \f(CW@DB::args\fR.
.Sp
The filter should return true if the frame should be included, or
false if it should be skipped.
.IP "\(bu" 8
ignore_package => \f(CW$package_name\fR \s-1OR\s0 \e@package_names
.Sp
Any frames where the package is one of these packages will not be on
the stack.
.IP "\(bu" 8
ignore_class => \f(CW$package_name\fR \s-1OR\s0 \e@package_names
.Sp
Any frames where the package is a subclass of one of these packages
(or is the same package) will not be on the stack.
.Sp
Devel::StackTrace internally adds itself to the 'ignore_package'
parameter, meaning that the Devel::StackTrace package is \fB\s-1ALWAYS\s0\fR
ignored.  However, if you create a subclass of Devel::StackTrace it
will not be ignored.
.IP "\(bu" 8
no_refs => \f(CW$boolean\fR
.Sp
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.
.Sp
Devel::StackTrace replaces any references with their stringified
representation.
.IP "\(bu" 8
respect_overload => \f(CW$boolean\fR
.Sp
By default, Devel::StackTrace will call \f(CW\*(C`overload::AddrRef()\*(C'\fR to get
the underlying string 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.
.IP "\(bu" 8
max_arg_length => \f(CW$integer\fR
.Sp
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.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\f(CW$trace\fR\->next_frame
.Sp
Returns the next Devel::StackTraceFrame 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 \f(CW\*(C`next_frame\*(C'\fR or \f(CW\*(C`prev_frame\*(C'\fR will work
properly.
.IP "\(bu" 4
\&\f(CW$trace\fR\->prev_frame
.Sp
Returns the next Devel::StackTraceFrame 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 \f(CW\*(C`next_frame\*(C'\fR or \f(CW\*(C`prev_frame\*(C'\fR will work
properly.
.IP "\(bu" 4
\&\f(CW$trace\fR\->reset_pointer
.Sp
Resets the pointer so that the next call \f(CW\*(C`next_frame\*(C'\fR or
\&\f(CW\*(C`prev_frame\*(C'\fR will start at the top or bottom of the stack, as
appropriate.
.IP "\(bu" 4
\&\f(CW$trace\fR\->frames
.Sp
Returns a list of Devel::StackTraceFrame objects.  The order they are
returned is from top (most recent) to bottom.
.IP "\(bu" 4
\&\f(CW$trace\fR\->frame ($index)
.Sp
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.
.IP "\(bu" 4
\&\f(CW$trace\fR\->frame_count
.Sp
Returns the number of frames in the trace object.
.IP "\(bu" 4
\&\f(CW$trace\fR\->as_string
.Sp
Calls as_string on each frame from top to bottom, producing output
quite similar to the Carp module's cluck/confess methods.
.SH "Devel::StackTraceFrame METHODS"
.IX Header "Devel::StackTraceFrame METHODS"
See the caller documentation for more information on what these
methods return.
.IP "\(bu" 4
\&\f(CW$frame\fR\->package
.IP "\(bu" 4
\&\f(CW$frame\fR\->filename
.IP "\(bu" 4
\&\f(CW$frame\fR\->line
.IP "\(bu" 4
\&\f(CW$frame\fR\->subroutine
.IP "\(bu" 4
\&\f(CW$frame\fR\->hasargs
.IP "\(bu" 4
\&\f(CW$frame\fR\->wantarray
.IP "\(bu" 4
\&\f(CW$frame\fR\->evaltext
.Sp
Returns undef if the frame was not part of an eval.
.IP "\(bu" 4
\&\f(CW$frame\fR\->is_require
.Sp
Returns undef if the frame was not part of a require.
.IP "\(bu" 4
\&\f(CW$frame\fR\->args
.Sp
Returns the arguments passed to the frame.  Note that any arguments
that are references are returned as references, not copies.
.IP "\(bu" 4
\&\f(CW$frame\fR\->hints
.IP "\(bu" 4
\&\f(CW$frame\fR\->bitmask
.SH "SUPPORT"
.IX Header "SUPPORT"
Please submit bugs to the \s-1CPAN\s0 \s-1RT\s0 system at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Devel%3A%3AStackTrace
or via email at bug\-devel\-stacktrace@rt.cpan.org.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky, <autarch@urth.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2000\-2006 David Rolsky.  All rights reserved.  This
program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
The full text of the license can be found in the \s-1LICENSE\s0 file included
with this module.