README
1NAME
2 Devel::Backtrace - Object-oriented backtrace
3
4VERSION
5 This is version 0.12.
6
7SYNOPSIS
8 my $backtrace = Devel::Backtrace->new;
9
10 print $backtrace; # use automatic stringification
11 # See EXAMPLES to see what the output might look like
12
13 print $backtrace->point(0)->line;
14
15METHODS
16 Devel::Backtrace->new()
17 Optional parameters: -start => $start, -format => $format
18
19 If only one parameter is given, it will be used as $start.
20
21 Constructs a new "Devel::Backtrace" which is filled with all the
22 information "caller($i)" provides, where $i starts from $start. If no
23 argument is given, $start defaults to 0.
24
25 If $start is 1 (or higher), the backtrace won't contain the information
26 that (and where) Devel::Backtrace::new() was called.
27
28 $backtrace->point($i)
29 Returns the i'th tracepoint as a Devel::Backtrace::Point object (see its
30 documentation for how to access every bit of information).
31
32 Note that the following code snippet will print the information of
33 "caller($start+$i)":
34
35 print Devel::Backtrace->new($start)->point($i)
36
37 $backtrace->points()
38 Returns a list of all tracepoints. In scalar context, the number of
39 tracepoints is returned.
40
41 $backtrace->skipme([$package])
42 This method deletes all leading tracepoints that contain information
43 about calls within $package. Afterwards the $backtrace will look as
44 though it had been created with a higher value of $start.
45
46 If the optional parameter $package is not given, it defaults to the
47 calling package.
48
49 The effect is similar to what the Carp module does.
50
51 This module ships with an example "skipme.pl" that demonstrates how to
52 use this method. See also "EXAMPLES".
53
54 $backtrace->skipmysubs([$package])
55 This method is like "skipme" except that it deletes calls *to* the
56 package rather than calls *from* the package.
57
58 Before discarding those calls, "skipme" is called. This is because
59 usually the topmost call in the stack is to Devel::Backtrace->new, which
60 would not be catched by "skipmysubs" otherwise.
61
62 This means that skipmysubs usually deletes more lines than skipme would.
63
64 "skipmysubs" was added in Devel::Backtrace version 0.06.
65
66 See also "EXAMPLES" and the example "skipme.pl".
67
68 $backtrace->to_string()
69 Returns a string that contains one line for each tracepoint. It will
70 contain the information from "Devel::Backtrace::Point"'s to_string()
71 method. To get more information, use the to_long_string() method.
72
73 Note that you don't have to call to_string() if you print a
74 "Devel::Backtrace" object or otherwise treat it as a string, as the
75 stringification operator is overloaded.
76
77 See "EXAMPLES".
78
79 $backtrace->to_long_string()
80 Returns a very long string that contains several lines for each trace
81 point. The result will contain every available bit of information. See
82 "to_long_string" in Devel::Backtrace::Point for an example of what the
83 result looks like.
84
85EXAMPLES
86 A sample stringification might look like this:
87
88 Devel::Backtrace::new called from MyPackage (foo.pl:30)
89 MyPackage::test2 called from MyPackage (foo.pl:28)
90 MyPackage::test1 called from main (foo.pl:18)
91 main::bar called from main (foo.pl:6)
92 main::foo called from main (foo.pl:13)
93
94 If MyPackage called skipme, the first two lines would be removed. If it
95 called skipmysubs, the first three lines would be removed.
96
97 If you don't like the format, you can change it:
98
99 my $backtrace = Devel::Backtrace->new(-format => '%I. %s');
100
101 This would produce a stringification of the following form:
102
103 0. Devel::Backtrace::new
104 1. MyPackage::test2
105 2. MyPackage::test1
106 3. main::bar
107 4. main::foo
108
109SEE ALSO
110 Devel::StackTrace does mostly the same as this module. I'm afraid I
111 hadn't noticed it until I uploaded this module.
112
113 Carp::Trace is a simpler module which gives you a backtrace in string
114 form.
115
116 Devel::DollarAt comes with this distribution and is a nice application
117 of this module. You can use it for debugging to get a backtrace out of
118 $@.
119
120AUTHOR
121 Christoph Bussenius <pepe@cpan.org>
122
123 If you use this module, I'll be glad if you drop me a note. You should
124 mention this module's name in the subject of your mails, in order to
125 make sure they won't get lost in all the spam.
126
127LICENSE
128 This module is in the public domain.
129
130 If your country's law does not allow this module being in the public
131 domain or does not include the concept of public domain, you may use the
132 module under the same terms as perl itself.
133
134