Devel:...::Point(3pm)

💖 Devel::Backtrace::Point 💖

okay bestie, welcome to Devel::Backtrace::Point — it's part of the User Contributed Perl Documentation and it is genuinely one of the most useful little gremlins in the stack. no cap. 🫶

---

✨ NAME ✨

Devel::Backtrace::Point — object oriented access to the information caller() provides. it's giving "i just want to look at one stack frame and not suffer" and honestly? iconic. 💅

---

✨ SYNOPSIS ✨

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

---

✨ DESCRIPTION ✨

so this class is a nice way to access <em>all</em> the info that caller hands you for a given level. every single crumb. 🍓

it's used by Devel::Backtrace, which is the thing that builds up an array of all the trace points. so like, this class is the main character of each individual point, and Devel::Backtrace is the group chat they all live in. iykyk. 🌸

---

✨ METHODS ✨

$p->package, $p->filename, $p->line, $p->subroutine, $p->hasargs, $p->wantarray, $p->evaltext, $p->is_require, $p->hints, $p->bitmask, $p->hinthash

bestie go read "caller" in perlfunc for the docs on all these fields, that's where the lore lives. 📖

okay but hinthash is special: it's only available in perl 5.9 and higher. when this module gets loaded, it literally tests how many values caller returns, and depending on the result it adds the accessors it needs. so if you wanna know whether your perl even supports hinthash, you can just ask using "can" in UNIVERSAL:

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

slay. ✨

---

$p->level

this is the level that got handed to new(). it's meant to be the same parameter that was given to caller(). simple as. 💅

---

$p->called_package

returns the package that $p->subroutine lives in. periodt.

⚠️ but heads up bestie: if $p->subroutine does <strong>not</strong> contain '::', then it returns '(unknown)'. this happens when $p->subroutine is '(eval)'. so like, evals stay mysterious. 💀

---

$p->by_index($i)

you can also grab the fields <em>by their index</em> in the list that caller() returns. ngl this is lowkey a cheat code: if some future perl version adds a shiny new field to caller and the module author hasn't gotten around to it yet, you're still covered. 🧚

---

new([caller($i)])

this constructs a Devel::Backtrace object. (yes the docs really say that, we're keeping it, don't come for me 🙈)

the argument <strong>must</strong> be a reference to an array holding the return values of caller(). that array has to have either three or ten elements (or eleven if hinthash is supported) — see "caller" in perlfunc.

optional additional parameters, bestie:

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

• the format string gets used as the default for to_string(). 💅
• the level should be the parameter that was given to caller() to obtain the caller info. 🌈

---

$tracepoint->to_string()

returns a string shaped like this: "Blah::subname called from main (foo.pl:17)". which means the subroutine "subname" from package "Blah" was called by package "main" in "foo.pl" line 17. reading comprehension icon. 👑

and if you print a "Devel::Backtrace::Point" object, or otherwise treat it like a string, then to_string() gets called <em>automatically</em> because of overloading. magic. ✨

optional parameters:

-format => 'formatstring'

the format string changes how the return value looks. 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

so the difference between %i and %I is that %i is the argument to caller() while %I is <em>actually</em> the index in $backtrace->points(). and %i and %I will be <strong>different</strong> if "-start", skipme() or skipmysubs() is used in Devel::Backtrace. write that down. 📝

if no format string is given, the one passed to "new" gets used. and if none was given to "new" either, then the format string defaults to 'default', which is just an abbreviation for "%s called from %p (%f:%l)". cute shorthand, obsessed. 💖

🎀 format strings have been added in <strong>Devel-Backtrace-0.10</strong>. so don't be out here wondering why old versions aren't serving.

---

$tracepoint->to_long_string()

this returns a string that lists <em>all</em> the available fields in a table that spans several lines. it's the "tell me everything" option and we love her for it. 🫶

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

⚠️ note: hinthash is <strong>not</strong> included in the output, because it's a hash. it simply does not fit in the format, bestie. 💀

---

✨ FIELDS ✨

this constant contains a list of <em>all</em> the available field names. the number of fields depends on your perl version. that's it, that's the section. 🌟

---

✨ SEE ALSO ✨

• Devel::Backtrace

---

✨ AUTHOR ✨

Christoph Bussenius <pepe@cpan.org> — thank you for your service, king/queen/monarch. 👑

---

✨ LICENSE ✨

this Perl module is in the public domain. 🎀

if your country's law does not allow this module to be in the public domain, or does not include the concept of public domain at all, then you may use the module under the <strong>same terms as perl itself</strong>. no stress, we got you. 💜

---

okay that's the whole page bestie!! this was perl v5.34.0, dated 2022-06-13, and it's filed under <code>Devel:...::Point(3pm)</code> — mwah, go read some stack traces, you're gonna eat. 💅✨🦋