Module::Runtime(3) User Contributed Perl Documentation Module::Runtime(3)NAME
Module::Runtime - runtime module handling
SYNOPSIS
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);
DESCRIPTION
The functions exported by this module deal with runtime handling of
Perl modules, which are normally handled at compile time.
REGULAR EXPRESSIONS
These regular expressions do not include any anchors, so to check
whether an entire string matches a syntax item you must supply the
anchors yourself.
$module_name_rx
Matches a valid Perl module name in bareword syntax. The rule for
this, precisely, is: the string must consist of one or more
segments separated by "::"; each segment must consist of one or
more identifier characters (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. Only ASCII characters
are permitted; Perl's handling of non-ASCII characters in source
code is inconsistent. "'" separators are not permitted.
$top_module_spec_rx
Matches a module specification for use with "compose_module_name",
where no prefix is being used.
$sub_module_spec_rx
Matches a module specification for use with "compose_module_name",
where a prefix is being used.
FUNCTIONS
Basic module handling
is_module_name(ARG)
Returns a truth value indicating whether ARG is a plain string
satisfying Perl module name syntax as described for
"$module_name_rx".
is_valid_module_name(ARG)
Deprecated alias for "is_module_name".
check_module_name(ARG)
Check whether ARG is a plain string satisfying Perl module name
syntax as described for "$module_name_rx". Return normally if it
is, or "die" if it is not.
module_notional_filename(NAME)
Generates a notional relative filename for a module, which is used
in some Perl core interfaces. The NAME is a string, which should
be a valid module name (one or more "::"-separated segments). If
it is not a valid name, the function "die"s.
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.
require_module(NAME)
This is essentially the bareword form of "require", in runtime
form. The NAME is a string, which should be a valid module name
(one or more "::"-separated segments). If it is not a valid name,
the function "die"s.
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.
Structured module use
use_module(NAME[, VERSION])
This is essentially "use" in runtime form, but without the
importing feature (which is fundamentally a compile-time thing).
The NAME is handled just like in "require_module" above: it must be
a module name, and the named module is loaded as if by the bareword
form of "require".
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.
use_package_optimistically(NAME[, VERSION])
This is an analogue of "use_module" for the situation where there
is uncertainty as to whether a package/class is defined in its own
module or by some other means. It attempts to arrange for the
named package to be available, either by loading a module or by
doing nothing and hoping.
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 but wasn't
detected correctly, and no error is signalled. That's the
optimistic bit.
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 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".
Module name composition
is_module_spec(PREFIX, SPEC)
Returns a truth value indicating whether SPEC is valid input for
"compose_module_name". See below for what that entails. Whether a
PREFIX is supplied affects the validity of SPEC, but the exact
value of the prefix is unimportant, so this function treats PREFIX
as a truth value.
is_valid_module_spec(PREFIX, SPEC)
Deprecated alias for "is_module_spec".
check_module_spec(PREFIX, SPEC)
Check whether SPEC is valid input for "compose_module_name".
Return normally if it is, or "die" if it is not.
compose_module_name(PREFIX, SPEC)
This function is intended to make it more convenient for a user to
specify a Perl module name at runtime. Users have greater need for
abbreviations and context-sensitivity than programmers, and Perl
module names get a little unwieldy. SPEC is what the user
specifies, and this function translates it into a module name in
standard form, which it returns.
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 "::").
SEE ALSO
base, "require" in perlfunc, "use" in perlfunc
AUTHOR
Andrew Main (Zefram) <zefram@fysh.org>
COPYRIGHT
Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011 Andrew Main (Zefram)
<zefram@fysh.org>
LICENSE
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.12.5 2013-08-25 Module::Runtime(3)
