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
89 it 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
102 "CAN_SET_SUB_NAME()".
103 use Test::Stream::Util qw/CAN_SET_SUB_NAME set_sub_name/;
105 set_sub_name('foo', \&sub) if CAN_SET_SUB_NAME();
106 my $hr = sub_info(\&code)
108 This returns a hashref with information about the sub:
109 {
111 ref => \&code,
112 cobj => $cobj,
113 name => "Some::Mod::code",
114 file => "Some/Mod.pm",
115 package => "Some::Mod",
116 # Note: These have been adjusted based on guesswork.
118 start_line => 22,
119 end_line => 42,
120 lines => [22, 42],
121 # Not a bug, these lines are different!
123 all_lines => [23, 25, ..., 39, 41],
124 };
125 $info->{ref} => \&code
127 This is the original sub passed to "sub_info()".
128 $info->{cobj} => $cobj
130 This is the c-object representation of the coderef.
131 $info->{name} => "Some::Mod::code"
133 This is the name of the coderef, for anonymous coderefs this
134 may end with '__ANON__'. Also note that the package 'main' is
135 special, and 'main::' may be omitted.
136 $info->{file} => "Some/Mod.pm"
138 The file in which the sub was defined.
139 $info->{package} => "Some::Mod"
141 The package in which the sub was defined.
142 $info->{start_line} => 22
144 $info->{end_line} => 42
145 $info->{lines} => [22, 42]
146 These 3 fields are the adjusted start line, end line, and array
147 with both. It is important to note that these lines have been
148 adjusted and may not be accurate.
149 The lines are obtained by walking the ops, as such the first
151 line is the line of the first statement, and the last line is
152 the line of the last statement. This means that in multi-line
153 subs the lines are usually off by 1. The lines in these keys
154 will be adjusted for you if it detects a multi-line sub.
155 $info->{all_lines} => [23, 25, ..., 39, 41]
157 This is an array with the lines of every statement in the sub.
158 unlike the other line fields, these have not been adjusted for
159 you.
160 update_mask($file, $line, $sub, {...})
162 This sets masking behavior in accordance with Trace::Mask. This
163 will have no effect on anything that does not honor Trace::Mask.
164
166 The source code repository for Test::Stream can be found at
167 http://github.com/Test-More/Test-Stream/.
168
170 Chad Granum <exodist@cpan.org>
171
173 Chad Granum <exodist@cpan.org>
174 Kent Fredric <kentnl@cpan.org>
175
177 Copyright 2015 Chad Granum <exodist7@gmail.com>.
178 This program is free software; you can redistribute it and/or modify it
180 under the same terms as Perl itself.
181 See http://dev.perl.org/licenses/
183perl v5.34.0 2021-07-27 Test::Stream::Util(3)