.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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::Point 3pm"
.TH Devel::Backtrace::Point 3pm "2021-01-07" "perl v5.32.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::Point \- Object oriented access to the information caller()
provides
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    print Devel::Backtrace::Point\->new([caller(0)])\->to_long_string;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is a nice way to access all the information caller provides on a
given level.  It is used by Devel::Backtrace, which generates an array of
all trace points.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$p\->package, $p\->filename, $p\->line, $p\->subroutine, $p\->hasargs, $p\->wantarray, $p\->evaltext, $p\->is_require, $p\->hints, $p\->bitmask, $p\->hinthash"
.el .SS "\f(CW$p\fP\->package, \f(CW$p\fP\->filename, \f(CW$p\fP\->line, \f(CW$p\fP\->subroutine, \f(CW$p\fP\->hasargs, \f(CW$p\fP\->wantarray, \f(CW$p\fP\->evaltext, \f(CW$p\fP\->is_require, \f(CW$p\fP\->hints, \f(CW$p\fP\->bitmask, \f(CW$p\fP\->hinthash"
.IX Subsection "$p->package, $p->filename, $p->line, $p->subroutine, $p->hasargs, $p->wantarray, $p->evaltext, $p->is_require, $p->hints, $p->bitmask, $p->hinthash"
See \*(L"caller\*(R" in perlfunc for documentation of these fields.
.PP
hinthash is only available in perl 5.9 and higher.  When this module is loaded,
it tests how many values caller returns.  Depending on the result, it adds the
necessary accessors.  Thus, you should be able to find out if your perl
supports hinthash by using \*(L"can\*(R" in \s-1UNIVERSAL\s0:
.PP
.Vb 1
\&    Devel::Backtrace::Point\->can(\*(Aqhinthash\*(Aq);
.Ve
.ie n .SS "$p\->level"
.el .SS "\f(CW$p\fP\->level"
.IX Subsection "$p->level"
This is the level given to \fBnew()\fR.  It's intended to be the parameter that was
given to \fBcaller()\fR.
.ie n .SS "$p\->called_package"
.el .SS "\f(CW$p\fP\->called_package"
.IX Subsection "$p->called_package"
This returns the package that \f(CW$p\fR\->subroutine is in.
.PP
If \f(CW$p\fR\->subroutine does not contain '::', then '(unknown)' is returned.  This is
the case if \f(CW$p\fR\->subroutine is '(eval)'.
.ie n .SS "$p\->by_index($i)"
.el .SS "\f(CW$p\fP\->by_index($i)"
.IX Subsection "$p->by_index($i)"
You may also access the fields by their index in the list that \fBcaller()\fR
returns.  This may be useful if some future perl version introduces a new field
for caller, and the author of this module doesn't react in time.
.SS "new([caller($i)])"
.IX Subsection "new([caller($i)])"
This constructs a Devel::Backtrace object.  The argument must be a reference to
an array holding the return values of \fBcaller()\fR.  This array must have either
three or ten elements (or eleven if hinthash is supported) (see
\&\*(L"caller\*(R" in perlfunc).
.PP
Optional additional parameters:
.PP
.Vb 2
\&    \-format => \*(Aqformatstring\*(Aq,
\&    \-level => $i
.Ve
.PP
The format string will be used as a default for \fBto_string()\fR.
.PP
The level should be the parameter that was given to \fBcaller()\fR to obtain the
caller information.
.ie n .SS "$tracepoint\->\fBto_string()\fP"
.el .SS "\f(CW$tracepoint\fP\->\fBto_string()\fP"
.IX Subsection "$tracepoint->to_string()"
Returns a string of the form \*(L"Blah::subname called from main (foo.pl:17)\*(R".
This means that the subroutine \f(CW\*(C`subname\*(C'\fR from package \f(CW\*(C`Blah\*(C'\fR was called by
package \f(CW\*(C`main\*(C'\fR in \f(CW\*(C`foo.pl\*(C'\fR line 17.
.PP
If you print a \f(CW\*(C`Devel::Backtrace::Point\*(C'\fR object or otherwise treat it as a
string, \fBto_string()\fR will be called automatically due to overloading.
.PP
Optional parameters: \-format => 'formatstring'
.PP
The format string changes the appearance of the return value.  It can contain
\&\f(CW%p\fR (package), \f(CW%c\fR (called_package), \f(CW%f\fR (filename), \f(CW%l\fR (line), \f(CW%s\fR
(subroutine), \f(CW%a\fR (hasargs), \f(CW%e\fR (evaltext), \f(CW%r\fR (is_require), \f(CW%h\fR
(hints), \f(CW%b\fR (bitmask), \f(CW%i\fR (level), \f(CW%I\fR (level, see below).
.PP
The difference between \f(CW%i\fR and \f(CW%I\fR is that the former is the argument to
\&\fBcaller()\fR while the latter is actually the index in \f(CW$backtrace\fR\->\fBpoints()\fR.  \f(CW%i\fR
and \f(CW%I\fR are different if \f(CW\*(C`\-start\*(C'\fR, \fBskipme()\fR or \fBskipmysubs()\fR is used in
Devel::Backtrace.
.PP
If no format string is given, the one passed to \f(CW\*(C`new\*(C'\fR will be used.  If none
was given to \f(CW\*(C`new\*(C'\fR, the format string defaults to 'default', which is an
abbreviation for \f(CW\*(C`%s called from %p (%f:%l)\*(C'\fR.
.PP
Format strings have been added in Devel\-Backtrace\-0.10.
.ie n .SS "$tracepoint\->\fBto_long_string()\fP"
.el .SS "\f(CW$tracepoint\fP\->\fBto_long_string()\fP"
.IX Subsection "$tracepoint->to_long_string()"
This returns a string which lists all available fields in a table that spans
several lines.
.PP
Example:
.PP
.Vb 10
\&    package: main
\&    filename: /tmp/foo.pl
\&    line: 6
\&    subroutine: main::foo
\&    hasargs: 1
\&    wantarray: undef
\&    evaltext: undef
\&    is_require: undef
\&    hints: 0
\&    bitmask: \e00\e00\e00\e00\e00\e00\e00\e00\e00\e00\e00\e00
.Ve
.PP
hinthash is not included in the output, as it is a hash.
.SS "\s-1FIELDS\s0"
.IX Subsection "FIELDS"
This constant contains a list of all the available field names.  The number of
fields depends on your perl version.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Devel::Backtrace
.SH "AUTHOR"
.IX Header "AUTHOR"
Christoph Bussenius <pepe@cpan.org>
.SH "LICENSE"
.IX Header "LICENSE"
This Perl 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.