|
Packit |
985e12 |
# NAME
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Devel::StackTrace - An object representing a stack trace
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# VERSION
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
version 2.03
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# SYNOPSIS
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
use Devel::StackTrace;
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
my $trace = Devel::StackTrace->new;
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
print $trace->as_string; # like carp
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# from top (most recent) of stack to bottom.
|
|
Packit |
985e12 |
while ( my $frame = $trace->next_frame ) {
|
|
Packit |
985e12 |
print "Has args\n" if $frame->hasargs;
|
|
Packit |
985e12 |
}
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# from bottom (least recent) of stack to top.
|
|
Packit |
985e12 |
while ( my $frame = $trace->prev_frame ) {
|
|
Packit |
985e12 |
print "Sub: ", $frame->subroutine, "\n";
|
|
Packit |
985e12 |
}
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# DESCRIPTION
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
The `Devel::StackTrace` module contains two classes, `Devel::StackTrace` and
|
|
Packit |
985e12 |
[Devel::StackTrace::Frame](https://metacpan.org/pod/Devel::StackTrace::Frame). These objects encapsulate the information that
|
|
Packit |
985e12 |
can retrieved via Perl's `caller` function, as well as providing a simple
|
|
Packit |
985e12 |
interface to this data.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
The `Devel::StackTrace` object contains a set of `Devel::StackTrace::Frame`
|
|
Packit |
985e12 |
objects, one for each level of the stack. The frames contain all the data
|
|
Packit |
985e12 |
available from `caller`.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
This code was created to support my [Exception::Class::Base](https://metacpan.org/pod/Exception::Class::Base) class (part of
|
|
Packit |
985e12 |
[Exception::Class](https://metacpan.org/pod/Exception::Class)) but may be useful in other contexts.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# 'TOP' AND 'BOTTOM' OF THE STACK
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
When describing the methods of the trace object, I use the words 'top' and
|
|
Packit |
985e12 |
'bottom'. In this context, the 'top' frame on the stack is the most recent
|
|
Packit |
985e12 |
frame and the 'bottom' is the least recent.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Here's an example:
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
foo(); # bottom frame is here
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
sub foo {
|
|
Packit |
985e12 |
bar();
|
|
Packit |
985e12 |
}
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
sub bar {
|
|
Packit |
985e12 |
Devel::StackTrace->new; # top frame is here.
|
|
Packit |
985e12 |
}
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# METHODS
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
This class provide the following methods:
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
## Devel::StackTrace->new(%named\_params)
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Returns a new Devel::StackTrace object.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Takes the following parameters:
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- frame\_filter => $sub
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
By default, Devel::StackTrace will include all stack frames before the call to
|
|
Packit |
985e12 |
its constructor.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
However, you may want to filter out some frames with more granularity than
|
|
Packit |
985e12 |
'ignore\_package' or 'ignore\_class' allow.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
You can provide a subroutine which is called with the raw frame data for each
|
|
Packit |
985e12 |
frame. This is a hash reference with two keys, "caller", and "args", both of
|
|
Packit |
985e12 |
which are array references. The "caller" key is the raw data as returned by
|
|
Packit |
985e12 |
Perl's `caller` function, and the "args" key are the subroutine arguments
|
|
Packit |
985e12 |
found in `@DB::args`.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
The filter should return true if the frame should be included, or false if it
|
|
Packit |
985e12 |
should be skipped.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- filter\_frames\_early => $boolean
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
If this parameter is true, `frame_filter` will be called as soon as the
|
|
Packit |
985e12 |
stacktrace is created, and before refs are stringified (if
|
|
Packit |
985e12 |
`unsafe_ref_capture` is not set), rather than being filtered lazily when
|
|
Packit |
985e12 |
[Devel::StackTrace::Frame](https://metacpan.org/pod/Devel::StackTrace::Frame) objects are first needed.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
This is useful if you want to filter based on the frame's arguments and want
|
|
Packit |
985e12 |
to be able to examine object properties, for example.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- ignore\_package => $package\_name OR \\@package\_names
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Any frames where the package is one of these packages will not be on the
|
|
Packit |
985e12 |
stack.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- ignore\_class => $package\_name OR \\@package\_names
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Any frames where the package is a subclass of one of these packages (or is the
|
|
Packit |
985e12 |
same package) will not be on the stack.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Devel::StackTrace internally adds itself to the 'ignore\_package' parameter,
|
|
Packit |
985e12 |
meaning that the Devel::StackTrace package is **ALWAYS** ignored. However, if
|
|
Packit |
985e12 |
you create a subclass of Devel::StackTrace it will not be ignored.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- skip\_frames => $integer
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
This will cause this number of stack frames to be excluded from top of the
|
|
Packit |
985e12 |
stack trace. This prevents the frames from being captured at all, and applies
|
|
Packit |
985e12 |
before the `frame_filter`, `ignore_package`, or `ignore_class` options,
|
|
Packit |
985e12 |
even with `filter_frames_early`.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- unsafe\_ref\_capture => $boolean
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
If this parameter is true, then Devel::StackTrace will store references
|
|
Packit |
985e12 |
internally when generating stacktrace frames.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
**This option is very dangerous, and should never be used with exception
|
|
Packit |
985e12 |
objects**. Using this option will keep any objects or references alive past
|
|
Packit |
985e12 |
their normal lifetime, until the stack trace object goes out of scope. It can
|
|
Packit |
985e12 |
keep objects alive even after their `DESTROY` sub is called, resulting it it
|
|
Packit |
985e12 |
being called multiple times on the same object.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
If not set, Devel::StackTrace replaces any references with their stringified
|
|
Packit |
985e12 |
representation.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- no\_args => $boolean
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
If this parameter is true, then Devel::StackTrace will not store caller
|
|
Packit |
985e12 |
arguments in stack trace frames at all.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- respect\_overload => $boolean
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
By default, Devel::StackTrace will call `overload::AddrRef` to get the
|
|
Packit |
985e12 |
underlying string representation of an object, instead of respecting the
|
|
Packit |
985e12 |
object's stringification overloading. If you would prefer to see the
|
|
Packit |
985e12 |
overloaded representation of objects in stack traces, then set this parameter
|
|
Packit |
985e12 |
to true.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- max\_arg\_length => $integer
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
By default, Devel::StackTrace will display the entire argument for each
|
|
Packit |
985e12 |
subroutine call. Setting this parameter causes truncates each subroutine
|
|
Packit |
985e12 |
argument's string representation if it is longer than this number of
|
|
Packit |
985e12 |
characters.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- message => $string
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
By default, Devel::StackTrace will use 'Trace begun' as the message for the
|
|
Packit |
985e12 |
first stack frame when you call `as_string`. You can supply an alternative
|
|
Packit |
985e12 |
message using this option.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- indent => $boolean
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
If this parameter is true, each stack frame after the first will start with a
|
|
Packit |
985e12 |
tab character, just like `Carp::confess`.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
## $trace->next\_frame
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Returns the next [Devel::StackTrace::Frame](https://metacpan.org/pod/Devel::StackTrace::Frame) object on the stack, going
|
|
Packit |
985e12 |
down. If this method hasn't been called before it returns the first frame. It
|
|
Packit |
985e12 |
returns `undef` when it reaches the bottom of the stack and then resets its
|
|
Packit |
985e12 |
pointer so the next call to `$trace->next_frame` or `$trace->prev_frame` will work properly.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
## $trace->prev\_frame
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Returns the next [Devel::StackTrace::Frame](https://metacpan.org/pod/Devel::StackTrace::Frame) object on the stack, going up. If
|
|
Packit |
985e12 |
this method hasn't been called before it returns the last frame. It returns
|
|
Packit |
985e12 |
undef when it reaches the top of the stack and then resets its pointer so the
|
|
Packit |
985e12 |
next call to `$trace->next_frame` or `$trace->prev_frame` will work
|
|
Packit |
985e12 |
properly.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
## $trace->reset\_pointer
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Resets the pointer so that the next call to `$trace->next_frame` or `$trace->prev_frame` will start at the top or bottom of the stack, as
|
|
Packit |
985e12 |
appropriate.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
## $trace->frames
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
When this method is called with no arguments, it returns a list of
|
|
Packit |
985e12 |
[Devel::StackTrace::Frame](https://metacpan.org/pod/Devel::StackTrace::Frame) objects. They are returned in order from top (most
|
|
Packit |
985e12 |
recent) to bottom.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
This method can also be used to set the object's frames if you pass it a list
|
|
Packit |
985e12 |
of [Devel::StackTrace::Frame](https://metacpan.org/pod/Devel::StackTrace::Frame) objects.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
This is useful if you want to filter the list of frames in ways that are more
|
|
Packit |
985e12 |
complex than can be handled by the `$trace->filter_frames` method:
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
$stacktrace->frames( my_filter( $stacktrace->frames ) );
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
## $trace->frame($index)
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Given an index, this method returns the relevant frame, or undef if there is
|
|
Packit |
985e12 |
no frame at that index. The index is exactly like a Perl array. The first
|
|
Packit |
985e12 |
frame is 0 and negative indexes are allowed.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
## $trace->frame\_count
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Returns the number of frames in the trace object.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
## $trace->as\_string(\\%p)
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Calls `$frame->as_string` on each frame from top to bottom, producing
|
|
Packit |
985e12 |
output quite similar to the Carp module's cluck/confess methods.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
The optional `\%p` parameter only has one option. The `max_arg_length`
|
|
Packit |
985e12 |
parameter truncates each subroutine argument's string representation if it is
|
|
Packit |
985e12 |
longer than this number of characters.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
If all the frames in a trace are skipped then this just returns the `message`
|
|
Packit |
985e12 |
passed to the constructor or the string `"Trace begun"`.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
## $trace->message
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Returns the message passed to the constructor. If this wasn't passed then this
|
|
Packit |
985e12 |
method returns `undef`.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# SUPPORT
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Bugs may be submitted at [https://github.com/houseabsolute/Devel-StackTrace/issues](https://github.com/houseabsolute/Devel-StackTrace/issues).
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
I am also usually active on IRC as 'autarch' on `irc://irc.perl.org`.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# SOURCE
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
The source code repository for Devel-StackTrace can be found at [https://github.com/houseabsolute/Devel-StackTrace](https://github.com/houseabsolute/Devel-StackTrace).
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# DONATIONS
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
If you'd like to thank me for the work I've done on this module, please
|
|
Packit |
985e12 |
consider making a "donation" to me via PayPal. I spend a lot of free time
|
|
Packit |
985e12 |
creating free software, and would appreciate any support you'd care to offer.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Please note that **I am not suggesting that you must do this** in order for me
|
|
Packit |
985e12 |
to continue working on this particular software. I will continue to do so,
|
|
Packit |
985e12 |
inasmuch as I have in the past, for as long as it interests me.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Similarly, a donation made in this way will probably not make me work on this
|
|
Packit |
985e12 |
software much more, unless I get so many donations that I can consider working
|
|
Packit |
985e12 |
on free software full time (let's all have a chuckle at that together).
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
To donate, log into PayPal and send money to autarch@urth.org, or use the
|
|
Packit |
985e12 |
button at [http://www.urth.org/~autarch/fs-donation.html](http://www.urth.org/~autarch/fs-donation.html).
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# AUTHOR
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
Dave Rolsky <autarch@urth.org>
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# CONTRIBUTORS
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
- Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
|
|
Packit |
985e12 |
- David Cantrell <david@cantrell.org.uk>
|
|
Packit |
985e12 |
- Graham Knop <haarg@haarg.org>
|
|
Packit |
985e12 |
- Ivan Bessarabov <ivan@bessarabov.ru>
|
|
Packit |
985e12 |
- Mark Fowler <mark@twoshortplanks.com>
|
|
Packit |
985e12 |
- Ricardo Signes <rjbs@cpan.org>
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
# COPYRIGHT AND LICENSE
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
This software is Copyright (c) 2000 - 2017 by David Rolsky.
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
This is free software, licensed under:
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
The Artistic License 2.0 (GPL Compatible)
|
|
Packit |
985e12 |
|
|
Packit |
985e12 |
The full text of the license can be found in the
|
|
Packit |
985e12 |
`LICENSE` file included with this distribution.
|