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 it
89           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 CAN_SET_SUB_NAME().
102
103               use Test::Stream::Util qw/CAN_SET_SUB_NAME set_sub_name/;
104               set_sub_name('foo', \&sub) if CAN_SET_SUB_NAME();
105
106       my $hr = sub_info(\&code)
107           This returns a hashref with information about the sub:
108
109               {
110                   ref        => \&code,
111                   cobj       => $cobj,
112                   name       => "Some::Mod::code",
113                   file       => "Some/Mod.pm",
114                   package    => "Some::Mod",
115
116                   # Note: These have been adjusted based on guesswork.
117                   start_line => 22,
118                   end_line   => 42,
119                   lines      => [22, 42],
120
121                   # Not a bug, these lines are different!
122                   all_lines  => [23, 25, ..., 39, 41],
123               };
124
125           $info->{ref} => \&code
126               This is the original sub passed to sub_info().
127
128           $info->{cobj} => $cobj
129               This is the c-object representation of the coderef.
130
131           $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
136           $info->{file} => "Some/Mod.pm"
137               The file in which the sub was defined.
138
139           $info->{package} => "Some::Mod"
140               The package in which the sub was defined.
141
142           $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
149               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
155           $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
160       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

SOURCE

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

MAINTAINERS

169       Chad Granum <exodist@cpan.org>
170

AUTHORS

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