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 );
13 if($module_name =~ /\A$module_name_rx\z/o) { ...
15 if(is_module_name($module_name)) { ...
16 check_module_name($module_name);
17 $notional_filename = module_notional_filename($module_name);
19 require_module($module_name);
20 use Module::Runtime qw(use_module use_package_optimistically);
22 $bi = use_module("Math::BigInt", 1.31)->new("1_234");
24 $widget = use_package_optimistically("Local::Widget")->new;
25 use Module::Runtime qw(
27 $top_module_spec_rx $sub_module_spec_rx
28 is_module_spec check_module_spec
29 compose_module_name
30 );
31 if($spec =~ /\A$top_module_spec_rx\z/o) { ...
33 if($spec =~ /\A$sub_module_spec_rx\z/o) { ...
34 if(is_module_spec("Standard::Prefix", $spec)) { ...
35 check_module_spec("Standard::Prefix", $spec);
36 $module_name =
38 compose_module_name("Standard::Prefix", $spec);
39
41 The functions exported by this module deal with runtime handling of
42 Perl modules, which are normally handled at compile time. This module
43 avoids using any other modules, so that it can be used in low-level
44 infrastructure.
45 The parts of this module that work with module names apply the same
47 syntax that is used for barewords in Perl source. In principle this
48 syntax can vary between versions of Perl, and this module applies the
49 syntax of the Perl on which it is running. In practice the usable
50 syntax hasn't changed yet, but there's a good chance of it changing in
51 Perl 5.18.
52 The functions of this module whose purpose is to load modules include
54 workarounds for three old Perl core bugs regarding "require". These
55 workarounds are applied on any Perl version where the bugs exist,
56 except for a case where one of the bugs cannot be adequately worked
57 around in pure Perl.
58 Module name syntax
60 The usable module name syntax has not changed from Perl 5.000 up to
61 Perl 5.15.7. The syntax is composed entirely of ASCII characters.
62 From Perl 5.6 onwards there has been some attempt to allow the use of
63 non-ASCII Unicode characters in Perl source, but it was fundamentally
64 broken (like the entirety of Perl 5.6's Unicode handling) and remained
65 pretty much entirely unusable until it got some attention in the Perl
66 5.15 series. Although Unicode is now consistently accepted by the
67 parser in some places, it remains broken for module names.
68 Furthermore, there has not yet been any work on how to map Unicode
69 module names into filenames, so in that respect also Unicode module
70 names are unusable. This may finally be addressed in the Perl 5.17
71 series.
72 The module name syntax is, precisely: the string must consist of one or
74 more segments separated by "::"; each segment must consist of one or
75 more identifier characters (ASCII alphanumerics plus "_"); the first
76 character of the string must not be a digit. Thus ""IO::File"",
77 ""warnings"", and ""foo::123::x_0"" are all valid module names, whereas
78 ""IO::"" and ""1foo::bar"" are not. "'" separators are not permitted
79 by this module, though they remain usable in Perl source, being
80 translated to "::" in the parser.
81 Core bugs worked around
83 The first bug worked around is core bug [perl #68590], which causes
84 lexical state in one file to leak into another that is
85 "require"d/"use"d from it. This bug is present from Perl 5.6 up to
86 Perl 5.10, and is fixed in Perl 5.11.0. From Perl 5.9.4 up to Perl
87 5.10.0 no satisfactory workaround is possible in pure Perl. The
88 workaround means that modules loaded via this module don't suffer this
89 pollution of their lexical state. Modules loaded in other ways, or via
90 this module on the Perl versions where the pure Perl workaround is
91 impossible, remain vulnerable. The module Lexical::SealRequireHints
92 provides a complete workaround for this bug.
93 The second bug worked around causes some kinds of failure in module
95 loading, principally compilation errors in the loaded module, to be
96 recorded in %INC as if they were successful, so later attempts to load
97 the same module immediately indicate success. This bug is present up
98 to Perl 5.8.9, and is fixed in Perl 5.9.0. The workaround means that a
99 compilation error in a module loaded via this module won't be cached as
100 a success. Modules loaded in other ways remain liable to produce bogus
101 %INC entries, and if a bogus entry exists then it will mislead this
102 module if it is used to re-attempt loading.
103 The third bug worked around causes the wrong context to be seen at file
105 scope of a loaded module, if "require" is invoked in a location that
106 inherits context from a higher scope. This bug is present up to Perl
107 5.11.2, and is fixed in Perl 5.11.3. The workaround means that a
108 module loaded via this module will always see the correct context.
109 Modules loaded in other ways remain vulnerable.
110
112 These regular expressions do not include any anchors, so to check
113 whether an entire string matches a syntax item you must supply the
114 anchors yourself.
115 $module_name_rx
117 Matches a valid Perl module name in bareword syntax.
118 $top_module_spec_rx
120 Matches a module specification for use with "compose_module_name",
121 where no prefix is being used.
122 $sub_module_spec_rx
124 Matches a module specification for use with "compose_module_name",
125 where a prefix is being used.
126
128 Basic module handling
129 is_module_name(ARG)
130 Returns a truth value indicating whether ARG is a plain string
131 satisfying Perl module name syntax as described for
132 "$module_name_rx".
133 is_valid_module_name(ARG)
135 Deprecated alias for "is_module_name".
136 check_module_name(ARG)
138 Check whether ARG is a plain string satisfying Perl module name
139 syntax as described for "$module_name_rx". Return normally if it
140 is, or "die" if it is not.
141 module_notional_filename(NAME)
143 Generates a notional relative filename for a module, which is used
144 in some Perl core interfaces. The NAME is a string, which should
145 be a valid module name (one or more "::"-separated segments). If
146 it is not a valid name, the function "die"s.
147 The notional filename for the named module is generated and
149 returned. This filename is always in Unix style, with "/"
150 directory separators and a ".pm" suffix. This kind of filename can
151 be used as an argument to "require", and is the key that appears in
152 %INC to identify a module, regardless of actual local filename
153 syntax.
154 require_module(NAME)
156 This is essentially the bareword form of "require", in runtime
157 form. The NAME is a string, which should be a valid module name
158 (one or more "::"-separated segments). If it is not a valid name,
159 the function "die"s.
160 The module specified by NAME is loaded, if it hasn't been already,
162 in the manner of the bareword form of "require". That means that a
163 search through @INC is performed, and a byte-compiled form of the
164 module will be used if available.
165 The return value is as for "require". That is, it is the value
167 returned by the module itself if the module is loaded anew, or 1 if
168 the module was already loaded.
169 Structured module use
171 use_module(NAME[, VERSION])
172 This is essentially "use" in runtime form, but without the
173 importing feature (which is fundamentally a compile-time thing).
174 The NAME is handled just like in "require_module" above: it must be
175 a module name, and the named module is loaded as if by the bareword
176 form of "require".
177 If a VERSION is specified, the "VERSION" method of the loaded
179 module is called with the specified VERSION as an argument. This
180 normally serves to ensure that the version loaded is at least the
181 version required. This is the same functionality provided by the
182 VERSION parameter of "use".
183 On success, the name of the module is returned. This is unlike
185 "require_module", and is done so that the entire call to
186 "use_module" can be used as a class name to call a constructor, as
187 in the example in the synopsis.
188 use_package_optimistically(NAME[, VERSION])
190 This is an analogue of "use_module" for the situation where there
191 is uncertainty as to whether a package/class is defined in its own
192 module or by some other means. It attempts to arrange for the
193 named package to be available, either by loading a module or by
194 doing nothing and hoping.
195 An attempt is made to load the named module (as if by the bareword
197 form of "require"). If the module cannot be found then it is
198 assumed that the package was actually already loaded by other
199 means, and no error is signalled. That's the optimistic bit.
200 This is mostly the same operation that is performed by the base
202 pragma to ensure that the specified base classes are available.
203 The behaviour of base was simplified in version 2.18, and this
204 function changed to match.
205 If a VERSION is specified, the "VERSION" method of the loaded
207 package is called with the specified VERSION as an argument. This
208 normally serves to ensure that the version loaded is at least the
209 version required. On success, the name of the package is returned.
210 These aspects of the function work just like "use_module".
211 Module name composition
213 is_module_spec(PREFIX, SPEC)
214 Returns a truth value indicating whether SPEC is valid input for
215 "compose_module_name". See below for what that entails. Whether a
216 PREFIX is supplied affects the validity of SPEC, but the exact
217 value of the prefix is unimportant, so this function treats PREFIX
218 as a truth value.
219 is_valid_module_spec(PREFIX, SPEC)
221 Deprecated alias for "is_module_spec".
222 check_module_spec(PREFIX, SPEC)
224 Check whether SPEC is valid input for "compose_module_name".
225 Return normally if it is, or "die" if it is not.
226 compose_module_name(PREFIX, SPEC)
228 This function is intended to make it more convenient for a user to
229 specify a Perl module name at runtime. Users have greater need for
230 abbreviations and context-sensitivity than programmers, and Perl
231 module names get a little unwieldy. SPEC is what the user
232 specifies, and this function translates it into a module name in
233 standard form, which it returns.
234 SPEC has syntax approximately that of a standard module name: it
236 should consist of one or more name segments, each of which consists
237 of one or more identifier characters. However, "/" is permitted as
238 a separator, in addition to the standard "::". The two separators
239 are entirely interchangeable.
240 Additionally, if PREFIX is not "undef" then it must be a module
242 name in standard form, and it is prefixed to the user-specified
243 name. The user can inhibit the prefix addition by starting SPEC
244 with a separator (either "/" or "::").
245
247 Lexical::SealRequireHints, base, "require" in perlfunc, "use" in
248 perlfunc
249
251 Andrew Main (Zefram) <zefram@fysh.org>
252
254 Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011, 2012 Andrew Main
255 (Zefram) <zefram@fysh.org>
256
258 This module is free software; you can redistribute it and/or modify it
259 under the same terms as Perl itself.
260perl v5.16.3 2014-06-09 Module::Runtime(3)