.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Module::Runtime 3"
.TH Module::Runtime 3 "2016-08-24" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Module::Runtime \- runtime module handling
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&        use Module::Runtime qw(
\&                $module_name_rx is_module_name check_module_name
\&                module_notional_filename require_module
\&        );
\&
\&        if($module_name =~ /\eA$module_name_rx\ez/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 =~ /\eA$top_module_spec_rx\ez/o) { ...
\&        if($spec =~ /\eA$sub_module_spec_rx\ez/o) { ...
\&        if(is_module_spec("Standard::Prefix", $spec)) { ...
\&        check_module_spec("Standard::Prefix", $spec);
\&
\&        $module_name =
\&                compose_module_name("Standard::Prefix", $spec);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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.
.PP
The functions of this module whose purpose is to load modules include
workarounds for three old Perl core bugs regarding \f(CW\*(C`require\*(C'\fR.  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.
.SS "Module name syntax"
.IX Subsection "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 \s-1ASCII\s0 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.
.PP
The module name syntax is, precisely: the string must consist of one or
more segments separated by \f(CW\*(C`::\*(C'\fR; each segment must consist of one or more
identifier characters (\s-1ASCII\s0 alphanumerics plus \*(L"_\*(R"); the first character
of the string must not be a digit.  Thus "\f(CW\*(C`IO::File\*(C'\fR\*(L", \*(R"\f(CW\*(C`warnings\*(C'\fR\*(L",
and \*(R"\f(CW\*(C`foo::123::x_0\*(C'\fR\*(L" are all valid module names, whereas \*(R"\f(CW\*(C`IO::\*(C'\fR\*(L"
and \*(R"\f(CW\*(C`1foo::bar\*(C'\fR" are not.  \f(CW\*(C`\*(Aq\*(C'\fR separators are not permitted by this
module, though they remain usable in Perl source, being translated to
\&\f(CW\*(C`::\*(C'\fR in the parser.
.SS "Core bugs worked around"
.IX Subsection "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 \f(CW\*(C`require\*(C'\fRd/\f(CW\*(C`use\*(C'\fRd
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.
.PP
The second bug worked around causes some kinds of failure in module
loading, principally compilation errors in the loaded module, to be
recorded in \f(CW%INC\fR 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
\&\f(CW%INC\fR entries, and if a bogus entry exists then it will mislead this
module if it is used to re-attempt loading.
.PP
The third bug worked around causes the wrong context to be seen at
file scope of a loaded module, if \f(CW\*(C`require\*(C'\fR 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.
.SH "REGULAR EXPRESSIONS"
.IX Header "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.
.ie n .IP "$module_name_rx" 4
.el .IP "\f(CW$module_name_rx\fR" 4
.IX Item "$module_name_rx"
Matches a valid Perl module name in bareword syntax.
.ie n .IP "$top_module_spec_rx" 4
.el .IP "\f(CW$top_module_spec_rx\fR" 4
.IX Item "$top_module_spec_rx"
Matches a module specification for use with \*(L"compose_module_name\*(R",
where no prefix is being used.
.ie n .IP "$sub_module_spec_rx" 4
.el .IP "\f(CW$sub_module_spec_rx\fR" 4
.IX Item "$sub_module_spec_rx"
Matches a module specification for use with \*(L"compose_module_name\*(R",
where a prefix is being used.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "Basic module handling"
.IX Subsection "Basic module handling"
.IP "is_module_name(\s-1ARG\s0)" 4
.IX Item "is_module_name(ARG)"
Returns a truth value indicating whether \fI\s-1ARG\s0\fR is a plain string
satisfying Perl module name syntax as described for \*(L"$module_name_rx\*(R".
.IP "is_valid_module_name(\s-1ARG\s0)" 4
.IX Item "is_valid_module_name(ARG)"
Deprecated alias for \*(L"is_module_name\*(R".
.IP "check_module_name(\s-1ARG\s0)" 4
.IX Item "check_module_name(ARG)"
Check whether \fI\s-1ARG\s0\fR is a plain string
satisfying Perl module name syntax as described for \*(L"$module_name_rx\*(R".
Return normally if it is, or \f(CW\*(C`die\*(C'\fR if it is not.
.IP "module_notional_filename(\s-1NAME\s0)" 4
.IX Item "module_notional_filename(NAME)"
Generates a notional relative filename for a module, which is used in
some Perl core interfaces.
The \fI\s-1NAME\s0\fR is a string, which should be a valid module name (one or
more \f(CW\*(C`::\*(C'\fR\-separated segments).  If it is not a valid name, the function
\&\f(CW\*(C`die\*(C'\fRs.
.Sp
The notional filename for the named module is generated and returned.
This filename is always in Unix style, with \f(CW\*(C`/\*(C'\fR directory separators
and a \f(CW\*(C`.pm\*(C'\fR suffix.  This kind of filename can be used as an argument to
\&\f(CW\*(C`require\*(C'\fR, and is the key that appears in \f(CW%INC\fR to identify a module,
regardless of actual local filename syntax.
.IP "require_module(\s-1NAME\s0)" 4
.IX Item "require_module(NAME)"
This is essentially the bareword form of \f(CW\*(C`require\*(C'\fR, in runtime form.
The \fI\s-1NAME\s0\fR is a string, which should be a valid module name (one or
more \f(CW\*(C`::\*(C'\fR\-separated segments).  If it is not a valid name, the function
\&\f(CW\*(C`die\*(C'\fRs.
.Sp
The module specified by \fI\s-1NAME\s0\fR is loaded, if it hasn't been already,
in the manner of the bareword form of \f(CW\*(C`require\*(C'\fR.  That means that a
search through \f(CW@INC\fR is performed, and a byte-compiled form of the
module will be used if available.
.Sp
The return value is as for \f(CW\*(C`require\*(C'\fR.  That is, it is the value returned
by the module itself if the module is loaded anew, or \f(CW1\fR if the module
was already loaded.
.SS "Structured module use"
.IX Subsection "Structured module use"
.IP "use_module(NAME[, \s-1VERSION\s0])" 4
.IX Item "use_module(NAME[, VERSION])"
This is essentially \f(CW\*(C`use\*(C'\fR in runtime form, but without the importing
feature (which is fundamentally a compile-time thing).  The \fI\s-1NAME\s0\fR is
handled just like in \f(CW\*(C`require_module\*(C'\fR above: it must be a module name,
and the named module is loaded as if by the bareword form of \f(CW\*(C`require\*(C'\fR.
.Sp
If a \fI\s-1VERSION\s0\fR is specified, the \f(CW\*(C`VERSION\*(C'\fR method of the loaded module is
called with the specified \fI\s-1VERSION\s0\fR 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 \fI\s-1VERSION\s0\fR parameter of \f(CW\*(C`use\*(C'\fR.
.Sp
On success, the name of the module is returned.  This is unlike
\&\*(L"require_module\*(R", and is done so that the entire call to \*(L"use_module\*(R"
can be used as a class name to call a constructor, as in the example in
the synopsis.
.IP "use_package_optimistically(NAME[, \s-1VERSION\s0])" 4
.IX Item "use_package_optimistically(NAME[, VERSION])"
This is an analogue of \*(L"use_module\*(R" 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.
.Sp
An attempt is made to load the named module (as if by the bareword form
of \f(CW\*(C`require\*(C'\fR).  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.
.Sp
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.
.Sp
If a \fI\s-1VERSION\s0\fR is specified, the \f(CW\*(C`VERSION\*(C'\fR method of the loaded package is
called with the specified \fI\s-1VERSION\s0\fR 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 \*(L"use_module\*(R".
.SS "Module name composition"
.IX Subsection "Module name composition"
.IP "is_module_spec(\s-1PREFIX, SPEC\s0)" 4
.IX Item "is_module_spec(PREFIX, SPEC)"
Returns a truth value indicating
whether \fI\s-1SPEC\s0\fR is valid input for \*(L"compose_module_name\*(R".
See below for what that entails.  Whether a \fI\s-1PREFIX\s0\fR is supplied affects
the validity of \fI\s-1SPEC\s0\fR, but the exact value of the prefix is unimportant,
so this function treats \fI\s-1PREFIX\s0\fR as a truth value.
.IP "is_valid_module_spec(\s-1PREFIX, SPEC\s0)" 4
.IX Item "is_valid_module_spec(PREFIX, SPEC)"
Deprecated alias for \*(L"is_module_spec\*(R".
.IP "check_module_spec(\s-1PREFIX, SPEC\s0)" 4
.IX Item "check_module_spec(PREFIX, SPEC)"
Check whether \fI\s-1SPEC\s0\fR is valid input for \*(L"compose_module_name\*(R".
Return normally if it is, or \f(CW\*(C`die\*(C'\fR if it is not.
.IP "compose_module_name(\s-1PREFIX, SPEC\s0)" 4
.IX Item "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.  \fI\s-1SPEC\s0\fR is what the user specifies, and this function
translates it into a module name in standard form, which it returns.
.Sp
\&\fI\s-1SPEC\s0\fR 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, \f(CW\*(C`/\*(C'\fR is permitted as a
separator, in addition to the standard \f(CW\*(C`::\*(C'\fR.  The two separators are
entirely interchangeable.
.Sp
Additionally, if \fI\s-1PREFIX\s0\fR is not \f(CW\*(C`undef\*(C'\fR 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 \fI\s-1SPEC\s0\fR with a
separator (either \f(CW\*(C`/\*(C'\fR or \f(CW\*(C`::\*(C'\fR).
.SH "BUGS"
.IX Header "BUGS"
On Perl versions 5.7.2 to 5.8.8, if \f(CW\*(C`require\*(C'\fR is overridden by the
\&\f(CW\*(C`CORE::GLOBAL\*(C'\fR mechanism, it is likely to break the heuristics used by
\&\*(L"use_package_optimistically\*(R", 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 \f(CW\*(C`require\*(C'\fR override
might be installed by Lexical::SealRequireHints, if something requires
its bugfix but for some reason its \s-1XS\s0 implementation isn't available.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Lexical::SealRequireHints,
base,
\&\*(L"require\*(R" in perlfunc,
\&\*(L"use\*(R" in perlfunc
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Main (Zefram) <zefram@fysh.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011, 2012, 2014
Andrew Main (Zefram) <zefram@fysh.org>
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.