1Module::Runtime(3) User Contributed Perl Documentation Module::Runtime(3)
2
6 Module::Runtime - runtime module handling
7
9 use Module::Runtime qw(
10 $module_name_rx is_module_name check_module_name
11 module_notional_filename require_module);
12 if($module_name =~ /\A$module_name_rx\z/o) { ...
14 if(is_module_name($module_name)) { ...
15 check_module_name($module_name);
16 $notional_filename = module_notional_filename($module_name);
18 require_module($module_name);
19 use Module::Runtime qw(use_module use_package_optimistically);
21 $bi = use_module("Math::BigInt", 1.31)->new("1_234");
23 $widget = use_package_optimistically("Local::Widget")->new;
24 use Module::Runtime qw(
26 $top_module_spec_rx $sub_module_spec_rx
27 is_module_spec check_module_spec
28 compose_module_name);
29 if($spec =~ /\A$top_module_spec_rx\z/o) { ...
31 if($spec =~ /\A$sub_module_spec_rx\z/o) { ...
32 if(is_module_spec("Standard::Prefix", $spec)) { ...
33 check_module_spec("Standard::Prefix", $spec);
34 $module_name = compose_module_name("Standard::Prefix", $spec);
36
38 The functions exported by this module deal with runtime handling of
39 Perl modules, which are normally handled at compile time. This module
40 avoids using any other modules, so that it can be used in low-level
41 infrastructure.
42 The parts of this module that work with module names apply the same
44 syntax that is used for barewords in Perl source. In principle this
45 syntax can vary between versions of Perl, and this module applies the
46 syntax of the Perl on which it is running. In practice the usable
47 syntax hasn't changed yet. There's some intent for Unicode module
48 names to be supported in the future, but this hasn't yet amounted to
49 any consistent facility.
50 The functions of this module whose purpose is to load modules include
52 workarounds for three old Perl core bugs regarding "require". These
53 workarounds are applied on any Perl version where the bugs exist,
54 except for a case where one of the bugs cannot be adequately worked
55 around in pure Perl.
56 Module name syntax
58 The usable module name syntax has not changed from Perl 5.000 up to
59 Perl 5.19.8. The syntax is composed entirely of ASCII characters.
60 From Perl 5.6 onwards there has been some attempt to allow the use of
61 non-ASCII Unicode characters in Perl source, but it was fundamentally
62 broken (like the entirety of Perl 5.6's Unicode handling) and remained
63 pretty much entirely unusable until it got some attention in the Perl
64 5.15 series. Although Unicode is now consistently accepted by the
65 parser in some places, it remains broken for module names.
66 Furthermore, there has not yet been any work on how to map Unicode
67 module names into filenames, so in that respect also Unicode module
68 names are unusable.
69 The module name syntax is, precisely: the string must consist of one or
71 more segments separated by "::"; each segment must consist of one or
72 more identifier characters (ASCII alphanumerics plus "_"); the first
73 character of the string must not be a digit. Thus ""IO::File"",
74 ""warnings"", and ""foo::123::x_0"" are all valid module names, whereas
75 ""IO::"" and ""1foo::bar"" are not. "'" separators are not permitted
76 by this module, though they remain usable in Perl source, being
77 translated to "::" in the parser.
78 Core bugs worked around
80 The first bug worked around is core bug [perl #68590], which causes
81 lexical state in one file to leak into another that is
82 "require"d/"use"d from it. This bug is present from Perl 5.6 up to
83 Perl 5.10, and is fixed in Perl 5.11.0. From Perl 5.9.4 up to Perl
84 5.10.0 no satisfactory workaround is possible in pure Perl. The
85 workaround means that modules loaded via this module don't suffer this
86 pollution of their lexical state. Modules loaded in other ways, or via
87 this module on the Perl versions where the pure Perl workaround is
88 impossible, remain vulnerable. The module Lexical::SealRequireHints
89 provides a complete workaround for this bug.
90 The second bug worked around causes some kinds of failure in module
92 loading, principally compilation errors in the loaded module, to be
93 recorded in %INC as if they were successful, so later attempts to load
94 the same module immediately indicate success. This bug is present up
95 to Perl 5.8.9, and is fixed in Perl 5.9.0. The workaround means that a
96 compilation error in a module loaded via this module won't be cached as
97 a success. Modules loaded in other ways remain liable to produce bogus
98 %INC entries, and if a bogus entry exists then it will mislead this
99 module if it is used to re-attempt loading.
100 The third bug worked around causes the wrong context to be seen at file
102 scope of a loaded module, if "require" is invoked in a location that
103 inherits context from a higher scope. This bug is present up to Perl
104 5.11.2, and is fixed in Perl 5.11.3. The workaround means that a
105 module loaded via this module will always see the correct context.
106 Modules loaded in other ways remain vulnerable.
107
109 These regular expressions do not include any anchors, so to check
110 whether an entire string matches a syntax item you must supply the
111 anchors yourself.
112 $module_name_rx
114 Matches a valid Perl module name in bareword syntax.
115 $top_module_spec_rx
117 Matches a module specification for use with "compose_module_name",
118 where no prefix is being used.
119 $sub_module_spec_rx
121 Matches a module specification for use with "compose_module_name",
122 where a prefix is being used.
123
125 Basic module handling
126 is_module_name(ARG)
127 Returns a truth value indicating whether ARG is a plain string
128 satisfying Perl module name syntax as described for
129 "$module_name_rx".
130 is_valid_module_name(ARG)
132 Deprecated alias for "is_module_name".
133 check_module_name(ARG)
135 Check whether ARG is a plain string satisfying Perl module name
136 syntax as described for "$module_name_rx". Return normally if it
137 is, or "die" if it is not.
138 module_notional_filename(NAME)
140 Generates a notional relative filename for a module, which is used
141 in some Perl core interfaces. The NAME is a string, which should
142 be a valid module name (one or more "::"-separated segments). If
143 it is not a valid name, the function "die"s.
144 The notional filename for the named module is generated and
146 returned. This filename is always in Unix style, with "/"
147 directory separators and a ".pm" suffix. This kind of filename can
148 be used as an argument to "require", and is the key that appears in
149 %INC to identify a module, regardless of actual local filename
150 syntax.
151 require_module(NAME)
153 This is essentially the bareword form of "require", in runtime
154 form. The NAME is a string, which should be a valid module name
155 (one or more "::"-separated segments). If it is not a valid name,
156 the function "die"s.
157 The module specified by NAME is loaded, if it hasn't been already,
159 in the manner of the bareword form of "require". That means that a
160 search through @INC is performed, and a byte-compiled form of the
161 module will be used if available.
162 The return value is as for "require". That is, it is the value
164 returned by the module itself if the module is loaded anew, or 1 if
165 the module was already loaded.
166 Structured module use
168 use_module(NAME[, VERSION])
169 This is essentially "use" in runtime form, but without the
170 importing feature (which is fundamentally a compile-time thing).
171 The NAME is handled just like in "require_module" above: it must be
172 a module name, and the named module is loaded as if by the bareword
173 form of "require".
174 If a VERSION is specified, the "VERSION" method of the loaded
176 module is called with the specified VERSION as an argument. This
177 normally serves to ensure that the version loaded is at least the
178 version required. This is the same functionality provided by the
179 VERSION parameter of "use".
180 On success, the name of the module is returned. This is unlike
182 "require_module", and is done so that the entire call to
183 "use_module" can be used as a class name to call a constructor, as
184 in the example in the synopsis.
185 use_package_optimistically(NAME[, VERSION])
187 This is an analogue of "use_module" for the situation where there
188 is uncertainty as to whether a package/class is defined in its own
189 module or by some other means. It attempts to arrange for the
190 named package to be available, either by loading a module or by
191 doing nothing and hoping.
192 An attempt is made to load the named module (as if by the bareword
194 form of "require"). If the module cannot be found then it is
195 assumed that the package was actually already loaded by other
196 means, and no error is signalled. That's the optimistic bit.
197 Warning: this optional module loading is liable to cause unreliable
199 behaviour, including security problems. It interacts especially
200 badly with having "." in @INC, which was the default state of
201 affairs in Perls prior to 5.25.11. If a package is actually
202 defined by some means other than a module, then applying this
203 function to it causes a spurious attempt to load a module that is
204 expected to be non-existent. If a module actually exists under
205 that name then it will be unintentionally loaded. If "." is in
206 @INC and this code is ever run with the current directory being one
207 writable by a malicious user (such as /tmp), then the malicious
208 user can easily cause the victim to run arbitrary code, by creating
209 a module file under the predictable spuriously-loaded name in the
210 writable directory. Generally, optional module loading should be
211 avoided.
212 This is mostly the same operation that is performed by the base
214 pragma to ensure that the specified base classes are available.
215 The behaviour of base was simplified in version 2.18, and later
216 improved in version 2.20, and on both occasions this function
217 changed to match.
218 If a VERSION is specified, the "VERSION" method of the loaded
220 package is called with the specified VERSION as an argument. This
221 normally serves to ensure that the version loaded is at least the
222 version required. On success, the name of the package is returned.
223 These aspects of the function work just like "use_module".
224 Module name composition
226 is_module_spec(PREFIX, SPEC)
227 Returns a truth value indicating whether SPEC is valid input for
228 "compose_module_name". See below for what that entails. Whether a
229 PREFIX is supplied affects the validity of SPEC, but the exact
230 value of the prefix is unimportant, so this function treats PREFIX
231 as a truth value.
232 is_valid_module_spec(PREFIX, SPEC)
234 Deprecated alias for "is_module_spec".
235 check_module_spec(PREFIX, SPEC)
237 Check whether SPEC is valid input for "compose_module_name".
238 Return normally if it is, or "die" if it is not.
239 compose_module_name(PREFIX, SPEC)
241 This function is intended to make it more convenient for a user to
242 specify a Perl module name at runtime. Users have greater need for
243 abbreviations and context-sensitivity than programmers, and Perl
244 module names get a little unwieldy. SPEC is what the user
245 specifies, and this function translates it into a module name in
246 standard form, which it returns.
247 SPEC has syntax approximately that of a standard module name: it
249 should consist of one or more name segments, each of which consists
250 of one or more identifier characters. However, "/" is permitted as
251 a separator, in addition to the standard "::". The two separators
252 are entirely interchangeable.
253 Additionally, if PREFIX is not "undef" then it must be a module
255 name in standard form, and it is prefixed to the user-specified
256 name. The user can inhibit the prefix addition by starting SPEC
257 with a separator (either "/" or "::").
258
260 On Perl versions 5.7.2 to 5.8.8, if "require" is overridden by the
261 "CORE::GLOBAL" mechanism, it is likely to break the heuristics used by
262 "use_package_optimistically", making it signal an error for a missing
263 module rather than assume that it was already loaded. From Perl 5.8.9
264 onwards, and on 5.7.1 and earlier, this module can avoid being confused
265 by such an override. On the affected versions, a "require" override
266 might be installed by Lexical::SealRequireHints, if something requires
267 its bugfix but for some reason its XS implementation isn't available.
268
270 Lexical::SealRequireHints, base, "require" in perlfunc, "use" in
271 perlfunc
272
274 Andrew Main (Zefram) <zefram@fysh.org>
275
277 Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011, 2012, 2014, 2017
278 Andrew Main (Zefram) <zefram@fysh.org>
279
281 This module is free software; you can redistribute it and/or modify it
282 under the same terms as Perl itself.
283perl v5.38.0 2023-07-20 Module::Runtime(3)