Test::Stream::Util(3)

📦
version 1.302027 · 2 versions
, in fedora 43

💖 Test::Stream::Util 💖

okay so bestie, welcome to Test::Stream::Util(3) — it's the lil toolbox that Test::Stream and all its friends keep in their bag 🎀. This page is from the User Contributed Perl Documentation collection, and we're gonna go through it together, no skimming, no skipping, periodt.

✨ NAME ✨

Test::Stream::Util — Tools used by Test::Stream and friends. 🛠️

💀 DEPRECATED 💀

ngl this one hurts. This distribution is deprecated in favor of Test2, Test2::Suite, and Test2::Workflow. 😭

See Test::Stream::Manual::ToTest2 for a conversion guide — that's your glow-up roadmap, bestie. 🦋

🌸 DESCRIPTION 🌸

It's a collection of tools used by Test::Stream and friends. That's the whole vibe. Simple. Iconic. 💅

👑 EXPORTS 👑

okay so the way this works: all exports are optional, you have to actually specify which subs you want to import. You don't just get them. Rude? Maybe. Safe? Absolutely. 💜

If you're feeling greedy and want everything, use -all:

use Test::Stream::Util '-all';

Here's the full lineup, no cap:

  • ($success, $error) = try { ... } — Evals the codeblock, returns success or failure, plus the error message. This code protects $@ and $! — they get restored by the end of the run. It also temporarily blocks $SIG{DIE} handlers. 🛡️
  • protect { ... } — Similar to try, except it does not catch exceptions. The whole idea is protecting $@ and $! from changes. $@ and $! get restored to whatever they were before the run, as long as it succeeds. If the run fails, $! still gets restored, but $@ will contain the exception being thrown. 🙈
  • USE_THREADS — Returns true if threads are enabled, false if they are not. 🧵
  • get_tid — Returns the id of the current thread when threads are enabled; otherwise it returns 0.
  • my $file = pkg_to_file($package) — Converts a package name to a filename. 📁
  • $stash = get_stash($package) — Returns the stash reference for the given package. The stash reference can be treated like a hashref — you can get keys and values from it. 🔑
  • $slot = sig_to_slot($sigil) — Give it a sigil like "$", "@", "%", "&", "*", and it returns the GLOB slot for that sigil, like "SCALAR", "ARRAY", "HASH", "CODE", "GLOB".
  • $sigil = slot_to_sig($slot) — Give it a glob slot like "SCALAR", "ARRAY", "HASH", "CODE", "GLOB", and it returns the typical sigil for that slot, like "$", "@", "%", "&", "*". It's the reverse girly. 🔄
  • ($name, $type) = parse_symbol($symbol) — When given a symbol name such as $foo or @bar, this returns the symbol name and the type name. If there's no sigil present in the variable name, it assumes it's a subroutine and returns the "CODE" type. $symbol should be a string containing the name of the symbol, with an optional sigil. 🏷️
  • my $cols = term_size() — Attempts to find the width in columns (characters) of the current terminal. Returns 80 as a safe bet if it can't find it another way. This is most accurate if Term::ReadKey is installed. 📏
  • $type = rtype($ref) — A normalization between Scalar::Util::reftype() and ref(). ✨
    • Always returns a string.
    • Returns 'REGEXP' for regex types.
    • Returns '' for non-refs.
    • Otherwise returns what Scalar::Util::reftype() returns.
  • $addr_str = render_ref($ref) — Always returns a string. For unblessed references this returns something like "SCALAR(0x...)". For blessed references it returns "My::Thing=SCALAR(0x...)". The only difference between this and $add_str = "$thing" is that it ignores any overloading, to ensure it's always the ref address. 🔍
  • $bool = CAN_SET_SUB_NAME() — A constant. Returns true if either Sub::Name or Sub::Util are installed and have the code necessary to set a sub name. ✅
  • set_sub_name($name, $coderef) — When Sub::Name or Sub::Util are installed, this will be an alias to the sub name setting function from one or the other. If neither are installed, then this will be a sub that throws an exception. 🚨

If setting the sub name is something nice but not strictly necessary, you can use this conditionally with CAN_SET_SUB_NAME():

use Test::Stream::Util qw/CAN_SET_SUB_NAME set_sub_name/;
set_sub_name('foo', \&sub) if CAN_SET_SUB_NAME();
  • my $hr = sub_info(\&code) — This returns a hashref with information about the sub:
{
    ref        => \&code,
    cobj       => $cobj,
    name       => "Some::Mod::code",
    file       => "Some/Mod.pm",
    package    => "Some::Mod",

    # Note: These have been adjusted based on guesswork.
    start_line => 22,
    end_line   => 42,
    lines      => [22, 42],

    # Not a bug, these lines are different!
    all_lines  => [23, 25, ..., 39, 41],
};

Here's what every single key means, bestie, don't skip 👇

  • $info->{ref} => \&code — This is the original sub passed to sub_info().
  • $info->{cobj} => $cobj — This is the c-object representation of the coderef.
  • $info->{name} => "Some::Mod::code" — This is the name of the coderef. For anonymous coderefs this may end with __ANON__. Also note that the package 'main' is special, and 'main::' may be omitted.
  • $info->{file} => "Some/Mod.pm" — The file in which the sub was defined.
  • $info->{package} => "Some::Mod" — The package in which the sub was defined.
  • $info->{start_line} => 22, $info->{end_line} => 42, $info->{lines} => [22, 42] — These 3 fields are the adjusted start line, end line, and an array with both. It is important to note that these lines have been adjusted and may not be accurate. ⚠️ The lines are obtained by walking the ops — as such, the first line is the line of the first statement, and the last line is the line of the last statement. This means that in multi-line subs the lines are usually off by 1. The lines in these keys will be adjusted for you if it detects a multi-line sub.
  • $info->{all_lines} => [23, 25, ..., 39, 41] — This is an array with the lines of every statement in the sub. Unlike the other line fields, these have not been adjusted for you. 🙃
  • update_mask($file, $line, $sub, {...}) — This sets masking behavior in accordance with Trace::Mask. This will have no effect on anything that does not honor Trace::Mask. 🎭

🌈 SOURCE 🌈

The source code repository for Test::Stream can be found at http://github.com/Test-More/Test-Stream/. Go star it, it's giving open source royalty 👑

🫶 MAINTAINERS 🫶

Chad Granum <exodist@cpan.org>

🧚 AUTHORS 🧚

Chad Granum <exodist@cpan.org> Kent Fredric <kentnl@cpan.org>

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://dev.perl.org/licenses/

and that's the whole page bestie, you ate it 💅✨ This was pulled from perl v5.42.0, dated 2025-07-25, for Test::Stream::Util(3) — now go forth and use it responsibly, mwah 🎀🦋💖

📦 where this page comes from