use Module::Runtime qw(
$module_name_rx is_module_name check_module_name
module_notional_filename require_module);
if($module_name =~ /\A$module_name_rx\z/o) { ...
if(is_module_name($module_name)) { ...
check_module_name($module_name);
$notional_filename = module_notional_filename($module_name);
require_module($module_name);
use Module::Runtime qw(use_module use_package_optimistically);
$bi = use_module("Math::BigInt", 1.31)->new("1_234");
$widget = use_package_optimistically("Local::Widget")->new;
use Module::Runtime qw(
$top_module_spec_rx $sub_module_spec_rx
is_module_spec check_module_spec
compose_module_name);
if($spec =~ /\A$top_module_spec_rx\z/o) { ...
if($spec =~ /\A$sub_module_spec_rx\z/o) { ...
if(is_module_spec("Standard::Prefix", $spec)) { ...
check_module_spec("Standard::Prefix", $spec);
$module_name = compose_module_name("Standard::Prefix", $spec);
The parts of this module that work with module names apply the same syntax that is used for barewords in Perl source. In principle this syntax can vary between versions of Perl, and this module applies the syntax of the Perl on which it is running. In practice the usable syntax hasn't changed yet. There's some intent for Unicode module names to be supported in the future, but this hasn't yet amounted to any consistent facility.
The functions of this module whose purpose is to load modules include workarounds for three old Perl core bugs regarding "require". These workarounds are applied on any Perl version where the bugs exist, except for a case where one of the bugs cannot be adequately worked around in pure Perl.
The module name syntax is, precisely: the string must consist of one or more segments separated by "::"; each segment must consist of one or more identifier characters (ASCII alphanumerics plus ``_''); the first character of the string must not be a digit. Thus ""IO::File"``, ''"warnings"``, and ''"foo::123::x_0"`` are all valid module names, whereas ''"IO::"`` and ''"1foo::bar"" are not. "'" separators are not permitted by this module, though they remain usable in Perl source, being translated to "::" in the parser.
The second bug worked around causes some kinds of failure in module loading, principally compilation errors in the loaded module, to be recorded in %INC as if they were successful, so later attempts to load the same module immediately indicate success. This bug is present up to Perl 5.8.9, and is fixed in Perl 5.9.0. The workaround means that a compilation error in a module loaded via this module won't be cached as a success. Modules loaded in other ways remain liable to produce bogus %INC entries, and if a bogus entry exists then it will mislead this module if it is used to re-attempt loading.
The third bug worked around causes the wrong context to be seen at file scope of a loaded module, if "require" is invoked in a location that inherits context from a higher scope. This bug is present up to Perl 5.11.2, and is fixed in Perl 5.11.3. The workaround means that a module loaded via this module will always see the correct context. Modules loaded in other ways remain vulnerable.
The notional filename for the named module is generated and returned. This filename is always in Unix style, with "/" directory separators and a ".pm" suffix. This kind of filename can be used as an argument to "require", and is the key that appears in %INC to identify a module, regardless of actual local filename syntax.
The module specified by NAME is loaded, if it hasn't been already, in the manner of the bareword form of "require". That means that a search through @INC is performed, and a byte-compiled form of the module will be used if available.
The return value is as for "require". That is, it is the value returned by the module itself if the module is loaded anew, or 1 if the module was already loaded.
If a VERSION is specified, the "VERSION" method of the loaded module is called with the specified VERSION as an argument. This normally serves to ensure that the version loaded is at least the version required. This is the same functionality provided by the VERSION parameter of "use".
On success, the name of the module is returned. This is unlike ``require_module'', and is done so that the entire call to ``use_module'' can be used as a class name to call a constructor, as in the example in the synopsis.
An attempt is made to load the named module (as if by the bareword form of "require"). If the module cannot be found then it is assumed that the package was actually already loaded by other means, and no error is signalled. That's the optimistic bit.
Warning: this optional module loading is liable to cause unreliable behaviour, including security problems. It interacts especially badly with having "." in @INC, which was the default state of affairs in Perls prior to 5.25.11. If a package is actually defined by some means other than a module, then applying this function to it causes a spurious attempt to load a module that is expected to be non-existent. If a module actually exists under that name then it will be unintentionally loaded. If "." is in @INC and this code is ever run with the current directory being one writable by a malicious user (such as /tmp), then the malicious user can easily cause the victim to run arbitrary code, by creating a module file under the predictable spuriously-loaded name in the writable directory. Generally, optional module loading should be avoided.
This is mostly the same operation that is performed by the base pragma to ensure that the specified base classes are available. The behaviour of base was simplified in version 2.18, and later improved in version 2.20, and on both occasions this function changed to match.
If a VERSION is specified, the "VERSION" method of the loaded package is called with the specified VERSION as an argument. This normally serves to ensure that the version loaded is at least the version required. On success, the name of the package is returned. These aspects of the function work just like ``use_module''.
SPEC has syntax approximately that of a standard module name: it should consist of one or more name segments, each of which consists of one or more identifier characters. However, "/" is permitted as a separator, in addition to the standard "::". The two separators are entirely interchangeable.
Additionally, if PREFIX is not "undef" then it must be a module name in standard form, and it is prefixed to the user-specified name. The user can inhibit the prefix addition by starting SPEC with a separator (either "/" or "::").