1Module::Runtime(3)    User Contributed Perl Documentation   Module::Runtime(3)
2
3
4

NAME

6       Module::Runtime - runtime module handling
7

SYNOPSIS

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) { ...
14           if(is_module_name($module_name)) { ...
15           check_module_name($module_name);
16
17           $notional_filename = module_notional_filename($module_name);
18           require_module($module_name);
19
20           use Module::Runtime qw(use_module use_package_optimistically);
21
22           $bi = use_module("Math::BigInt", 1.31)->new("1_234");
23           $widget = use_package_optimistically("Local::Widget")->new;
24
25           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
30           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
35           $module_name = compose_module_name("Standard::Prefix", $spec);
36

DESCRIPTION

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
43       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
51       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
57   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
70       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
79   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
91       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
101       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

REGULAR EXPRESSIONS

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
113       $module_name_rx
114           Matches a valid Perl module name in bareword syntax.
115
116       $top_module_spec_rx
117           Matches a module specification for use with "compose_module_name",
118           where no prefix is being used.
119
120       $sub_module_spec_rx
121           Matches a module specification for use with "compose_module_name",
122           where a prefix is being used.
123

FUNCTIONS

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
131       is_valid_module_name(ARG)
132           Deprecated alias for "is_module_name".
133
134       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
139       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
145           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
152       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
158           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
163           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
167   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
175           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
181           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
186       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
193           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
198           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
213           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
219           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
225   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
233       is_valid_module_spec(PREFIX, SPEC)
234           Deprecated alias for "is_module_spec".
235
236       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
240       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
248           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
254           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

BUGS

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

SEE ALSO

270       Lexical::SealRequireHints, base, "require" in perlfunc, "use" in
271       perlfunc
272

AUTHOR

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

LICENSE

281       This module is free software; you can redistribute it and/or modify it
282       under the same terms as Perl itself.
283
284
285
286perl v5.26.3                      2017-10-17                Module::Runtime(3)
Impressum