| 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 | Module::Runtime::require_module |
| 86 | 1 | 1 | 621µs | 1.46ms | Module::Runtime::is_module_name |
| 91 | 2 | 1 | 551µs | 551µs | Module::Runtime::CORE:match (opcode) |
| 86 | 2 | 2 | 387µs | 1.85ms | Module::Runtime::check_module_name |
| 86 | 1 | 1 | 279µs | 279µs | Module::Runtime::_is_string |
| 14 | 2 | 2 | 91µs | 300µs | Module::Runtime::module_notional_filename |
| 3 | 3 | 1 | 64µs | 64µs | Module::Runtime::CORE:regcomp (opcode) |
| 2 | 2 | 2 | 41µs | 44µs | Module::Runtime::import |
| 14 | 1 | 1 | 38µs | 38µs | Module::Runtime::CORE:subst (opcode) |
| 1 | 1 | 1 | 25µs | 25µs | Module::Runtime::BEGIN@116 |
| 1 | 1 | 1 | 9µs | 9µs | Module::Runtime::BEGIN@289 |
| 6 | 6 | 1 | 7µs | 7µs | Module::Runtime::CORE:qr (opcode) |
| 1 | 1 | 1 | 3µs | 3µs | Module::Runtime::BEGIN@120 |
| 1 | 1 | 1 | 3µs | 3µs | Module::Runtime::BEGIN@296 |
| 0 | 0 | 0 | 0s | 0s | Module::Runtime::check_module_spec |
| 0 | 0 | 0 | 0s | 0s | Module::Runtime::compose_module_name |
| 0 | 0 | 0 | 0s | 0s | Module::Runtime::is_module_spec |
| 0 | 0 | 0 | 0s | 0s | Module::Runtime::use_module |
| 0 | 0 | 0 | 0s | 0s | Module::Runtime::use_package_optimistically |
| 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 |