1Test::Stream::Util(3) User Contributed Perl DocumentationTest::Stream::Util(3)
2
6 Test::Stream::Util - Tools used by Test::Stream and friends.
7
9 This distribution is deprecated in favor of Test2, Test2::Suite, and
10 Test2::Workflow.
11 See Test::Stream::Manual::ToTest2 for a conversion guide.
13
15 Collection of tools used by Test::Stream and friends.
16
18 All exports are optional, you must specify subs to import. If you want
19 to import everything use '-all'.
20 use Test::Stream::Util '-all';
22 ($success, $error) = try { ... }
24 Eval the codeblock, return success or failure, and the error
25 message. This code protects $@ and $!, they will be restored by the
26 end of the run. This code also temporarily blocks $SIG{DIE}
27 handlers.
28 protect { ... }
30 Similar to try, except that it does not catch exceptions. The idea
31 here is to protect $@ and $! from changes. $@ and $! will be
32 restored to whatever they were before the run so long as it is
33 successful. If the run fails $! will still be restored, but $@ will
34 contain the exception being thrown.
35 USE_THREADS
37 Returns true if threads are enabled, false if they are not.
38 get_tid
40 This will return the id of the current thread when threads are
41 enabled, otherwise it returns 0.
42 my $file = pkg_to_file($package)
44 Convert a package name to a filename.
45 $stash = get_stash($package)
47 Returns the stash reference for the given package. The stash
48 reference can be treated like a hashref, you can get keys and
49 values from it.
50 $slot = sig_to_slot($sigil)
52 Given a sigil such as "$", "@", "%", "&", "*", this will return the
53 GLOB slot for that sigil such as "SCALAR", "ARRAY", "HASH", "CODE",
54 "GLOB".
55 $sigil = slot_to_sig($slot)
57 Given a a glob slot such as "SCALAR", "ARRAY", "HASH", "CODE",
58 "GLOB", this will return the typical sigil for that slot such as
59 "$", "@", "%", "&", "*".
60 ($name, $type) = parse_symbol($symbol)
62 When given a symbol name such as $foo or @bar this will return the
63 symbol name, and the type name. If no sigil is present in the
64 variable name it will assume it is a subroutine and return the
65 "CODE" type. $symbol should be a string containing the name of the
66 symbol with optional sigil.
67 my $cols = term_size()
69 Attempts to find the width in columns (characters) of the current
70 terminal. Returns 80 as a safe bet if it cannot find it another
71 way. This is most accurate if Term::ReadKey is installed.
72 $type = rtype($ref)
74 A normalization between Scalar::Util::reftype() and ref().
75 Always returns a string.
77 Returns 'REGEXP' for regex types
79 Returns '' for non-refs
81 Otherwise returns what Scalar::Util::reftype() returns.
83 $addr_str = render_ref($ref)
85 Always returns a string. For unblessed references this returns
86 something like "SCALAR(0x...)". For blessed references it returns
87 "My::Thing=SCALAR(0x...)". The only difference between this and
88 $add_str = "$thing" is that it ignores any overloading to ensure it
89 is always the ref address.
90 $bool = CAN_SET_SUB_NAME()
92 A constant, it returns true if either Sub::Name or Sub::Util are
93 installed and have the code necessary to set a sub name.
94 set_sub_name($name, $coderef)
96 When Sub::Name or Sub::Util are installed, this will be an alias to
97 the sub name setting function from one or the other. If neither are
98 installed then this will be a sub that throws an exception.
99 If setting the sub name is something nice, but not strictly
101 necessary, you can use this conditionally with CAN_SET_SUB_NAME().
102 use Test::Stream::Util qw/CAN_SET_SUB_NAME set_sub_name/;
104 set_sub_name('foo', \&sub) if CAN_SET_SUB_NAME();
105 my $hr = sub_info(\&code)
107 This returns a hashref with information about the sub:
108 {
110 ref => \&code,
111 cobj => $cobj,
112 name => "Some::Mod::code",
113 file => "Some/Mod.pm",
114 package => "Some::Mod",
115 # Note: These have been adjusted based on guesswork.
117 start_line => 22,
118 end_line => 42,
119 lines => [22, 42],
120 # Not a bug, these lines are different!
122 all_lines => [23, 25, ..., 39, 41],
123 };
124 $info->{ref} => \&code
126 This is the original sub passed to sub_info().
127 $info->{cobj} => $cobj
129 This is the c-object representation of the coderef.
130 $info->{name} => "Some::Mod::code"
132 This is the name of the coderef, for anonymous coderefs this
133 may end with '__ANON__'. Also note that the package 'main' is
134 special, and 'main::' may be omitted.
135 $info->{file} => "Some/Mod.pm"
137 The file in which the sub was defined.
138 $info->{package} => "Some::Mod"
140 The package in which the sub was defined.
141 $info->{start_line} => 22
143 $info->{end_line} => 42
144 $info->{lines} => [22, 42]
145 These 3 fields are the adjusted start line, end line, and array
146 with both. It is important to note that these lines have been
147 adjusted and may not be accurate.
148 The lines are obtained by walking the ops, as such the first
150 line is the line of the first statement, and the last line is
151 the line of the last statement. This means that in multi-line
152 subs the lines are usually off by 1. The lines in these keys
153 will be adjusted for you if it detects a multi-line sub.
154 $info->{all_lines} => [23, 25, ..., 39, 41]
156 This is an array with the lines of every statement in the sub.
157 unlike the other line fields, these have not been adjusted for
158 you.
159 update_mask($file, $line, $sub, {...})
161 This sets masking behavior in accordance with Trace::Mask. This
162 will have no effect on anything that does not honor Trace::Mask.
163
165 The source code repository for Test::Stream can be found at
166 http://github.com/Test-More/Test-Stream/.
167
169 Chad Granum <exodist@cpan.org>
170
172 Chad Granum <exodist@cpan.org>
173 Kent Fredric <kentnl@cpan.org>
174
176 Copyright 2015 Chad Granum <exodist7@gmail.com>.
177 This program is free software; you can redistribute it and/or modify it
179 under the same terms as Perl itself.
180 See http://dev.perl.org/licenses/
182perl v5.38.0 2023-07-21 Test::Stream::Util(3)