Trace::...ference(3)

💖 Trace::Mask::Reference 💖

okay so bestie, gather round 🫶 this is a page from the User Contributed Perl Documentation crew, and it's all about a lil module called Trace::Mask::Reference. It's giving "reference implementation" energy and honestly? iconic. 👑

✨ NAME ✨

Trace::Mask::Reference — Reference implemtnations of tools and tracers

not me pointing out that the typo in "implemtnations" is 100% canon and lives in the original, we do NOT fix it, we RESPECT it 😭💅

---

🌸 DESCRIPTION 🌸

This module hands you a reference implementation of a Stack::Mask compliant stack tracer. Yes, compliant. It's also got reference examples of tools that benefit from masking stack traces. 🦋

BIG WARNING BESTIE — these tools should NOT be used in production code. Like, ever. They're for unit tests that verify compliance. That's the whole vibe check. 🚫

---

🎀 SYNOPSIS 🎀

use Trace::Mask::Reference qw/try_example trace_string/;

sub foo {
    print trace_string;
}

sub bar {
    my $error = try_example { foo() };
    ...
}

sub baz {
    bar();
}

baz();

This produces the following stack trace:

main::foo() called at test.pl line 8
main::bar() called at test.pl line 13
main::baz() called at test.pl line 16

Notice that the call to try, the eval it uses inside, and the call to the anonymous codeblock are all hidden. 🫣✨ This effectively removes noise from the stack trace. It makes try look just like an if or while block. slay.

There is a downside however if anything inside the try implementation itself is broken. 💀

---

🌈 EXPORTS 🌈

Note: All exports are optional, you must request them if you want them. No surprise gifts here, bestie. 🎁

• $frames_ref = trace() — This produces an array reference containing stack frames of a trace. Each frame is an arrayref that matches the return from caller(), with the additon that the last index contains the arguments used in the call. Never rely on the index number of the arguments, always pop them off if you need them, different versions of perl may have a different number of values in a stack frame. 🍓

Index 0 of the $frames_ref will be the topmost call of the trace, the rest will be in descending order.

See trace_string() for a tool to provide a carp-like stack trace.

$level may be specified to start the stack at a deeper level.

• $trace = trace_string()
• $trace = trace_string($level) — This provides a stack trace string similar to longmess() from Carp. Though it does not indent the trace, and it does not take the form of an error report. 📝

$level may be specified to start the stack at a deeper level.

• ($pkg, $file, $line) = trace_mask_caller()
• ($pkg, $file, $line, $name, ...) = trace_mask_caller($level) — This is a caller() emulator that honors the stack tracing specifications. Please do not override caller() with this. This implementation take a FULL stack trace on each call, and returns just the desired frame from that trace. 🙈
• $error = try_example { ... } — A reference implementation of try { ... } that demonstrates the trace masking behavior. Please do not use this in production code, it is a very dumb, and not-very-useful implementation of try that serves as a demo. 💀

---

🦋 SEE ALSO 🦋

• Sub::Uplevel — Tool for hiding stack frames from all callers, not just stack traces. 👀

---

⭐ SOURCE ⭐

The source code repository for Trace-Mask can be found at http://github.com/exodist/Trace-Mask.

---

👑 MAINTAINERS 👑

• Chad Granum <exodist@cpan.org>

---

💜 AUTHORS 💜

• Chad Granum <exodist@cpan.org>

---

🌸 COPYRIGHT 🌸

Copyright 2015 Chad Granum <exodist7@gmail.com>.

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

See http://www.perl.com/perl/misc/Artistic.html

---

and that's the whole page, bestie!! 💅 this was perl v5.42.0 doing its thing, dated 2025-07-25, and it's the Trace::...ference(3) situation we've been living in this entire time. no cap, go forth and mask those stack frames responsibly. 🫶✨💖