Debian Codegraph @

upstream/debian-unstable/man3/Module::Load.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 "Module::Load 3perl"
58 .TH Module::Load 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 Module::Load \- runtime require of both modules and files
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use Module::Load;
69 \&
70 \& my $module = \*(AqData::Dumper\*(Aq;
71 \&
72 \& load Data::Dumper; # loads that module, but not import any functions
73 \& # \-> cannot use \*(AqDumper\*(Aq function
74 \&
75 \& load \*(AqData::Dumper\*(Aq; # ditto
76 \& load $module # tritto
77 \&
78 \& autoload Data::Dumper; # loads that module and imports the default functions
79 \& # \-> can use \*(AqDumper\*(Aq function
80 \&
81 \& my $script = \*(Aqsome/script.pl\*(Aq
82 \& load $script;
83 \& load \*(Aqsome/script.pl\*(Aq; # use quotes because of punctuations
84 \&
85 \& load thing; # try \*(Aqthing\*(Aq first, then \*(Aqthing.pm\*(Aq
86 \&
87 \& load CGI, \*(Aq:all\*(Aq; # like \*(Aquse CGI qw[:standard]\*(Aq
88 .Ve
89 .SH DESCRIPTION
90 .IX Header "DESCRIPTION"
91 \&\f(CW\*(C`Module::Load\*(C'\fR eliminates the need to know whether you are trying
92 to require either a file or a module.
93 .PP
94 If you consult \f(CW\*(C`perldoc \-f require\*(C'\fR you will see that \f(CW\*(C`require\*(C'\fR will
95 behave differently when given a bareword or a string.
96 .PP
97 In the case of a string, \f(CW\*(C`require\*(C'\fR assumes you are wanting to load a
98 file. But in the case of a bareword, it assumes you mean a module.
99 .PP
100 This gives nasty overhead when you are trying to dynamically require
101 modules at runtime, since you will need to change the module notation
102 (\f(CW\*(C`Acme::Comment\*(C'\fR) to a file notation fitting the particular platform
103 you are on.
104 .PP
105 \&\f(CW\*(C`Module::Load\*(C'\fR eliminates the need for this overhead and will
106 just DWYM.
107 .ie n .SS "Difference between ""load"" and ""autoload"""
108 .el .SS "Difference between \f(CWload\fP and \f(CWautoload\fP"
109 .IX Subsection "Difference between load and autoload"
110 \&\f(CW\*(C`Module::Load\*(C'\fR imports the two functions \- \f(CW\*(C`load\*(C'\fR and \f(CW\*(C`autoload\*(C'\fR
111 .PP
112 \&\f(CW\*(C`autoload\*(C'\fR imports the default functions automatically,
113 but \f(CW\*(C`load\*(C'\fR do not import any functions.
114 .PP
115 \&\f(CW\*(C`autoload\*(C'\fR is usable under \f(CW\*(C`BEGIN{};\*(C'\fR.
116 .PP
117 Both the functions can import the functions that are specified.
118 .PP
119 Following codes are same.
120 .PP
121 .Vb 1
122 \& load File::Spec::Functions, qw/splitpath/;
123 \&
124 \& autoload File::Spec::Functions, qw/splitpath/;
125 .Ve
126 .SH FUNCTIONS
127 .IX Header "FUNCTIONS"
128 .IP load 4
129 .IX Item "load"
130 Loads a specified module.
131 .Sp
132 See "Rules" for detailed loading rule.
133 .IP autoload 4
134 .IX Item "autoload"
135 Loads a specified module and imports the default functions.
136 .Sp
137 Except importing the functions, 'autoload' is same as 'load'.
138 .IP load_remote 4
139 .IX Item "load_remote"
140 Loads a specified module to the specified package.
141 .Sp
142 .Vb 1
143 \& use Module::Load \*(Aqload_remote\*(Aq;
144 \&
145 \& my $pkg = \*(AqOther::Package\*(Aq;
146 \&
147 \& load_remote $pkg, \*(AqData::Dumper\*(Aq; # load a module to \*(AqOther::Package\*(Aq
148 \& # but do not import \*(AqDumper\*(Aq function
149 .Ve
150 .Sp
151 A module for loading must be quoted.
152 .Sp
153 Except specifing the package and quoting module name,
154 \&'load_remote' is same as 'load'.
155 .IP autoload_remote 4
156 .IX Item "autoload_remote"
157 Loads a specified module and imports the default functions to the specified package.
158 .Sp
159 .Vb 1
160 \& use Module::Load \*(Aqautoload_remote\*(Aq;
161 \&
162 \& my $pkg = \*(AqOther::Package\*(Aq;
163 \&
164 \& autoload_remote $pkg, \*(AqData::Dumper\*(Aq; # load a module to \*(AqOther::Package\*(Aq
165 \& # and imports \*(AqDumper\*(Aq function
166 .Ve
167 .Sp
168 A module for loading must be quoted.
169 .Sp
170 Except specifing the package and quoting module name,
171 \&'autoload_remote' is same as 'load_remote'.
172 .SH Rules
173 .IX Header "Rules"
174 All functions have the following rules to decide what it thinks
175 you want:
176 .IP \(bu 4
177 If the argument has any characters in it other than those matching
178 \&\f(CW\*(C`\ew\*(C'\fR, \f(CW\*(C`:\*(C'\fR or \f(CW\*(C`\*(Aq\*(C'\fR, it must be a file
179 .IP \(bu 4
180 If the argument matches only \f(CW\*(C`[\ew:\*(Aq]\*(C'\fR, it must be a module
181 .IP \(bu 4
182 If the argument matches only \f(CW\*(C`\ew\*(C'\fR, it could either be a module or a
183 file. We will try to find \f(CW\*(C`file.pm\*(C'\fR first in \f(CW@INC\fR and if that
184 fails, we will try to find \f(CW\*(C`file\*(C'\fR in \f(CW@INC\fR. If both fail, we die with
185 the respective error messages.
186 .SH "IMPORTS THE FUNCTIONS"
187 .IX Header "IMPORTS THE FUNCTIONS"
188 \&'load' and 'autoload' are imported by default, but 'load_remote' and
189 \&'autoload_remote' are not imported.
190 .PP
191 To use 'load_remote' or 'autoload_remote', specify at 'use'.
192 .IP """load"",""autoload"",""load_remote"",""autoload_remote""" 4
193 .IX Item """load"",""autoload"",""load_remote"",""autoload_remote"""
194 Imports the selected functions.
195 .Sp
196 .Vb 2
197 \& # imports \*(Aqload\*(Aq and \*(Aqautoload\*(Aq (default)
198 \& use Module::Load;
199 \&
200 \& # imports \*(Aqautoload\*(Aq only
201 \& use Module::Load \*(Aqautoload\*(Aq;
202 \&
203 \& # imports \*(Aqautoload\*(Aq and \*(Aqautoload_remote\*(Aq, but don\*(Aqt import \*(Aqload\*(Aq;
204 \& use Module::Load qw/autoload autoload_remote/;
205 .Ve
206 .IP 'all' 4
207 .IX Item "'all'"
208 Imports all the functions.
209 .Sp
210 .Vb 1
211 \& use Module::Load \*(Aqall\*(Aq; # imports load, autoload, load_remote, autoload_remote
212 .Ve
213 .IP '','none',undef 4
214 .IX Item "'','none',undef"
215 Not import any functions (\f(CW\*(C`load\*(C'\fR and \f(CW\*(C`autoload\*(C'\fR are not imported).
216 .Sp
217 .Vb 1
218 \& use Module::Load \*(Aq\*(Aq;
219 \&
220 \& use Module::Load \*(Aqnone\*(Aq;
221 \&
222 \& use Module::Load undef;
223 .Ve
224 .SH Caveats
225 .IX Header "Caveats"
226 Because of a bug in perl (#19213), at least in version 5.6.1, we have
227 to hardcode the path separator for a require on Win32 to be \f(CW\*(C`/\*(C'\fR, like
228 on Unix rather than the Win32 \f(CW\*(C`\e\*(C'\fR. Otherwise perl will not read its
229 own \f(CW%INC\fR accurately double load files if they are required again, or
230 in the worst case, core dump.
231 .PP
232 \&\f(CW\*(C`Module::Load\*(C'\fR cannot do implicit imports, only explicit imports.
233 (in other words, you always have to specify explicitly what you wish
234 to import from a module, even if the functions are in that modules'
235 \&\f(CW@EXPORT\fR)
236 .SH "SEE ALSO"
237 .IX Header "SEE ALSO"
238 Module::Runtime provides functions for loading modules,
239 checking the validity of a module name,
240 converting a module name to partial \f(CW\*(C`.pm\*(C'\fR path,
241 and related utility functions.
242 .PP
243 "require" in perlfunc <https://metacpan.org/pod/perlfunc#require>
244 and
245 "use" in perlfunc <https://metacpan.org/pod/perlfunc#use>.
246 .PP
247 Mojo::Loader is a "class loader and plugin framework",
248 and is included in the
249 Mojolicious <https://metacpan.org/release/Mojolicious> distribution.
250 .PP
251 Module::Loader is a module for finding and loading modules
252 in a given namespace, inspired by \f(CW\*(C`Mojo::Loader\*(C'\fR.
253 .SH ACKNOWLEDGEMENTS
254 .IX Header "ACKNOWLEDGEMENTS"
255 Thanks to Jonas B. Nielsen for making explicit imports work.
256 .SH "BUG REPORTS"
257 .IX Header "BUG REPORTS"
258 Please report bugs or other issues to <bug\-module\[email protected]>.
259 .SH AUTHOR
260 .IX Header "AUTHOR"
261 This module by Jos Boumans <[email protected]>.
262 .SH COPYRIGHT
263 .IX Header "COPYRIGHT"
264 This library is free software; you may redistribute and/or modify it
265 under the same terms as Perl itself.