1Devel::StackTrace(3)  User Contributed Perl Documentation Devel::StackTrace(3)
2
3
4

NAME

6       Devel::StackTrace - An object representing a stack trace
7

VERSION

9       version 2.04
10

SYNOPSIS

12         use Devel::StackTrace;
13
14         my $trace = Devel::StackTrace->new;
15
16         print $trace->as_string; # like carp
17
18         # from top (most recent) of stack to bottom.
19         while ( my $frame = $trace->next_frame ) {
20             print "Has args\n" if $frame->hasargs;
21         }
22
23         # from bottom (least recent) of stack to top.
24         while ( my $frame = $trace->prev_frame ) {
25             print "Sub: ", $frame->subroutine, "\n";
26         }
27

DESCRIPTION

29       The "Devel::StackTrace" module contains two classes,
30       "Devel::StackTrace" and Devel::StackTrace::Frame. These objects
31       encapsulate the information that can retrieved via Perl's "caller"
32       function, as well as providing a simple interface to this data.
33
34       The "Devel::StackTrace" object contains a set of
35       "Devel::StackTrace::Frame" objects, one for each level of the stack.
36       The frames contain all the data available from "caller".
37
38       This code was created to support my Exception::Class::Base class (part
39       of Exception::Class) but may be useful in other contexts.
40

'TOP' AND 'BOTTOM' OF THE STACK

42       When describing the methods of the trace object, I use the words 'top'
43       and 'bottom'. In this context, the 'top' frame on the stack is the most
44       recent frame and the 'bottom' is the least recent.
45
46       Here's an example:
47
48         foo();  # bottom frame is here
49
50         sub foo {
51            bar();
52         }
53
54         sub bar {
55            Devel::StackTrace->new;  # top frame is here.
56         }
57

METHODS

59       This class provide the following methods:
60
61   Devel::StackTrace->new(%named_params)
62       Returns a new Devel::StackTrace object.
63
64       Takes the following parameters:
65
66       •   frame_filter => $sub
67
68           By default, Devel::StackTrace will include all stack frames before
69           the call to its constructor.
70
71           However, you may want to filter out some frames with more
72           granularity than 'ignore_package' or 'ignore_class' allow.
73
74           You can provide a subroutine which is called with the raw frame
75           data for each frame. This is a hash reference with two keys,
76           "caller", and "args", both of which are array references. The
77           "caller" key is the raw data as returned by Perl's "caller"
78           function, and the "args" key are the subroutine arguments found in
79           @DB::args.
80
81           The filter should return true if the frame should be included, or
82           false if it should be skipped.
83
84       •   filter_frames_early => $boolean
85
86           If this parameter is true, "frame_filter" will be called as soon as
87           the stacktrace is created, and before refs are stringified (if
88           "unsafe_ref_capture" is not set), rather than being filtered lazily
89           when Devel::StackTrace::Frame objects are first needed.
90
91           This is useful if you want to filter based on the frame's arguments
92           and want to be able to examine object properties, for example.
93
94       •   ignore_package => $package_name OR \@package_names
95
96           Any frames where the package is one of these packages will not be
97           on the stack.
98
99       •   ignore_class => $package_name OR \@package_names
100
101           Any frames where the package is a subclass of one of these packages
102           (or is the same package) will not be on the stack.
103
104           Devel::StackTrace internally adds itself to the 'ignore_package'
105           parameter, meaning that the Devel::StackTrace package is ALWAYS
106           ignored. However, if you create a subclass of Devel::StackTrace it
107           will not be ignored.
108
109       •   skip_frames => $integer
110
111           This will cause this number of stack frames to be excluded from top
112           of the stack trace. This prevents the frames from being captured at
113           all, and applies before the "frame_filter", "ignore_package", or
114           "ignore_class" options, even with "filter_frames_early".
115
116       •   unsafe_ref_capture => $boolean
117
118           If this parameter is true, then Devel::StackTrace will store
119           references internally when generating stacktrace frames.
120
121           This option is very dangerous, and should never be used with
122           exception objects. Using this option will keep any objects or
123           references alive past their normal lifetime, until the stack trace
124           object goes out of scope. It can keep objects alive even after
125           their "DESTROY" sub is called, resulting it it being called
126           multiple times on the same object.
127
128           If not set, Devel::StackTrace replaces any references with their
129           stringified representation.
130
131       •   no_args => $boolean
132
133           If this parameter is true, then Devel::StackTrace will not store
134           caller arguments in stack trace frames at all.
135
136       •   respect_overload => $boolean
137
138           By default, Devel::StackTrace will call "overload::AddrRef" to get
139           the underlying string representation of an object, instead of
140           respecting the object's stringification overloading. If you would
141           prefer to see the overloaded representation of objects in stack
142           traces, then set this parameter to true.
143
144       •   max_arg_length => $integer
145
146           By default, Devel::StackTrace will display the entire argument for
147           each subroutine call. Setting this parameter causes truncates each
148           subroutine argument's string representation if it is longer than
149           this number of characters.
150
151       •   message => $string
152
153           By default, Devel::StackTrace will use 'Trace begun' as the message
154           for the first stack frame when you call "as_string". You can supply
155           an alternative message using this option.
156
157       •   indent => $boolean
158
159           If this parameter is true, each stack frame after the first will
160           start with a tab character, just like "Carp::confess".
161
162   $trace->next_frame
163       Returns the next Devel::StackTrace::Frame object on the stack, going
164       down. If this method hasn't been called before it returns the first
165       frame. It returns "undef" when it reaches the bottom of the stack and
166       then resets its pointer so the next call to "$trace->next_frame" or
167       "$trace->prev_frame" will work properly.
168
169   $trace->prev_frame
170       Returns the next Devel::StackTrace::Frame object on the stack, going
171       up. If this method hasn't been called before it returns the last frame.
172       It returns undef when it reaches the top of the stack and then resets
173       its pointer so the next call to "$trace->next_frame" or
174       "$trace->prev_frame" will work properly.
175
176   $trace->reset_pointer
177       Resets the pointer so that the next call to "$trace->next_frame" or
178       "$trace->prev_frame" will start at the top or bottom of the stack, as
179       appropriate.
180
181   $trace->frames
182       When this method is called with no arguments, it returns a list of
183       Devel::StackTrace::Frame objects. They are returned in order from top
184       (most recent) to bottom.
185
186       This method can also be used to set the object's frames if you pass it
187       a list of Devel::StackTrace::Frame objects.
188
189       This is useful if you want to filter the list of frames in ways that
190       are more complex than can be handled by the "$trace->filter_frames"
191       method:
192
193         $stacktrace->frames( my_filter( $stacktrace->frames ) );
194
195   $trace->frame($index)
196       Given an index, this method returns the relevant frame, or undef if
197       there is no frame at that index. The index is exactly like a Perl
198       array. The first frame is 0 and negative indexes are allowed.
199
200   $trace->frame_count
201       Returns the number of frames in the trace object.
202
203   $trace->as_string(\%p)
204       Calls "$frame->as_string" on each frame from top to bottom, producing
205       output quite similar to the Carp module's cluck/confess methods.
206
207       The optional "\%p" parameter only has one option. The "max_arg_length"
208       parameter truncates each subroutine argument's string representation if
209       it is longer than this number of characters.
210
211       If all the frames in a trace are skipped then this just returns the
212       "message" passed to the constructor or the string "Trace begun".
213
214   $trace->message
215       Returns the message passed to the constructor. If this wasn't passed
216       then this method returns "undef".
217

SUPPORT

219       Bugs may be submitted at
220       <https://github.com/houseabsolute/Devel-StackTrace/issues>.
221
222       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
223

SOURCE

225       The source code repository for Devel-StackTrace can be found at
226       <https://github.com/houseabsolute/Devel-StackTrace>.
227

DONATIONS

229       If you'd like to thank me for the work I've done on this module, please
230       consider making a "donation" to me via PayPal. I spend a lot of free
231       time creating free software, and would appreciate any support you'd
232       care to offer.
233
234       Please note that I am not suggesting that you must do this in order for
235       me to continue working on this particular software. I will continue to
236       do so, inasmuch as I have in the past, for as long as it interests me.
237
238       Similarly, a donation made in this way will probably not make me work
239       on this software much more, unless I get so many donations that I can
240       consider working on free software full time (let's all have a chuckle
241       at that together).
242
243       To donate, log into PayPal and send money to autarch@urth.org, or use
244       the button at <http://www.urth.org/~autarch/fs-donation.html>.
245

AUTHOR

247       Dave Rolsky <autarch@urth.org>
248

CONTRIBUTORS

250       •   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
251
252       •   David Cantrell <david@cantrell.org.uk>
253
254       •   Graham Knop <haarg@haarg.org>
255
256       •   Ivan Bessarabov <ivan@bessarabov.ru>
257
258       •   Mark Fowler <mark@twoshortplanks.com>
259
260       •   Pali <pali@cpan.org>
261
262       •   Ricardo Signes <rjbs@cpan.org>
263
265       This software is Copyright (c) 2000 - 2019 by David Rolsky.
266
267       This is free software, licensed under:
268
269         The Artistic License 2.0 (GPL Compatible)
270
271       The full text of the license can be found in the LICENSE file included
272       with this distribution.
273
274
275
276perl v5.34.0                      2022-01-21              Devel::StackTrace(3)
Impressum