Debian Codegraph @

upstream/mageia-cauldron/man3pm/Module::Load.3pm

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