Devel::Backtrace(3pm)

💅 Devel::Backtrace — the manual, but make it cute

okay bestie, so Devel::Backtrace(3pm) is a User Contributed Perl Documentation page and honestly? it's a bop. it's the object-oriented backtrace module, and we're gonna go through the whole thing together, no skips, no cap 💖

---

✨ NAME ✨

Devel::Backtrace — Object-oriented backtrace. that's it, that's the whole vibe. it's giving "I know where you came from" but make it OO 🦋

---

🌸 VERSION 🌸

This is version 0.12. yes, bestie, we're on 0.12. ✨

---

🎀 SYNOPSIS 🎀

look at this lil starter pack, it's so iconic:

my $backtrace = Devel::Backtrace->new;

print $backtrace; # use automatic stringification
                  # See EXAMPLES to see what the output might look like

print $backtrace->point(0)->line;

like, you literally just make one and print it. the automatic stringification is doing the heavy lifting, and honestly? she's the main character 💅 the EXAMPLES section below shows you what that output might look like, iykyk 👑

---

🔥 METHODS 🔥

Devel::Backtrace->new()

Optional parameters: -start => $start, -format => $format.

If only one parameter is given, it will be used as $start. (so it's flexible like that, she adapts 🌈)

Constructs a new Devel::Backtrace which is filled with all the information caller($i) provides, where $i starts from $start. If no argument is given, $start defaults to 0.

If $start is 1 (or higher), the backtrace won't contain the information that (and where) Devel::Backtrace::new() was called. so like, bump that number and the whole "who even called me" origin story just dips 🙈

$backtrace->point($i)

Returns the i'th tracepoint as a Devel::Backtrace::Point object (see its documentation for how to access every bit of information). every single lil crumb of data is in there, bestie 🍓

Note that the following code snippet will print the information of caller($start+$i):

print Devel::Backtrace->new($start)->point($i)

$backtrace->points()

Returns a list of all tracepoints. In scalar context, the number of tracepoints is returned. so it's giving list in list context, count in scalar context — context-aware queen 👑

$backtrace->skipme([$package])

This method deletes all leading tracepoints that contain information about calls within $package. Afterwards the $backtrace will look as though it had been created with a higher value of $start. it's lowkey just erasing the evidence ✨

If the optional parameter $package is not given, it defaults to the calling package.

The effect is similar to what the Carp module does.

This module ships with an example skipme.pl that demonstrates how to use this method. See also EXAMPLES.

$backtrace->skipmysubs([$package])

This method is like skipme except that it deletes calls to the package rather than calls from the package. subtle difference, huge energy shift 💫

Before discarding those calls, skipme is called. This is because usually the topmost call in the stack is to Devel::Backtrace->new, which would not be catched by skipmysubs otherwise.

This means that skipmysubs usually deletes more lines than skipme would. so yeah, she's the more aggressive one 😤

skipmysubs was added in Devel::Backtrace version 0.06.

See also EXAMPLES and the example skipme.pl.

$backtrace->to_string()

Returns a string that contains one line for each tracepoint. It will contain the information from Devel::Backtrace::Point's to_string() method. To get more information, use the to_long_string() method.

Note that you don't have to call to_string() if you print a Devel::Backtrace object or otherwise treat it as a string, as the stringification operator is overloaded. so you can just yeet it into a print and she knows what to do 🫶

See EXAMPLES.

$backtrace->to_long_string()

Returns a very long string that contains several lines for each trace point. The result will contain every available bit of information. like, ALL of it, no holding back 💀 See "to_long_string" in Devel::Backtrace::Point for an example of what the result looks like.

---

💖 EXAMPLES 💖

A sample stringification might look like this:

Devel::Backtrace::new called from MyPackage (foo.pl:30)
MyPackage::test2 called from MyPackage (foo.pl:28)
MyPackage::test1 called from main (foo.pl:18)
main::bar called from main (foo.pl:6)
main::foo called from main (foo.pl:13)

If MyPackage called skipme, the first two lines would be removed. If it called skipmysubs, the first three lines would be removed. see? told you she deletes more 👀

If you don't like the format, you can change it:

my $backtrace = Devel::Backtrace->new(-format => '%I. %s');

This would produce a stringification of the following form:

0. Devel::Backtrace::new
1. MyPackage::test2
2. MyPackage::test1
3. main::bar
4. main::foo

custom format? obsessed. it's giving personalization, it's giving tailored ✨

---

🌈 SEE ALSO 🌈

• Devel::StackTrace does mostly the same as this module. the author is like "I'm afraid I hadn't noticed it until I uploaded this module" — realest thing ever, we've all been there 😭
• Carp::Trace is a simpler module which gives you a backtrace in string form. cute, low-maintenance, does the job 💅
• Devel::DollarAt comes with this distribution and is a nice application of this module. You can use it for debugging to get a backtrace out of $@. yes bestie, backtrace straight outta $@, iconic 🔥

---

👑 AUTHOR 👑

Christoph Bussenius <pepe@cpan.org>

If you use this module, I'll be glad if you drop me a note. You should mention this module's name in the subject of your mails, in order to make sure they won't get lost in all the spam. fr fr, put the module name in the subject or it's getting buried in the spam folder 🙈

---

🧚 LICENSE 🧚

This 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.

---

okay that's the whole thing, you're fully caught up bestie 💜 this page was perl v5.34.0, dated 2022-06-13, and it's Devel::Backtrace(3pm) — go forth and trace those calls, you absolute legend ⭐🎀