NAME

       Devel::Backtrace::Point - Object oriented access to the information caller() provides

SYNOPSIS

           print Devel::Backtrace::Point->new([caller(0)])->to_long_string;

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.

METHODS

   $p->package, $p->filename, $p->line, $p->subroutine, $p->hasargs, $p->wantarray, $p->evaltext,
       $p->is_require, $p->hints, $p->bitmask, $p->hinthash
       See "caller" in perlfunc for documentation of these fields.

       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 "can" in
       UNIVERSAL:

           Devel::Backtrace::Point->can('hinthash');

   $p->level
       This is the level given to new().  It's intended to be the parameter that was given to
       caller().

   $p->called_package
       This returns the package that $p->subroutine is in.

       If $p->subroutine does not contain '::', then '(unknown)' is returned.  This is the case
       if $p->subroutine is '(eval)'.

   $p->by_index($i)
       You may also access the fields by their index in the list that caller() 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.

   new([caller($i)])
       This constructs a Devel::Backtrace object.  The argument must be a reference to an array
       holding the return values of caller().  This array must have either three or ten elements
       (or eleven if hinthash is supported) (see "caller" in perlfunc).

       Optional additional parameters:

           -format => 'formatstring',
           -level => $i

       The format string will be used as a default for to_string().

       The level should be the parameter that was given to caller() to obtain the caller
       information.

   $tracepoint->to_string()
       Returns a string of the form "Blah::subname called from main (foo.pl:17)".  This means
       that the subroutine "subname" from package "Blah" was called by package "main" in "foo.pl"
       line 17.

       If you print a "Devel::Backtrace::Point" object or otherwise treat it as a string,
       to_string() will be called automatically due to overloading.

       Optional parameters: -format => 'formatstring'

       The format string changes the appearance of the return value.  It can contain %p
       (package), %c (called_package), %f (filename), %l (line), %s (subroutine), %a (hasargs),
       %e (evaltext), %r (is_require), %h (hints), %b (bitmask), %i (level), %I (level, see
       below).

       The difference between %i and %I is that the former is the argument to caller() while the
       latter is actually the index in $backtrace->points().  %i and %I are different if
       "-start", skipme() or skipmysubs() is used in Devel::Backtrace.

       If no format string is given, the one passed to "new" will be used.  If none was given to
       "new", the format string defaults to 'default', which is an abbreviation for "%s called
       from %p (%f:%l)".

       Format strings have been added in Devel-Backtrace-0.10.

   $tracepoint->to_long_string()
       This returns a string which lists all available fields in a table that spans several
       lines.

       Example:

           package: main
           filename: /tmp/foo.pl
           line: 6
           subroutine: main::foo
           hasargs: 1
           wantarray: undef
           evaltext: undef
           is_require: undef
           hints: 0
           bitmask: \00\00\00\00\00\00\00\00\00\00\00\00

       hinthash is not included in the output, as it is a hash.

   FIELDS
       This constant contains a list of all the available field names.  The number of fields
       depends on your perl version.

SEE ALSO

       Devel::Backtrace

AUTHOR

       Christoph Bussenius <pepe@cpan.org>

LICENSE

       This Perl module is in the public domain.

       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.