|$module_name_rx||Matches a valid Perl module name in bareword syntax.|
|$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.|
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 dies.
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 dies.
The module specified by NAME is loaded, if it hasnt 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.
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 by other means, and no error is signalled. Thats 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 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.
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 ::).
On Perl versions 5.7.2 to 5.8.8, if require is overridden by the CORE::GLOBAL mechanism, it is likely to break the heuristics used by use_package_optimistically, making it signal an error for a missing module rather than assume that it was already loaded. From Perl 5.8.9 onwards, and on 5.7.1 and earlier, this module can avoid being confused by such an override. On the affected versions, a require override might be installed by Lexical::SealRequireHints, if something requires its bugfix but for some reason its XS implementation isnt available.
Lexical::SealRequireHints, base, require in perlfunc, use in perlfunc
Andrew Main (Zefram) <firstname.lastname@example.org>
Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011, 2012, 2014 Andrew Main (Zefram) <email@example.com>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
|perl v5.20.3||MODULE::RUNTIME (3)||2016-03-17|