Perl6::Caller(3pm)

💖 NAME 💖

Perl6::Caller — an OO caller() interface, bestie. That's the whole thing. It's giving "the builtin but make it an object."

---

✨ VERSION ✨

Version 0.04 💅

---

🌸 SYNOPSIS 🌸

 use Perl6::Caller;

 my $sub         = caller->subroutine;
 my $line_number = caller->line;
 my $is_require  = caller(3)->is_require;

---

🎀 EXPORT 🎀

caller"

okay so yeah, that's what's in here. Moving on.

 # standard usage
 print "In ",           caller->subroutine,
       " called from ", caller->file,
       " line ",        caller->line;

 # get a caller object
 my $caller = caller;
 my $caller = caller();   # same thing

 # get a caller object for a different stack from
 my $caller = caller(2);  # two stack frames up
 print $caller->package;  # prints the package name

 # enjoy the original flavor
 my @caller = caller;     # original caller behavior
 print $caller[0],        # prints the package name

---

🦋 DESCRIPTION 🦋

Heads up bestie: this module is experimental. It's also alpha. Bug reports and patches are welcome, fr fr. 🫶

By default, this module exports the caller function. And the way it works? It automatically returns a brand new caller object. Iconic. ✨

You can pass an optional argument that says how many stack frames back to skip — literally just like the CORE::caller function does. Which is what unlocks stuff like this:

 print "In ",           caller->subroutine,
       " called from ", caller->file,
       " line ",        caller->line;

But lowkey, if you don't want the caller function imported at all? Just specify an empty import list and instantiate a fresh Perl6::Caller object yourself. Main character energy:

 use Perl6::Caller ();
 my $caller = Perl6::Caller->new;
 print $caller->line;

Note: if the stuff coming back from this module seems strange, please go read perldoc -s caller carefully. Not me being dramatic — it genuinely has stranger behavior than you might be aware of. 😭

---

👑 METHODS 👑

These are the methods chilling on the caller object. They return the same values as documented in perldoc -f caller. No cap.

There are no "hints" and no "bitmask" methods, because those are documented as for internal use only. So we don't got them. Periodt.

• "package"
• "filename"
• "line"
• "subroutine"
• "hasargs"
• "wantarray"
• "evaltext"
• "is_require"

Now here's the tea: each one of these values reports correctly for the moment when the caller object was created. So the following will probably print different line numbers:

 print caller->line;
 foo();
 sub foo {
    print caller->line;
 }

But the following will print the same line numbers:

 my $caller = Perl6::Caller->new;   # everything is relative to here
 print $caller->line;
 foo($caller);
 sub foo {
    my $caller = shift;
    print $caller->line;
 }

---

💀 CAVEATS 💀

Most of the time, this package should just work and not interfere with anything else. Slay. But here's the fine print:

• $hints, $bitmask

'hints' and 'bitmask' are not available. They are documented to be for internal use only and should not be relied upon. Also, the bitmask caused strange test failures, so I opted not to include them. We're not doing that today. 🙈

• Subclassing

Don't.

• Perl 6

I'm not entirely comfortable with the namespace. The Perl 6 caller actually does considerably more, but for me to have a hope of working that in, I need proper introspection and I don't have that. Thus, I've settled for simply having a caller object. It's giving "we work with what we have."

• *CORE::GLOBAL::caller

I didn't implement this, though I was tempted. It turns out to be a bit tricky in spots and I'm very concerned about globally overriding behavior. I might change my mind in the future if there's enough demand.

• Overloading

In string context, this returns the package name. This is to support the original "caller" behavior.

• List Context

In list context, we simply default to the original behavior of "CORE::caller". However, this always assumes we've called caller with an argument. Calling "caller" and caller(0) are identical with this module. It's difficult to avoid since the stack frame changes.

---

🍓 AUTHOR 🍓

Curtis "Ovid" Poe, "<ovid@cpan.org>" 💜

---

🌈 ACKNOWLEDGEMENTS 🌈

Thanks to "phaylon" for helping me revisit a bad design issue with this. Real ones only. 🫶

---

🧚 BUGS 🧚

Please report any bugs or feature requests to "bug-perl6-caller@rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl6-Caller>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. Bestie, we'll go through this journey together. ✨

---

⭐ ACKNOWLEDGEMENTS ⭐

(yeah it's listed twice, that's just how the original is, and we keep every detail around here 💅)

---

💖 COPYRIGHT & LICENSE 💖

Copyright 2007 Curtis "Ovid" Poe, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay that's the whole page, we ate and left no crumbs 🎀 this was perl v5.36.0, dated 2022-10-13, and the page itself is Perl6::Caller(3pm) — mwah, bye bestie 💅🌸