Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

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)