1Test::Stream::Util(3) User Contributed Perl DocumentationTest::Stream::Util(3)
2
3
4

NAME

6       Test::Stream::Util - Tools used by Test::Stream and friends.
7

DEPRECATED

9       This distribution is deprecated in favor of Test2, Test2::Suite, and
10       Test2::Workflow.
11
12       See Test::Stream::Manual::ToTest2 for a conversion guide.
13

DESCRIPTION

15       Collection of tools used by Test::Stream and friends.
16

EXPORTS

18       All exports are optional, you must specify subs to import. If you want
19       to import everything use '-all'.
20
21           use Test::Stream::Util '-all';
22
23       ($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
29       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
36       USE_THREADS
37           Returns true if threads are enabled, false if they are not.
38
39       get_tid
40           This will return the id of the current thread when threads are
41           enabled, otherwise it returns 0.
42
43       my $file = pkg_to_file($package)
44           Convert a package name to a filename.
45
46       $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
51       $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
56       $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
61       ($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
68       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
73       $type = rtype($ref)
74           A normalization between "Scalar::Util::reftype()" and "ref()".
75
76           Always returns a string.
77
78           Returns 'REGEXP' for regex types
79
80           Returns '' for non-refs
81
82           Otherwise returns what "Scalar::Util::reftype()" returns.
83
84       $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
91       $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
95       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
100           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
104               use Test::Stream::Util qw/CAN_SET_SUB_NAME set_sub_name/;
105               set_sub_name('foo', \&sub) if CAN_SET_SUB_NAME();
106
107       my $hr = sub_info(\&code)
108           This returns a hashref with information about the sub:
109
110               {
111                   ref        => \&code,
112                   cobj       => $cobj,
113                   name       => "Some::Mod::code",
114                   file       => "Some/Mod.pm",
115                   package    => "Some::Mod",
116
117                   # Note: These have been adjusted based on guesswork.
118                   start_line => 22,
119                   end_line   => 42,
120                   lines      => [22, 42],
121
122                   # Not a bug, these lines are different!
123                   all_lines  => [23, 25, ..., 39, 41],
124               };
125
126           $info->{ref} => \&code
127               This is the original sub passed to "sub_info()".
128
129           $info->{cobj} => $cobj
130               This is the c-object representation of the coderef.
131
132           $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
137           $info->{file} => "Some/Mod.pm"
138               The file in which the sub was defined.
139
140           $info->{package} => "Some::Mod"
141               The package in which the sub was defined.
142
143           $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
150               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
156           $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
161       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

SOURCE

166       The source code repository for Test::Stream can be found at
167       http://github.com/Test-More/Test-Stream/.
168

MAINTAINERS

170       Chad Granum <exodist@cpan.org>
171

AUTHORS

173       Chad Granum <exodist@cpan.org>
174       Kent Fredric <kentnl@cpan.org>
175
177       Copyright 2015 Chad Granum <exodist7@gmail.com>.
178
179       This program is free software; you can redistribute it and/or modify it
180       under the same terms as Perl itself.
181
182       See http://dev.perl.org/licenses/
183
184
185
186perl v5.32.1                      2021-01-27             Test::Stream::Util(3)
Impressum