.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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::Backtrace 3pm"
.TH Devel::Backtrace 3pm "2022-06-13" "perl v5.34.0" "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::Backtrace \- Object\-oriented backtrace
.SH "VERSION"
.IX Header "VERSION"
This is version 0.12.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    my $backtrace = Devel::Backtrace\->new;
\&
\&    print $backtrace; # use automatic stringification
\&                      # See EXAMPLES to see what the output might look like
\&
\&    print $backtrace\->point(0)\->line;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "Devel::Backtrace\->\fBnew()\fP"
.IX Subsection "Devel::Backtrace->new()"
Optional parameters: \-start => \f(CW$start\fR, \-format => \f(CW$format\fR
.PP
If only one parameter is given, it will be used as \f(CW$start\fR.
.PP
Constructs a new \f(CW\*(C`Devel::Backtrace\*(C'\fR which is filled with all the information
\&\f(CW\*(C`caller($i)\*(C'\fR provides, where \f(CW$i\fR starts from \f(CW$start\fR.  If no argument is
given, \f(CW$start\fR defaults to 0.
.PP
If \f(CW$start\fR is 1 (or higher), the backtrace won't contain the information that
(and where) \fBDevel::Backtrace::new()\fR was called.
.ie n .SS "$backtrace\->point($i)"
.el .SS "\f(CW$backtrace\fP\->point($i)"
.IX Subsection "$backtrace->point($i)"
Returns the i'th tracepoint as a Devel::Backtrace::Point object (see its documentation
for how to access every bit of information).
.PP
Note that the following code snippet will print the information of
\&\f(CW\*(C`caller($start+$i)\*(C'\fR:
.PP
.Vb 1
\&    print Devel::Backtrace\->new($start)\->point($i)
.Ve
.ie n .SS "$backtrace\->\fBpoints()\fP"
.el .SS "\f(CW$backtrace\fP\->\fBpoints()\fP"
.IX Subsection "$backtrace->points()"
Returns a list of all tracepoints.  In scalar context, the number of
tracepoints is returned.
.ie n .SS "$backtrace\->skipme([$package])"
.el .SS "\f(CW$backtrace\fP\->skipme([$package])"
.IX Subsection "$backtrace->skipme([$package])"
This method deletes all leading tracepoints that contain information about calls
within \f(CW$package\fR.  Afterwards the \f(CW$backtrace\fR will look as though it had
been created with a higher value of \f(CW$start\fR.
.PP
If the optional parameter \f(CW$package\fR is not given, it defaults to the calling
package.
.PP
The effect is similar to what the Carp module does.
.PP
This module ships with an example \*(L"skipme.pl\*(R" that demonstrates how to use this
method.  See also \*(L"\s-1EXAMPLES\*(R"\s0.
.ie n .SS "$backtrace\->skipmysubs([$package])"
.el .SS "\f(CW$backtrace\fP\->skipmysubs([$package])"
.IX Subsection "$backtrace->skipmysubs([$package])"
This method is like \f(CW\*(C`skipme\*(C'\fR except that it deletes calls \fIto\fR the package
rather than calls \fIfrom\fR the package.
.PP
Before discarding those calls, \f(CW\*(C`skipme\*(C'\fR is called.  This is because usually
the topmost call in the stack is to Devel::Backtrace\->new, which would not be
catched by \f(CW\*(C`skipmysubs\*(C'\fR otherwise.
.PP
This means that skipmysubs usually deletes more lines than skipme would.
.PP
\&\f(CW\*(C`skipmysubs\*(C'\fR was added in Devel::Backtrace version 0.06.
.PP
See also \*(L"\s-1EXAMPLES\*(R"\s0 and the example \*(L"skipme.pl\*(R".
.ie n .SS "$backtrace\->\fBto_string()\fP"
.el .SS "\f(CW$backtrace\fP\->\fBto_string()\fP"
.IX Subsection "$backtrace->to_string()"
Returns a string that contains one line for each tracepoint.  It will contain
the information from \f(CW\*(C`Devel::Backtrace::Point\*(C'\fR's \fBto_string()\fR method.  To get
more information, use the \fBto_long_string()\fR method.
.PP
Note that you don't have to call \fBto_string()\fR if you print a \f(CW\*(C`Devel::Backtrace\*(C'\fR
object or otherwise treat it as a string, as the stringification operator is
overloaded.
.PP
See \*(L"\s-1EXAMPLES\*(R"\s0.
.ie n .SS "$backtrace\->\fBto_long_string()\fP"
.el .SS "\f(CW$backtrace\fP\->\fBto_long_string()\fP"
.IX Subsection "$backtrace->to_long_string()"
Returns a very long string that contains several lines for each trace point.
The result will contain every available bit of information.  See
\&\*(L"to_long_string\*(R" in Devel::Backtrace::Point for an example of what the result
looks like.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
A sample stringification might look like this:
.PP
.Vb 5
\&    Devel::Backtrace::new called from MyPackage (foo.pl:30)
\&    MyPackage::test2 called from MyPackage (foo.pl:28)
\&    MyPackage::test1 called from main (foo.pl:18)
\&    main::bar called from main (foo.pl:6)
\&    main::foo called from main (foo.pl:13)
.Ve
.PP
If MyPackage called skipme, the first two lines would be removed.  If it called
skipmysubs, the first three lines would be removed.
.PP
If you don't like the format, you can change it:
.PP
.Vb 1
\&    my $backtrace = Devel::Backtrace\->new(\-format => \*(Aq%I. %s\*(Aq);
.Ve
.PP
This would produce a stringification of the following form:
.PP
.Vb 5
\&    0. Devel::Backtrace::new
\&    1. MyPackage::test2
\&    2. MyPackage::test1
\&    3. main::bar
\&    4. main::foo
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Devel::StackTrace does mostly the same as this module.  I'm afraid I hadn't
noticed it until I uploaded this module.
.PP
Carp::Trace is a simpler module which gives you a backtrace in string form.
.PP
Devel::DollarAt comes with this distribution and is a nice application of
this module.  You can use it for debugging to get a backtrace out of $@.
.SH "AUTHOR"
.IX Header "AUTHOR"
Christoph Bussenius <pepe@cpan.org>
.PP
If you use this module, I'll be glad if you drop me a note.
You should mention this module's name in the subject of your mails, in order to
make sure they won't get lost in all the spam.
.SH "LICENSE"
.IX Header "LICENSE"
This module is in the public domain.
.PP
If your country's law does not allow this module being in the public
domain or does not include the concept of public domain, you may use the
module under the same terms as perl itself.