{
    "mode": "info",
    "parameter": "Module::Runtime",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/info/Module%3A%3ARuntime/json",
    "generated": "2026-07-05T13:02:04Z",
    "synopsis": "use Module::Runtime qw(\n$modulenamerx ismodulename checkmodulename\nmodulenotionalfilename requiremodule);\nif($modulename =~ /\\A$modulenamerx\\z/o) { ...\nif(ismodulename($modulename)) { ...\ncheckmodulename($modulename);\n$notionalfilename = modulenotionalfilename($modulename);\nrequiremodule($modulename);\nuse Module::Runtime qw(usemodule usepackageoptimistically);\n$bi = usemodule(\"Math::BigInt\", 1.31)->new(\"1234\");\n$widget = usepackageoptimistically(\"Local::Widget\")->new;\nuse Module::Runtime qw(\n$topmodulespecrx $submodulespecrx\nismodulespec checkmodulespec\ncomposemodulename);\nif($spec =~ /\\A$topmodulespecrx\\z/o) { ...\nif($spec =~ /\\A$submodulespecrx\\z/o) { ...\nif(ismodulespec(\"Standard::Prefix\", $spec)) { ...\ncheckmodulespec(\"Standard::Prefix\", $spec);\n$modulename = composemodulename(\"Standard::Prefix\", $spec);",
    "sections": {
        "Module::Runtime(3pm)  User Contributed Perl Documentation Module::Runtime(3pm)": {
            "content": "",
            "subsections": []
        },
        "NAME": {
            "content": "Module::Runtime - runtime module handling\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Module::Runtime qw(\n$modulenamerx ismodulename checkmodulename\nmodulenotionalfilename requiremodule);\n\nif($modulename =~ /\\A$modulenamerx\\z/o) { ...\nif(ismodulename($modulename)) { ...\ncheckmodulename($modulename);\n\n$notionalfilename = modulenotionalfilename($modulename);\nrequiremodule($modulename);\n\nuse Module::Runtime qw(usemodule usepackageoptimistically);\n\n$bi = usemodule(\"Math::BigInt\", 1.31)->new(\"1234\");\n$widget = usepackageoptimistically(\"Local::Widget\")->new;\n\nuse Module::Runtime qw(\n$topmodulespecrx $submodulespecrx\nismodulespec checkmodulespec\ncomposemodulename);\n\nif($spec =~ /\\A$topmodulespecrx\\z/o) { ...\nif($spec =~ /\\A$submodulespecrx\\z/o) { ...\nif(ismodulespec(\"Standard::Prefix\", $spec)) { ...\ncheckmodulespec(\"Standard::Prefix\", $spec);\n\n$modulename = composemodulename(\"Standard::Prefix\", $spec);\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The functions exported by this module deal with runtime handling of\nPerl modules, which are normally handled at compile time.  This module\navoids using any other modules, so that it can be used in low-level\ninfrastructure.\n\nThe parts of this module that work with module names apply the same\nsyntax that is used for barewords in Perl source.  In principle this\nsyntax can vary between versions of Perl, and this module applies the\nsyntax of the Perl on which it is running.  In practice the usable\nsyntax hasn't changed yet.  There's some intent for Unicode module\nnames to be supported in the future, but this hasn't yet amounted to\nany consistent facility.\n\nThe functions of this module whose purpose is to load modules include\nworkarounds for three old Perl core bugs regarding \"require\".  These\nworkarounds are applied on any Perl version where the bugs exist,\nexcept for a case where one of the bugs cannot be adequately worked\naround in pure Perl.\n\nModule name syntax\nThe usable module name syntax has not changed from Perl 5.000 up to\nPerl 5.19.8.  The syntax is composed entirely of ASCII characters.\nFrom Perl 5.6 onwards there has been some attempt to allow the use of\nnon-ASCII Unicode characters in Perl source, but it was fundamentally\nbroken (like the entirety of Perl 5.6's Unicode handling) and remained\npretty much entirely unusable until it got some attention in the Perl\n5.15 series.  Although Unicode is now consistently accepted by the\nparser in some places, it remains broken for module names.\nFurthermore, there has not yet been any work on how to map Unicode\nmodule names into filenames, so in that respect also Unicode module\nnames are unusable.\n\nThe module name syntax is, precisely: the string must consist of one or\nmore segments separated by \"::\"; each segment must consist of one or\nmore identifier characters (ASCII alphanumerics plus \"\"); the first\ncharacter of the string must not be a digit.  Thus \"\"IO::File\"\",\n\"\"warnings\"\", and \"\"foo::123::x0\"\" are all valid module names, whereas\n\"\"IO::\"\" and \"\"1foo::bar\"\" are not.  \"'\" separators are not permitted\nby this module, though they remain usable in Perl source, being\ntranslated to \"::\" in the parser.\n\nCore bugs worked around\nThe first bug worked around is core bug [perl #68590], which causes\nlexical state in one file to leak into another that is\n\"require\"d/\"use\"d from it.  This bug is present from Perl 5.6 up to\nPerl 5.10, and is fixed in Perl 5.11.0.  From Perl 5.9.4 up to Perl\n5.10.0 no satisfactory workaround is possible in pure Perl.  The\nworkaround means that modules loaded via this module don't suffer this\npollution of their lexical state.  Modules loaded in other ways, or via\nthis module on the Perl versions where the pure Perl workaround is\nimpossible, remain vulnerable.  The module Lexical::SealRequireHints\nprovides a complete workaround for this bug.\n\nThe second bug worked around causes some kinds of failure in module\nloading, principally compilation errors in the loaded module, to be\nrecorded in %INC as if they were successful, so later attempts to load\nthe same module immediately indicate success.  This bug is present up\nto Perl 5.8.9, and is fixed in Perl 5.9.0.  The workaround means that a\ncompilation error in a module loaded via this module won't be cached as\na success.  Modules loaded in other ways remain liable to produce bogus\n%INC entries, and if a bogus entry exists then it will mislead this\nmodule if it is used to re-attempt loading.\n\nThe third bug worked around causes the wrong context to be seen at file\nscope of a loaded module, if \"require\" is invoked in a location that\ninherits context from a higher scope.  This bug is present up to Perl\n5.11.2, and is fixed in Perl 5.11.3.  The workaround means that a\nmodule loaded via this module will always see the correct context.\nModules loaded in other ways remain vulnerable.\n",
            "subsections": []
        },
        "REGULAR EXPRESSIONS": {
            "content": "These regular expressions do not include any anchors, so to check\nwhether an entire string matches a syntax item you must supply the\nanchors yourself.\n\n$modulenamerx\nMatches a valid Perl module name in bareword syntax.\n\n$topmodulespecrx\nMatches a module specification for use with \"composemodulename\",\nwhere no prefix is being used.\n\n$submodulespecrx\nMatches a module specification for use with \"composemodulename\",\nwhere a prefix is being used.\n",
            "subsections": []
        },
        "FUNCTIONS": {
            "content": "Basic module handling\nismodulename(ARG)\nReturns a truth value indicating whether ARG is a plain string\nsatisfying Perl module name syntax as described for\n\"$modulenamerx\".\n\nisvalidmodulename(ARG)\nDeprecated alias for \"ismodulename\".\n\ncheckmodulename(ARG)\nCheck whether ARG is a plain string satisfying Perl module name\nsyntax as described for \"$modulenamerx\".  Return normally if it\nis, or \"die\" if it is not.\n\nmodulenotionalfilename(NAME)\nGenerates a notional relative filename for a module, which is used\nin some Perl core interfaces.  The NAME is a string, which should\nbe a valid module name (one or more \"::\"-separated segments).  If\nit is not a valid name, the function \"die\"s.\n\nThe notional filename for the named module is generated and\nreturned.  This filename is always in Unix style, with \"/\"\ndirectory separators and a \".pm\" suffix.  This kind of filename can\nbe used as an argument to \"require\", and is the key that appears in\n%INC to identify a module, regardless of actual local filename\nsyntax.\n\nrequiremodule(NAME)\nThis is essentially the bareword form of \"require\", in runtime\nform.  The NAME is a string, which should be a valid module name\n(one or more \"::\"-separated segments).  If it is not a valid name,\nthe function \"die\"s.\n\nThe module specified by NAME is loaded, if it hasn't been already,\nin the manner of the bareword form of \"require\".  That means that a\nsearch through @INC is performed, and a byte-compiled form of the\nmodule will be used if available.\n\nThe return value is as for \"require\".  That is, it is the value\nreturned by the module itself if the module is loaded anew, or 1 if\nthe module was already loaded.\n\nStructured module use\nusemodule(NAME[, VERSION])\nThis is essentially \"use\" in runtime form, but without the\nimporting feature (which is fundamentally a compile-time thing).\nThe NAME is handled just like in \"requiremodule\" above: it must be\na module name, and the named module is loaded as if by the bareword\nform of \"require\".\n\nIf a VERSION is specified, the \"VERSION\" method of the loaded\nmodule is called with the specified VERSION as an argument.  This\nnormally serves to ensure that the version loaded is at least the\nversion required.  This is the same functionality provided by the\nVERSION parameter of \"use\".\n\nOn success, the name of the module is returned.  This is unlike\n\"requiremodule\", and is done so that the entire call to\n\"usemodule\" can be used as a class name to call a constructor, as\nin the example in the synopsis.\n\nusepackageoptimistically(NAME[, VERSION])\nThis is an analogue of \"usemodule\" for the situation where there\nis uncertainty as to whether a package/class is defined in its own\nmodule or by some other means.  It attempts to arrange for the\nnamed package to be available, either by loading a module or by\ndoing nothing and hoping.\n\nAn attempt is made to load the named module (as if by the bareword\nform of \"require\").  If the module cannot be found then it is\nassumed that the package was actually already loaded by other\nmeans, and no error is signalled.  That's the optimistic bit.\n\nWarning: this optional module loading is liable to cause unreliable\nbehaviour, including security problems.  It interacts especially\nbadly with having \".\" in @INC, which was the default state of\naffairs in Perls prior to 5.25.11.  If a package is actually\ndefined by some means other than a module, then applying this\nfunction to it causes a spurious attempt to load a module that is\nexpected to be non-existent.  If a module actually exists under\nthat name then it will be unintentionally loaded.  If \".\" is in\n@INC and this code is ever run with the current directory being one\nwritable by a malicious user (such as /tmp), then the malicious\nuser can easily cause the victim to run arbitrary code, by creating\na module file under the predictable spuriously-loaded name in the\nwritable directory.  Generally, optional module loading should be\navoided.\n\nThis is mostly the same operation that is performed by the base\npragma to ensure that the specified base classes are available.\nThe behaviour of base was simplified in version 2.18, and later\nimproved in version 2.20, and on both occasions this function\nchanged to match.\n\nIf a VERSION is specified, the \"VERSION\" method of the loaded\npackage is called with the specified VERSION as an argument.  This\nnormally serves to ensure that the version loaded is at least the\nversion required.  On success, the name of the package is returned.\nThese aspects of the function work just like \"usemodule\".\n\nModule name composition\nismodulespec(PREFIX, SPEC)\nReturns a truth value indicating whether SPEC is valid input for\n\"composemodulename\".  See below for what that entails.  Whether a\nPREFIX is supplied affects the validity of SPEC, but the exact\nvalue of the prefix is unimportant, so this function treats PREFIX\nas a truth value.\n\nisvalidmodulespec(PREFIX, SPEC)\nDeprecated alias for \"ismodulespec\".\n\ncheckmodulespec(PREFIX, SPEC)\nCheck whether SPEC is valid input for \"composemodulename\".\nReturn normally if it is, or \"die\" if it is not.\n\ncomposemodulename(PREFIX, SPEC)\nThis function is intended to make it more convenient for a user to\nspecify a Perl module name at runtime.  Users have greater need for\nabbreviations and context-sensitivity than programmers, and Perl\nmodule names get a little unwieldy.  SPEC is what the user\nspecifies, and this function translates it into a module name in\nstandard form, which it returns.\n\nSPEC has syntax approximately that of a standard module name: it\nshould consist of one or more name segments, each of which consists\nof one or more identifier characters.  However, \"/\" is permitted as\na separator, in addition to the standard \"::\".  The two separators\nare entirely interchangeable.\n\nAdditionally, if PREFIX is not \"undef\" then it must be a module\nname in standard form, and it is prefixed to the user-specified\nname.  The user can inhibit the prefix addition by starting SPEC\nwith a separator (either \"/\" or \"::\").\n",
            "subsections": []
        },
        "BUGS": {
            "content": "On Perl versions 5.7.2 to 5.8.8, if \"require\" is overridden by the\n\"CORE::GLOBAL\" mechanism, it is likely to break the heuristics used by\n\"usepackageoptimistically\", making it signal an error for a missing\nmodule rather than assume that it was already loaded.  From Perl 5.8.9\nonwards, and on 5.7.1 and earlier, this module can avoid being confused\nby such an override.  On the affected versions, a \"require\" override\nmight be installed by Lexical::SealRequireHints, if something requires\nits bugfix but for some reason its XS implementation isn't available.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "Lexical::SealRequireHints, base, \"require\" in perlfunc, \"use\" in\nperlfunc\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Andrew Main (Zefram) <zefram@fysh.org>\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011, 2012, 2014, 2017\nAndrew Main (Zefram) <zefram@fysh.org>\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "This module is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.\n\nperl v5.26.1                      2018-01-02              Module::Runtime(3pm)",
            "subsections": []
        }
    },
    "summary": "Module::Runtime - runtime module handling",
    "flags": [],
    "examples": [],
    "see_also": []
}