Trace::Mask::Util(3)

🦋 NAME 🦋

Trace::Mask::Util — utilities for applying stack trace masks. That's it, that's the name section. This page lives in the User Contributed Perl Documentation manual, and it's here to make your stack traces stop looking like a crime scene. 💅

---

✨ DESCRIPTION ✨

okay so. This package hands you a whole lil toolbox of utilities that help you apply masks to stack traces. If you wanna know the actual rules these utilities follow, go read Trace::Mask — that's the spec, and it's the one setting the vibe here. periodt. 🎀

---

🎀 EXPORTS 🎀

Note: every single export here is optional. Nothing just parachutes into your namespace — you gotta ask for it. no sneaky auto-imports, we respect boundaries in this house. 🫶

💖 update_mask($file, $line, $sub, \%mask)

update_mask($file, $line, $sub, \%mask)

Updates the mask for the $file, $line and $sub you named. Whatever's in that \%mask hashref gets merged into any mask that already exists there — merge, not replace, iykyk. Also you may use the wildcard string '*' for any 2 of the first 3 arguments. And $sub can be a coderef, or a fully qualified sub name. flexible icon behavior. ✨

🧚 @errors = validate_mask(\%mask)

@errors = validate_mask(\%mask)

This one runs a vibe check on your mask to make sure it's actually valid. Mask valid? You get an empty list back, slay. Mask got problems? You get a whole list of error strings, one per problem. no cap. 😭

🌸 $hr = get_mask($file, $line, $sub)

$hr = get_mask($file, $line, $sub)

Gets you the combined mask for that specific file, line and sub. Combined means it's a merger of all the applicable masks, wildcards included. And yeah, $sub can be a coderef or a fully qualified sub name. 💜

👑 mask_call(\%mask, $sub)

👑 mask_call(\%mask, $sub, @args)

mask_call(\%mask, $sub)
mask_call(\%mask, $sub, @args)

Calls $sub with the mask and args you specified. The iconic part: it uses goto &$sub to run your sub, which means mask_call() itself does not show up in any stack frames. gone, invisible, main character exit. $sub can be a sub reference, or the name of a sub in the calling package. 🌈

⭐ mask_sub(\%mask, $sub)

⭐ mask_sub(\%mask, $sub, $file)

⭐ mask_sub(\%mask, $sub, $file, $line)

mask_sub(\%mask, $sub)
mask_sub(\%mask, $sub, $file)
mask_sub(\%mask, $sub, $file, $line)

Applies the mask to the sub you point at — coderef, or the name of a sub in the calling package, either one works. $file and $line are optional, and if you don't hand them over, '*' gets used instead. defaults are wildcards, we love a low-effort queen. 💅

🍓 mask_line(\%mask)

🍓 mask_line(\%mask, $delta)

🍓 mask_line(\%mask, $delta, @subs)

mask_line(\%mask)
mask_line(\%mask, $delta)
mask_line(\%mask, $delta, @subs)

Masks calls on the current line of the calling package, or the current + $delta line if you pass a delta. Optionally you can also hand it a list of subs to mask, and if you don't specify any, '*' is used. 🌸

This is genuinely so useful when you wanna slap a mask on multiple calls that live on one specific line:

sub try(&) {
    my $code = shift;

    # Hides both the eval, and the anon-block call
    BEGIN { mask_line({hide => 1}, 1) }
    my $ok = eval { $code->(); 1 };

    ...
}

Bestie pro-tip straight from the docs: it is best to run this inside a BEGIN {...} block so the mask gets added at compile time, instead of being re-added every single time your code runs. efficiency, we stan. ✨

🦋 mask_frame(%mask)

mask_frame(%mask)

This applies a mask to the currently running stack frame — aka whatever sub you happen to use it in. And it applies no matter where or how your sub got called. unconditional. iconic. 💖

---

🔥 SOURCE 🔥

The source code repository for Trace-Mask lives at http://github.com/exodist/Trace-Mask. go be nosy, bestie. 🫶

---

💜 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

---

okay that's the whole page, bestie, you're officially caught up. this was Trace::Mask::Util(3) from the User Contributed Perl Documentation manual, delivered to you by perl v5.42.0 on 2025-07-25. now go mask some stack traces and live your truth. 💅✨🎀