Filename | /2home/ss5/perl5/perlbrew/perls/perl-5.12.3/lib/site_perl/5.12.3/Module/Runtime.pm |
Statements | Executed 466 statements in 4.08ms |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
8 | 2 | 2 | 4.29ms | 101ms | require_module | Module::Runtime::
86 | 1 | 1 | 621µs | 1.46ms | is_module_name | Module::Runtime::
91 | 2 | 1 | 551µs | 551µs | CORE:match (opcode) | Module::Runtime::
86 | 2 | 2 | 387µs | 1.85ms | check_module_name | Module::Runtime::
86 | 1 | 1 | 279µs | 279µs | _is_string | Module::Runtime::
14 | 2 | 2 | 91µs | 300µs | module_notional_filename | Module::Runtime::
3 | 3 | 1 | 64µs | 64µs | CORE:regcomp (opcode) | Module::Runtime::
2 | 2 | 2 | 41µs | 44µs | import | Module::Runtime::
14 | 1 | 1 | 38µs | 38µs | CORE:subst (opcode) | Module::Runtime::
1 | 1 | 1 | 25µs | 25µs | BEGIN@116 | Module::Runtime::
1 | 1 | 1 | 9µs | 9µs | BEGIN@289 | Module::Runtime::
6 | 6 | 1 | 7µs | 7µs | CORE:qr (opcode) | Module::Runtime::
1 | 1 | 1 | 3µs | 3µs | BEGIN@120 | Module::Runtime::
1 | 1 | 1 | 3µs | 3µs | BEGIN@296 | Module::Runtime::
0 | 0 | 0 | 0s | 0s | check_module_spec | Module::Runtime::
0 | 0 | 0 | 0s | 0s | compose_module_name | Module::Runtime::
0 | 0 | 0 | 0s | 0s | is_module_spec | Module::Runtime::
0 | 0 | 0 | 0s | 0s | use_module | Module::Runtime::
0 | 0 | 0 | 0s | 0s | use_package_optimistically | Module::Runtime::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | =head1 NAME | ||||
2 | |||||
3 | Module::Runtime - runtime module handling | ||||
4 | |||||
5 | =head1 SYNOPSIS | ||||
6 | |||||
7 | use Module::Runtime qw( | ||||
8 | $module_name_rx is_module_name check_module_name | ||||
9 | module_notional_filename require_module | ||||
10 | ); | ||||
11 | |||||
12 | if($module_name =~ /\A$module_name_rx\z/o) { ... | ||||
13 | if(is_module_name($module_name)) { ... | ||||
14 | check_module_name($module_name); | ||||
15 | |||||
16 | $notional_filename = module_notional_filename($module_name); | ||||
17 | require_module($module_name); | ||||
18 | |||||
19 | use Module::Runtime qw(use_module use_package_optimistically); | ||||
20 | |||||
21 | $bi = use_module("Math::BigInt", 1.31)->new("1_234"); | ||||
22 | $widget = use_package_optimistically("Local::Widget")->new; | ||||
23 | |||||
24 | use Module::Runtime qw( | ||||
25 | $top_module_spec_rx $sub_module_spec_rx | ||||
26 | is_module_spec check_module_spec | ||||
27 | compose_module_name | ||||
28 | ); | ||||
29 | |||||
30 | if($spec =~ /\A$top_module_spec_rx\z/o) { ... | ||||
31 | if($spec =~ /\A$sub_module_spec_rx\z/o) { ... | ||||
32 | if(is_module_spec("Standard::Prefix", $spec)) { ... | ||||
33 | check_module_spec("Standard::Prefix", $spec); | ||||
34 | |||||
35 | $module_name = | ||||
36 | compose_module_name("Standard::Prefix", $spec); | ||||
37 | |||||
38 | =head1 DESCRIPTION | ||||
39 | |||||
40 | The functions exported by this module deal with runtime handling of | ||||
41 | Perl modules, which are normally handled at compile time. This module | ||||
42 | avoids using any other modules, so that it can be used in low-level | ||||
43 | infrastructure. | ||||
44 | |||||
45 | The parts of this module that work with module names apply the same | ||||
46 | syntax that is used for barewords in Perl source. In principle this | ||||
47 | syntax can vary between versions of Perl, and this module applies the | ||||
48 | syntax of the Perl on which it is running. In practice the usable syntax | ||||
49 | hasn't changed yet, but there's a good chance of it changing in Perl 5.18. | ||||
50 | |||||
51 | The functions of this module whose purpose is to load modules include | ||||
52 | workarounds for three old Perl core bugs regarding C<require>. These | ||||
53 | workarounds are applied on any Perl version where the bugs exist, except | ||||
54 | for a case where one of the bugs cannot be adequately worked around in | ||||
55 | pure Perl. | ||||
56 | |||||
57 | =head2 Module name syntax | ||||
58 | |||||
59 | The usable module name syntax has not changed from Perl 5.000 up to | ||||
60 | Perl 5.15.7. The syntax is composed entirely of ASCII characters. | ||||
61 | From Perl 5.6 onwards there has been some attempt to allow the use of | ||||
62 | non-ASCII Unicode characters in Perl source, but it was fundamentally | ||||
63 | broken (like the entirety of Perl 5.6's Unicode handling) and remained | ||||
64 | pretty much entirely unusable until it got some attention in the Perl | ||||
65 | 5.15 series. Although Unicode is now consistently accepted by the | ||||
66 | parser in some places, it remains broken for module names. Furthermore, | ||||
67 | there has not yet been any work on how to map Unicode module names into | ||||
68 | filenames, so in that respect also Unicode module names are unusable. | ||||
69 | This may finally be addressed in the Perl 5.17 series. | ||||
70 | |||||
71 | The module name syntax is, precisely: the string must consist of one or | ||||
72 | more segments separated by C<::>; each segment must consist of one or more | ||||
73 | identifier characters (ASCII alphanumerics plus "_"); the first character | ||||
74 | of the string must not be a digit. Thus "C<IO::File>", "C<warnings>", | ||||
75 | and "C<foo::123::x_0>" are all valid module names, whereas "C<IO::>" | ||||
76 | and "C<1foo::bar>" are not. C<'> separators are not permitted by this | ||||
77 | module, though they remain usable in Perl source, being translated to | ||||
78 | C<::> in the parser. | ||||
79 | |||||
80 | =head2 Core bugs worked around | ||||
81 | |||||
82 | The first bug worked around is core bug [perl #68590], which causes | ||||
83 | lexical state in one file to leak into another that is C<require>d/C<use>d | ||||
84 | from it. This bug is present from Perl 5.6 up to Perl 5.10, and is | ||||
85 | fixed in Perl 5.11.0. From Perl 5.9.4 up to Perl 5.10.0 no satisfactory | ||||
86 | workaround is possible in pure Perl. The workaround means that modules | ||||
87 | loaded via this module don't suffer this pollution of their lexical | ||||
88 | state. Modules loaded in other ways, or via this module on the Perl | ||||
89 | versions where the pure Perl workaround is impossible, remain vulnerable. | ||||
90 | The module L<Lexical::SealRequireHints> provides a complete workaround | ||||
91 | for this bug. | ||||
92 | |||||
93 | The second bug worked around causes some kinds of failure in module | ||||
94 | loading, principally compilation errors in the loaded module, to be | ||||
95 | recorded in C<%INC> as if they were successful, so later attempts to load | ||||
96 | the same module immediately indicate success. This bug is present up | ||||
97 | to Perl 5.8.9, and is fixed in Perl 5.9.0. The workaround means that a | ||||
98 | compilation error in a module loaded via this module won't be cached as | ||||
99 | a success. Modules loaded in other ways remain liable to produce bogus | ||||
100 | C<%INC> entries, and if a bogus entry exists then it will mislead this | ||||
101 | module if it is used to re-attempt loading. | ||||
102 | |||||
103 | The third bug worked around causes the wrong context to be seen at | ||||
104 | file scope of a loaded module, if C<require> is invoked in a location | ||||
105 | that inherits context from a higher scope. This bug is present up to | ||||
106 | Perl 5.11.2, and is fixed in Perl 5.11.3. The workaround means that | ||||
107 | a module loaded via this module will always see the correct context. | ||||
108 | Modules loaded in other ways remain vulnerable. | ||||
109 | |||||
110 | =cut | ||||
111 | |||||
112 | package Module::Runtime; | ||||
113 | |||||
114 | # Don't "use 5.006" here, because Perl 5.15.6 will load feature.pm if | ||||
115 | # the version check is done that way. | ||||
116 | 1 | 35µs | 1 | 25µs | # spent 25µs within Module::Runtime::BEGIN@116 which was called:
# once (25µs+0s) by Module::Implementation::BEGIN@9 at line 116 # spent 25µs making 1 call to Module::Runtime::BEGIN@116 |
117 | # Don't "use warnings" here, to avoid dependencies. Do standardise the | ||||
118 | # warning status by lexical override; unfortunately the only safe bitset | ||||
119 | # to build in is the empty set, equivalent to "no warnings". | ||||
120 | 1 | 593µs | 1 | 3µs | # spent 3µs within Module::Runtime::BEGIN@120 which was called:
# once (3µs+0s) by Module::Implementation::BEGIN@9 at line 120 # spent 3µs making 1 call to Module::Runtime::BEGIN@120 |
121 | # Don't "use strict" here, to avoid dependencies. | ||||
122 | |||||
123 | 1 | 500ns | our $VERSION = "0.013"; | ||
124 | |||||
125 | # Don't use Exporter here, to avoid dependencies. | ||||
126 | 1 | 3µs | our @EXPORT_OK = qw( | ||
127 | $module_name_rx is_module_name is_valid_module_name check_module_name | ||||
128 | module_notional_filename require_module | ||||
129 | use_module use_package_optimistically | ||||
130 | $top_module_spec_rx $sub_module_spec_rx | ||||
131 | is_module_spec is_valid_module_spec check_module_spec | ||||
132 | compose_module_name | ||||
133 | ); | ||||
134 | 1 | 20µs | my %export_ok = map { ($_ => undef) } @EXPORT_OK; | ||
135 | # spent 44µs (41+4) within Module::Runtime::import which was called 2 times, avg 22µs/call:
# once (27µs+2µs) by Class::Load::BEGIN@10 at line 10 of Class/Load.pm
# once (13µs+2µs) by Module::Implementation::BEGIN@9 at line 9 of Module/Implementation.pm | ||||
136 | 10 | 11µs | my $me = shift; | ||
137 | my $callpkg = caller(0); | ||||
138 | my $errs = ""; | ||||
139 | foreach(@_) { | ||||
140 | 10 | 20µs | if(exists $export_ok{$_}) { | ||
141 | # We would need to do "no strict 'refs'" here | ||||
142 | # if we had enabled strict at file scope. | ||||
143 | 5 | 16µs | 5 | 4µs | if(/\A\$(.*)\z/s) { # spent 4µs making 5 calls to Module::Runtime::CORE:match, avg 720ns/call |
144 | *{$callpkg."::".$1} = \$$1; | ||||
145 | } else { | ||||
146 | *{$callpkg."::".$_} = \&$_; | ||||
147 | } | ||||
148 | } else { | ||||
149 | $errs .= "\"$_\" is not exported by the $me module\n"; | ||||
150 | } | ||||
151 | } | ||||
152 | if($errs ne "") { | ||||
153 | die "${errs}Can't continue after import errors ". | ||||
154 | "at @{[(caller(0))[1]]} line @{[(caller(0))[2]]}.\n"; | ||||
155 | } | ||||
156 | } | ||||
157 | |||||
158 | # Logic duplicated from Params::Classify. Duplicating it here avoids | ||||
159 | # an extensive and potentially circular dependency graph. | ||||
160 | # spent 279µs within Module::Runtime::_is_string which was called 86 times, avg 3µs/call:
# 86 times (279µs+0s) by Module::Runtime::is_module_name at line 222, avg 3µs/call | ||||
161 | 172 | 389µs | my($arg) = @_; | ||
162 | return defined($arg) && ref(\$arg) eq "SCALAR"; | ||||
163 | } | ||||
164 | |||||
165 | =head1 REGULAR EXPRESSIONS | ||||
166 | |||||
167 | These regular expressions do not include any anchors, so to check | ||||
168 | whether an entire string matches a syntax item you must supply the | ||||
169 | anchors yourself. | ||||
170 | |||||
171 | =over | ||||
172 | |||||
173 | =item $module_name_rx | ||||
174 | |||||
175 | Matches a valid Perl module name in bareword syntax. | ||||
176 | |||||
177 | =cut | ||||
178 | |||||
179 | 1 | 8µs | 1 | 3µs | our $module_name_rx = qr/[A-Z_a-z][0-9A-Z_a-z]*(?:::[0-9A-Z_a-z]+)*/; # spent 3µs making 1 call to Module::Runtime::CORE:qr |
180 | |||||
181 | =item $top_module_spec_rx | ||||
182 | |||||
183 | Matches a module specification for use with L</compose_module_name>, | ||||
184 | where no prefix is being used. | ||||
185 | |||||
186 | =cut | ||||
187 | |||||
188 | 1 | 3µs | 1 | 900ns | my $qual_module_spec_rx = # spent 900ns making 1 call to Module::Runtime::CORE:qr |
189 | qr#(?:/|::)[A-Z_a-z][0-9A-Z_a-z]*(?:(?:/|::)[0-9A-Z_a-z]+)*#; | ||||
190 | |||||
191 | 1 | 3µs | 1 | 800ns | my $unqual_top_module_spec_rx = # spent 800ns making 1 call to Module::Runtime::CORE:qr |
192 | qr#[A-Z_a-z][0-9A-Z_a-z]*(?:(?:/|::)[0-9A-Z_a-z]+)*#; | ||||
193 | |||||
194 | 1 | 32µs | 2 | 26µs | our $top_module_spec_rx = qr/$qual_module_spec_rx|$unqual_top_module_spec_rx/o; # spent 25µs making 1 call to Module::Runtime::CORE:regcomp
# spent 900ns making 1 call to Module::Runtime::CORE:qr |
195 | |||||
196 | =item $sub_module_spec_rx | ||||
197 | |||||
198 | Matches a module specification for use with L</compose_module_name>, | ||||
199 | where a prefix is being used. | ||||
200 | |||||
201 | =cut | ||||
202 | |||||
203 | 1 | 3µs | 1 | 800ns | my $unqual_sub_module_spec_rx = qr#[0-9A-Z_a-z]+(?:(?:/|::)[0-9A-Z_a-z]+)*#; # spent 800ns making 1 call to Module::Runtime::CORE:qr |
204 | |||||
205 | 1 | 26µs | 2 | 22µs | our $sub_module_spec_rx = qr/$qual_module_spec_rx|$unqual_sub_module_spec_rx/o; # spent 21µs making 1 call to Module::Runtime::CORE:regcomp
# spent 900ns making 1 call to Module::Runtime::CORE:qr |
206 | |||||
207 | =back | ||||
208 | |||||
209 | =head1 FUNCTIONS | ||||
210 | |||||
211 | =head2 Basic module handling | ||||
212 | |||||
213 | =over | ||||
214 | |||||
215 | =item is_module_name(ARG) | ||||
216 | |||||
217 | Returns a truth value indicating whether I<ARG> is a plain string | ||||
218 | satisfying Perl module name syntax as described for L</$module_name_rx>. | ||||
219 | |||||
220 | =cut | ||||
221 | |||||
222 | 86 | 1.16ms | 173 | 844µs | # spent 1.46ms (621µs+844µs) within Module::Runtime::is_module_name which was called 86 times, avg 17µs/call:
# 86 times (621µs+844µs) by Module::Runtime::check_module_name at line 241, avg 17µs/call # spent 548µs making 86 calls to Module::Runtime::CORE:match, avg 6µs/call
# spent 279µs making 86 calls to Module::Runtime::_is_string, avg 3µs/call
# spent 17µs making 1 call to Module::Runtime::CORE:regcomp |
223 | |||||
224 | =item is_valid_module_name(ARG) | ||||
225 | |||||
226 | Deprecated alias for L</is_module_name>. | ||||
227 | |||||
228 | =cut | ||||
229 | |||||
230 | 1 | 1µs | *is_valid_module_name = \&is_module_name; | ||
231 | |||||
232 | =item check_module_name(ARG) | ||||
233 | |||||
234 | Check whether I<ARG> is a plain string | ||||
235 | satisfying Perl module name syntax as described for L</$module_name_rx>. | ||||
236 | Return normally if it is, or C<die> if it is not. | ||||
237 | |||||
238 | =cut | ||||
239 | |||||
240 | # spent 1.85ms (387µs+1.46) within Module::Runtime::check_module_name which was called 86 times, avg 22µs/call:
# 72 times (355µs+1.33ms) by Class::Load::try_load_class at line 139 of Class/Load.pm, avg 23µs/call
# 14 times (32µs+139µs) by Module::Runtime::module_notional_filename at line 264, avg 12µs/call | ||||
241 | 86 | 312µs | 86 | 1.46ms | unless(&is_module_name) { # spent 1.46ms making 86 calls to Module::Runtime::is_module_name, avg 17µs/call |
242 | die +(_is_string($_[0]) ? "`$_[0]'" : "argument"). | ||||
243 | " is not a module name\n"; | ||||
244 | } | ||||
245 | } | ||||
246 | |||||
247 | =item module_notional_filename(NAME) | ||||
248 | |||||
249 | Generates a notional relative filename for a module, which is used in | ||||
250 | some Perl core interfaces. | ||||
251 | The I<NAME> is a string, which should be a valid module name (one or | ||||
252 | more C<::>-separated segments). If it is not a valid name, the function | ||||
253 | C<die>s. | ||||
254 | |||||
255 | The notional filename for the named module is generated and returned. | ||||
256 | This filename is always in Unix style, with C</> directory separators | ||||
257 | and a C<.pm> suffix. This kind of filename can be used as an argument to | ||||
258 | C<require>, and is the key that appears in C<%INC> to identify a module, | ||||
259 | regardless of actual local filename syntax. | ||||
260 | |||||
261 | =cut | ||||
262 | |||||
263 | # spent 300µs (91+209) within Module::Runtime::module_notional_filename which was called 14 times, avg 21µs/call:
# 8 times (45µs+132µs) by Module::Runtime::require_module at line 317, avg 22µs/call
# 6 times (45µs+78µs) by Class::Load::try_load_class at line 158 of Class/Load.pm, avg 20µs/call | ||||
264 | 56 | 128µs | 14 | 171µs | &check_module_name; # spent 171µs making 14 calls to Module::Runtime::check_module_name, avg 12µs/call |
265 | my($name) = @_; | ||||
266 | 14 | 38µs | $name =~ s!::!/!g; # spent 38µs making 14 calls to Module::Runtime::CORE:subst, avg 3µs/call | ||
267 | return $name.".pm"; | ||||
268 | } | ||||
269 | |||||
270 | =item require_module(NAME) | ||||
271 | |||||
272 | This is essentially the bareword form of C<require>, in runtime form. | ||||
273 | The I<NAME> is a string, which should be a valid module name (one or | ||||
274 | more C<::>-separated segments). If it is not a valid name, the function | ||||
275 | C<die>s. | ||||
276 | |||||
277 | The module specified by I<NAME> is loaded, if it hasn't been already, | ||||
278 | in the manner of the bareword form of C<require>. That means that a | ||||
279 | search through C<@INC> is performed, and a byte-compiled form of the | ||||
280 | module will be used if available. | ||||
281 | |||||
282 | The return value is as for C<require>. That is, it is the value returned | ||||
283 | by the module itself if the module is loaded anew, or C<1> if the module | ||||
284 | was already loaded. | ||||
285 | |||||
286 | =cut | ||||
287 | |||||
288 | # Don't "use constant" here, to avoid dependencies. | ||||
289 | # spent 9µs within Module::Runtime::BEGIN@289 which was called:
# once (9µs+0s) by Module::Implementation::BEGIN@9 at line 294 | ||||
290 | *_WORK_AROUND_HINT_LEAKAGE = | ||||
291 | "$]" < 5.011 && !("$]" >= 5.009004 && "$]" < 5.010001) | ||||
292 | 2 | 13µs | ? sub(){1} : sub(){0}; | ||
293 | *_WORK_AROUND_BROKEN_MODULE_STATE = "$]" < 5.009 ? sub(){1} : sub(){0}; | ||||
294 | 1 | 34µs | 1 | 9µs | } # spent 9µs making 1 call to Module::Runtime::BEGIN@289 |
295 | |||||
296 | 1 | 3µs | # spent 3µs within Module::Runtime::BEGIN@296 which was called:
# once (3µs+0s) by Module::Implementation::BEGIN@9 at line 301 | ||
297 | sub Module::Runtime::__GUARD__::DESTROY { | ||||
298 | delete $INC{$_[0]->[0]} if @{$_[0]}; | ||||
299 | } | ||||
300 | 1; | ||||
301 | 1 | 355µs | 1 | 3µs | }; die $@ if $@ ne ""; } } # spent 3µs making 1 call to Module::Runtime::BEGIN@296 |
302 | |||||
303 | # spent 101ms (4.29+96.5) within Module::Runtime::require_module which was called 8 times, avg 12.6ms/call:
# 6 times (3.83ms+95.8ms) by Class::Load::__ANON__[/2home/ss5/perl5/perlbrew/perls/perl-5.12.3/lib/site_perl/5.12.3/Class/Load.pm:180] at line 177 of Class/Load.pm, avg 16.6ms/call
# 2 times (467µs+604µs) by Module::Implementation::__ANON__[/2home/ss5/perl5/perlbrew/perls/perl-5.12.3/lib/site_perl/5.12.3/Module/Implementation.pm:87] at line 85 of Module/Implementation.pm, avg 536µs/call | ||||
304 | # Localise %^H to work around [perl #68590], where the bug exists | ||||
305 | # and this is a satisfactory workaround. The bug consists of | ||||
306 | # %^H state leaking into each required module, polluting the | ||||
307 | # module's lexical state. | ||||
308 | 16 | 4µs | local %^H if _WORK_AROUND_HINT_LEAKAGE; | ||
309 | 8 | 894µs | if(_WORK_AROUND_BROKEN_MODULE_STATE) { | ||
310 | my $notional_filename = &module_notional_filename; | ||||
311 | my $guard = bless([ $notional_filename ], | ||||
312 | "Module::Runtime::__GUARD__"); | ||||
313 | my $result = require($notional_filename); | ||||
314 | pop @$guard; | ||||
315 | return $result; | ||||
316 | } else { | ||||
317 | 8 | 177µs | return scalar(require(&module_notional_filename)); # spent 177µs making 8 calls to Module::Runtime::module_notional_filename, avg 22µs/call | ||
318 | } | ||||
319 | } | ||||
320 | |||||
321 | =back | ||||
322 | |||||
323 | =head2 Structured module use | ||||
324 | |||||
325 | =over | ||||
326 | |||||
327 | =item use_module(NAME[, VERSION]) | ||||
328 | |||||
329 | This is essentially C<use> in runtime form, but without the importing | ||||
330 | feature (which is fundamentally a compile-time thing). The I<NAME> is | ||||
331 | handled just like in C<require_module> above: it must be a module name, | ||||
332 | and the named module is loaded as if by the bareword form of C<require>. | ||||
333 | |||||
334 | If a I<VERSION> is specified, the C<VERSION> method of the loaded module is | ||||
335 | called with the specified I<VERSION> as an argument. This normally serves to | ||||
336 | ensure that the version loaded is at least the version required. This is | ||||
337 | the same functionality provided by the I<VERSION> parameter of C<use>. | ||||
338 | |||||
339 | On success, the name of the module is returned. This is unlike | ||||
340 | L</require_module>, and is done so that the entire call to L</use_module> | ||||
341 | can be used as a class name to call a constructor, as in the example in | ||||
342 | the synopsis. | ||||
343 | |||||
344 | =cut | ||||
345 | |||||
346 | sub use_module($;$) { | ||||
347 | my($name, $version) = @_; | ||||
348 | require_module($name); | ||||
349 | if(defined $version) { | ||||
350 | $name->VERSION($version); | ||||
351 | } | ||||
352 | return $name; | ||||
353 | } | ||||
354 | |||||
355 | =item use_package_optimistically(NAME[, VERSION]) | ||||
356 | |||||
357 | This is an analogue of L</use_module> for the situation where there is | ||||
358 | uncertainty as to whether a package/class is defined in its own module | ||||
359 | or by some other means. It attempts to arrange for the named package to | ||||
360 | be available, either by loading a module or by doing nothing and hoping. | ||||
361 | |||||
362 | An attempt is made to load the named module (as if by the bareword form | ||||
363 | of C<require>). If the module cannot be found then it is assumed that | ||||
364 | the package was actually already loaded by other means, and no error | ||||
365 | is signalled. That's the optimistic bit. | ||||
366 | |||||
367 | This is mostly the same operation that is performed by the L<base> pragma | ||||
368 | to ensure that the specified base classes are available. The behaviour | ||||
369 | of L<base> was simplified in version 2.18, and this function changed | ||||
370 | to match. | ||||
371 | |||||
372 | If a I<VERSION> is specified, the C<VERSION> method of the loaded package is | ||||
373 | called with the specified I<VERSION> as an argument. This normally serves | ||||
374 | to ensure that the version loaded is at least the version required. | ||||
375 | On success, the name of the package is returned. These aspects of the | ||||
376 | function work just like L</use_module>. | ||||
377 | |||||
378 | =cut | ||||
379 | |||||
380 | sub use_package_optimistically($;$) { | ||||
381 | my($name, $version) = @_; | ||||
382 | check_module_name($name); | ||||
383 | eval { local $SIG{__DIE__}; require_module($name); }; | ||||
384 | die $@ if $@ ne "" && | ||||
385 | $@ !~ /\ACan't locate .+ at \Q@{[__FILE__]}\E line/s; | ||||
386 | $name->VERSION($version) if defined $version; | ||||
387 | return $name; | ||||
388 | } | ||||
389 | |||||
390 | =back | ||||
391 | |||||
392 | =head2 Module name composition | ||||
393 | |||||
394 | =over | ||||
395 | |||||
396 | =item is_module_spec(PREFIX, SPEC) | ||||
397 | |||||
398 | Returns a truth value indicating | ||||
399 | whether I<SPEC> is valid input for L</compose_module_name>. | ||||
400 | See below for what that entails. Whether a I<PREFIX> is supplied affects | ||||
401 | the validity of I<SPEC>, but the exact value of the prefix is unimportant, | ||||
402 | so this function treats I<PREFIX> as a truth value. | ||||
403 | |||||
404 | =cut | ||||
405 | |||||
406 | sub is_module_spec($$) { | ||||
407 | my($prefix, $spec) = @_; | ||||
408 | return _is_string($spec) && | ||||
409 | $spec =~ ($prefix ? qr/\A$sub_module_spec_rx\z/o : | ||||
410 | qr/\A$top_module_spec_rx\z/o); | ||||
411 | } | ||||
412 | |||||
413 | =item is_valid_module_spec(PREFIX, SPEC) | ||||
414 | |||||
415 | Deprecated alias for L</is_module_spec>. | ||||
416 | |||||
417 | =cut | ||||
418 | |||||
419 | 1 | 500ns | *is_valid_module_spec = \&is_module_spec; | ||
420 | |||||
421 | =item check_module_spec(PREFIX, SPEC) | ||||
422 | |||||
423 | Check whether I<SPEC> is valid input for L</compose_module_name>. | ||||
424 | Return normally if it is, or C<die> if it is not. | ||||
425 | |||||
426 | =cut | ||||
427 | |||||
428 | sub check_module_spec($$) { | ||||
429 | unless(&is_module_spec) { | ||||
430 | die +(_is_string($_[1]) ? "`$_[1]'" : "argument"). | ||||
431 | " is not a module specification\n"; | ||||
432 | } | ||||
433 | } | ||||
434 | |||||
435 | =item compose_module_name(PREFIX, SPEC) | ||||
436 | |||||
437 | This function is intended to make it more convenient for a user to specify | ||||
438 | a Perl module name at runtime. Users have greater need for abbreviations | ||||
439 | and context-sensitivity than programmers, and Perl module names get a | ||||
440 | little unwieldy. I<SPEC> is what the user specifies, and this function | ||||
441 | translates it into a module name in standard form, which it returns. | ||||
442 | |||||
443 | I<SPEC> has syntax approximately that of a standard module name: it | ||||
444 | should consist of one or more name segments, each of which consists | ||||
445 | of one or more identifier characters. However, C</> is permitted as a | ||||
446 | separator, in addition to the standard C<::>. The two separators are | ||||
447 | entirely interchangeable. | ||||
448 | |||||
449 | Additionally, if I<PREFIX> is not C<undef> then it must be a module | ||||
450 | name in standard form, and it is prefixed to the user-specified name. | ||||
451 | The user can inhibit the prefix addition by starting I<SPEC> with a | ||||
452 | separator (either C</> or C<::>). | ||||
453 | |||||
454 | =cut | ||||
455 | |||||
456 | sub compose_module_name($$) { | ||||
457 | my($prefix, $spec) = @_; | ||||
458 | check_module_name($prefix) if defined $prefix; | ||||
459 | &check_module_spec; | ||||
460 | if($spec =~ s#\A(?:/|::)##) { | ||||
461 | # OK | ||||
462 | } else { | ||||
463 | $spec = $prefix."::".$spec if defined $prefix; | ||||
464 | } | ||||
465 | $spec =~ s#/#::#g; | ||||
466 | return $spec; | ||||
467 | } | ||||
468 | |||||
469 | =back | ||||
470 | |||||
471 | =head1 SEE ALSO | ||||
472 | |||||
473 | L<Lexical::SealRequireHints>, | ||||
474 | L<base>, | ||||
475 | L<perlfunc/require>, | ||||
476 | L<perlfunc/use> | ||||
477 | |||||
478 | =head1 AUTHOR | ||||
479 | |||||
480 | Andrew Main (Zefram) <zefram@fysh.org> | ||||
481 | |||||
482 | =head1 COPYRIGHT | ||||
483 | |||||
484 | Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011, 2012 | ||||
485 | Andrew Main (Zefram) <zefram@fysh.org> | ||||
486 | |||||
487 | =head1 LICENSE | ||||
488 | |||||
489 | This module is free software; you can redistribute it and/or modify it | ||||
490 | under the same terms as Perl itself. | ||||
491 | |||||
492 | =cut | ||||
493 | |||||
494 | 1 | 14µs | 1; | ||
sub Module::Runtime::CORE:match; # opcode | |||||
# spent 7µs within Module::Runtime::CORE:qr which was called 6 times, avg 1µs/call:
# once (3µs+0s) by Module::Implementation::BEGIN@9 at line 179
# once (900ns+0s) by Module::Implementation::BEGIN@9 at line 205
# once (900ns+0s) by Module::Implementation::BEGIN@9 at line 194
# once (900ns+0s) by Module::Implementation::BEGIN@9 at line 188
# once (800ns+0s) by Module::Implementation::BEGIN@9 at line 203
# once (800ns+0s) by Module::Implementation::BEGIN@9 at line 191 | |||||
sub Module::Runtime::CORE:regcomp; # opcode | |||||
# spent 38µs within Module::Runtime::CORE:subst which was called 14 times, avg 3µs/call:
# 14 times (38µs+0s) by Module::Runtime::module_notional_filename at line 266, avg 3µs/call |