Provided by: libmodule-runtime-perl_0.016-2_all bug

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.  This module avoids using any other modules, so that
       it can be used in low-level infrastructure.

       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.

   Module name syntax
       The usable module name syntax has not changed from Perl 5.000 up to Perl 5.19.8.  The
       syntax is composed entirely of ASCII characters.  From Perl 5.6 onwards there has been
       some attempt to allow the use of non-ASCII Unicode characters in Perl source, but it was
       fundamentally broken (like the entirety of Perl 5.6's Unicode handling) and remained
       pretty much entirely unusable until it got some attention in the Perl 5.15 series.
       Although Unicode is now consistently accepted by the parser in some places, it remains
       broken for module names.  Furthermore, there has not yet been any work on how to map
       Unicode module names into filenames, so in that respect also Unicode module names are
       unusable.

       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.

   Core bugs worked around
       The first bug worked around is core bug [perl #68590], which causes lexical state in one
       file to leak into another that is "require"d/"use"d from it.  This bug is present from
       Perl 5.6 up to Perl 5.10, and is fixed in Perl 5.11.0.  From Perl 5.9.4 up to Perl 5.10.0
       no satisfactory workaround is possible in pure Perl.  The workaround means that modules
       loaded via this module don't suffer this pollution of their lexical state.  Modules loaded
       in other ways, or via this module on the Perl versions where the pure Perl workaround is
       impossible, remain vulnerable.  The module Lexical::SealRequireHints provides a complete
       workaround for this bug.

       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.

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.

       $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 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".

   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 "::").

BUGS

       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 isn't available.

SEE ALSO

       Lexical::SealRequireHints, base, "require" in perlfunc, "use" in perlfunc

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011, 2012, 2014, 2017 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.