1Module::Runtime(3) User Contributed Perl Documentation Module::Runtime(3)
2
6 Module::Runtime - runtime module handling
7
9 use Module::Runtime qw(
10 $module_name_rx is_module_name check_module_name
11 require_module
12 );
13 if($module_name =~ /\A$module_name_rx\z/o) { ...
15 if(is_module_name($module_name)) { ...
16 check_module_name($module_name);
17 require_module($module_name);
19 use Module::Runtime qw(use_module use_package_optimistically);
21 $bi = use_module("Math::BigInt", 1.31)->new("1_234");
23 $widget = use_package_optimistically("Local::Widget")->new;
24 use Module::Runtime qw(
26 $top_module_spec_rx $sub_module_spec_rx
27 is_module_spec check_module_spec
28 compose_module_name
29 );
30 if($spec =~ /\A$top_module_spec_rx\z/o) { ...
32 if($spec =~ /\A$sub_module_spec_rx\z/o) { ...
33 if(is_module_spec("Standard::Prefix", $spec)) { ...
34 check_module_spec("Standard::Prefix", $spec);
35 $module_name =
37 compose_module_name("Standard::Prefix", $spec);
38
40 The functions exported by this module deal with runtime handling of
41 Perl modules, which are normally handled at compile time.
42
44 These regular expressions do not include any anchors, so to check
45 whether an entire string matches a syntax item you must supply the
46 anchors yourself.
47 $module_name_rx
49 Matches a valid Perl module name in bareword syntax. The rule for
50 this, precisely, is: the string must consist of one or more
51 segments separated by "::"; each segment must consist of one or
52 more identifier characters (alphanumerics plus "_"); the first
53 character of the string must not be a digit. Thus ""IO::File"",
54 ""warnings"", and ""foo::123::x_0"" are all valid module names,
55 whereas ""IO::"" and ""1foo::bar"" are not. Only ASCII characters
56 are permitted; Perl's handling of non-ASCII characters in source
57 code is inconsistent. "'" separators are not permitted.
58 $top_module_spec_rx
60 Matches a module specification for use with "compose_module_name",
61 where no prefix is being used.
62 $sub_module_spec_rx
64 Matches a module specification for use with "compose_module_name",
65 where a prefix is being used.
66
68 Basic module handling
69 is_module_name(ARG)
70 Returns a truth value indicating whether ARG is a plain string
71 satisfying Perl module name syntax as described for
72 "$module_name_rx".
73 is_valid_module_name(ARG)
75 Deprecated alias for "is_module_name".
76 check_module_name(ARG)
78 Check whether ARG is a plain string satisfying Perl module name
79 syntax as described for "$module_name_rx". Return normally if it
80 is, or "die" if it is not.
81 require_module(NAME)
83 This is essentially the bareword form of "require", in runtime
84 form. The NAME is a string, which should be a valid module name
85 (one or more "::"-separated segments). If it is not a valid name,
86 the function "die"s.
87 The module specified by NAME is loaded, if it hasn't been already,
89 in the manner of the bareword form of "require". That means that a
90 search through @INC is performed, and a byte-compiled form of the
91 module will be used if available.
92 The return value is as for "require". That is, it is the value
94 returned by the module itself if the module is loaded anew, or 1 if
95 the module was already loaded.
96 Structured module use
98 use_module(NAME[, VERSION])
99 This is essentially "use" in runtime form, but without the
100 importing feature (which is fundamentally a compile-time thing).
101 The NAME is handled just like in "require_module" above: it must be
102 a module name, and the named module is loaded as if by the bareword
103 form of "require".
104 If a VERSION is specified, the "VERSION" method of the loaded
106 module is called with the specified VERSION as an argument. This
107 normally serves to ensure that the version loaded is at least the
108 version required. This is the same functionality provided by the
109 VERSION parameter of "use".
110 On success, the name of the module is returned. This is unlike
112 "require_module", and is done so that the entire call to
113 "use_module" can be used as a class name to call a constructor, as
114 in the example in the synopsis.
115 use_package_optimistically(NAME[, VERSION])
117 This is an analogue of "use_module" for the situation where there
118 is uncertainty as to whether a package/class is defined in its own
119 module or by some other means. It attempts to arrange for the
120 named package to be available, either by loading a module or by
121 doing nothing and hoping.
122 If the package does not appear to already be loaded then an attempt
124 is made to load the module of the same name (as if by the bareword
125 form of "require"). If the module cannot be found then it is
126 assumed that the package was actually already loaded but wasn't
127 detected correctly, and no error is signalled. That's the
128 optimistic bit.
129 For the purposes of this function, package existence is checked by
131 whether a $VERSION variable exists in the package. If the module
132 wasn't found, or if it was loaded but didn't create a $VERSION
133 variable, then such a variable is automatically created (with value
134 "undef") so that repeated use of this function won't redundantly
135 attempt to load the module.
136 This is mostly the same operation that is performed by the base
138 pragma to ensure that the specified base classes are available.
139 The difference is that base does not allow the $VERSION variable to
140 remain undefined: it will set it to ""-1, set by base.pm"" if it
141 does not otherwise have a non-null value.
142 If a VERSION is specified, the "VERSION" method of the loaded
144 package is called with the specified VERSION as an argument. This
145 normally serves to ensure that the version loaded is at least the
146 version required. On success, the name of the package is returned.
147 These aspects of the function work just like "use_module".
148 Module name composition
150 is_module_spec(PREFIX, SPEC)
151 Returns a truth value indicating whether SPEC is valid input for
152 "compose_module_name". See below for what that entails. Whether a
153 PREFIX is supplied affects the validity of SPEC, but the exact
154 value of the prefix is unimportant, so this function treats PREFIX
155 as a truth value.
156 is_valid_module_spec(PREFIX, SPEC)
158 Deprecated alias for "is_module_spec".
159 check_module_spec(PREFIX, SPEC)
161 Check whether SPEC is valid input for "compose_module_name".
162 Return normally if it is, or "die" if it is not.
163 compose_module_name(PREFIX, SPEC)
165 This function is intended to make it more convenient for a user to
166 specify a Perl module name at runtime. Users have greater need for
167 abbreviations and context-sensitivity than programmers, and Perl
168 module names get a little unwieldy. SPEC is what the user
169 specifies, and this function translates it into a module name in
170 standard form, which it returns.
171 SPEC has syntax approximately that of a standard module name: it
173 should consist of one or more name segments, each of which consists
174 of one or more identifier characters. However, "/" is permitted as
175 a separator, in addition to the standard "::". The two separators
176 are entirely interchangeable.
177 Additionally, if PREFIX is not "undef" then it must be a module
179 name in standard form, and it is prefixed to the user-specified
180 name. The user can inhibit the prefix addition by starting SPEC
181 with a separator (either "/" or "::").
182
184 base, "require" in perlfunc, "use" in perlfunc
185
187 Andrew Main (Zefram) <zefram@fysh.org>
188
190 Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011 Andrew Main (Zefram)
191 <zefram@fysh.org>
192
194 This module is free software; you can redistribute it and/or modify it
195 under the same terms as Perl itself.
196perl v5.12.3 2011-07-20 Module::Runtime(3)