Debian Codegraph @

upstream/debian-unstable/man3/Test2::Tools::Exports.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Test2::Tools::Exports 3perl"
58 .TH Test2::Tools::Exports 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test2::Tools::Exports \- Tools for validating exporters.
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 These are tools for checking that symbols have been imported into your
68 namespace.
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& use Test2::Tools::Exports
73 \&
74 \& use Data::Dumper;
75 \& imported_ok qw/Dumper/;
76 \& not_imported_ok qw/dumper/;
77 .Ve
78 .SH EXPORTS
79 .IX Header "EXPORTS"
80 All subs are exported by default.
81 .IP imported_ok(@SYMBOLS) 4
82 .IX Item "imported_ok(@SYMBOLS)"
83 Check that the specified symbols exist in the current package. This will not
84 find inherited subs. This will only find symbols in the current package's symbol
85 table. This \fBWILL NOT\fR confirm that the symbols were defined outside of the
86 package itself.
87 .Sp
88 .Vb 1
89 \& imported_ok( \*(Aq$scalar\*(Aq, \*(Aq@array\*(Aq, \*(Aq%hash\*(Aq, \*(Aq&sub\*(Aq, \*(Aqalso_a_sub\*(Aq );
90 .Ve
91 .Sp
92 \&\f(CW@SYMBOLS\fR can contain any number of symbols. Each item in the array must be a
93 string. The string should be the name of a symbol. If a sigil is present then
94 it will search for that specified type, if no sigil is specified it will be
95 used as a sub name.
96 .IP not_imported_ok(@SYMBOLS) 4
97 .IX Item "not_imported_ok(@SYMBOLS)"
98 Check that the specified symbols do not exist in the current package. This will
99 not find inherited subs. This will only look at symbols in the current package's
100 symbol table.
101 .Sp
102 .Vb 1
103 \& not_imported_ok( \*(Aq$scalar\*(Aq, \*(Aq@array\*(Aq, \*(Aq%hash\*(Aq, \*(Aq&sub\*(Aq, \*(Aqalso_a_sub\*(Aq );
104 .Ve
105 .Sp
106 \&\f(CW@SYMBOLS\fR can contain any number of symbols. Each item in the array must be a
107 string. The string should be the name of a symbol. If a sigil is present, then
108 it will search for that specified type. If no sigil is specified, it will be
109 used as a sub name.
110 .SH CAVEATS
111 .IX Header "CAVEATS"
112 Before Perl 5.10, it is very difficult to distinguish between a package scalar
113 that is undeclared vs declared and undefined. Currently \f(CW\*(C`imported_ok\*(C'\fR and
114 \&\f(CW\*(C`not_imported_ok\*(C'\fR cannot see package scalars declared using \f(CW\*(C`our $var\*(C'\fR unless
115 the variable has been assigned a defined value.
116 .PP
117 This will pass on recent perls, but fail on perls older than 5.10:
118 .PP
119 .Vb 1
120 \& use Test2::Tools::Exports;
121 \&
122 \& our $foo;
123 \&
124 \& # Fails on perl onlder than 5.10
125 \& imported_ok(qw/$foo/);
126 .Ve
127 .PP
128 If \f(CW$foo\fR is imported from another module, or imported using
129 \&\f(CW\*(C`use vars qw/$foo/;\*(C'\fR then it will work on all supported perl versions.
130 .PP
131 .Vb 1
132 \& use Test2::Tools::Exports;
133 \&
134 \& use vars qw/$foo/;
135 \& use Some::Module qw/$bar/;
136 \&
137 \& # Always works
138 \& imported_ok(qw/$foo $bar/);
139 .Ve
140 .SH SOURCE
141 .IX Header "SOURCE"
142 The source code repository for Test2\-Suite can be found at
143 \&\fIhttps://github.com/Test\-More/Test2\-Suite/\fR.
144 .SH MAINTAINERS
145 .IX Header "MAINTAINERS"
146 .IP "Chad Granum <[email protected]>" 4
147 .IX Item "Chad Granum <[email protected]>"
148 .SH AUTHORS
149 .IX Header "AUTHORS"
150 .PD 0
151 .IP "Chad Granum <[email protected]>" 4
152 .IX Item "Chad Granum <[email protected]>"
153 .PD
154 .SH COPYRIGHT
155 .IX Header "COPYRIGHT"
156 Copyright 2018 Chad Granum <[email protected]>.
157 .PP
158 This program is free software; you can redistribute it and/or
159 modify it under the same terms as Perl itself.
160 .PP
161 See \fIhttp://dev.perl.org/licenses/\fR