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