| Filename | /Users/dde/perl5/perlbrew/perls/5.18.0t/lib/site_perl/5.18.0/Module/Runtime.pm |
| Statements | Executed 1790 statements in 11.5ms |
| Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
|---|---|---|---|---|---|
| 26 | 3 | 3 | 11.9ms | 151ms | Module::Runtime::require_module (recurses: max depth 3, inclusive time 71.1ms) |
| 374 | 1 | 1 | 5.56ms | 6.99ms | Module::Runtime::is_module_name |
| 379 | 2 | 1 | 779µs | 779µs | Module::Runtime::CORE:match (opcode) |
| 374 | 3 | 2 | 652µs | 7.64ms | Module::Runtime::check_module_name |
| 374 | 1 | 1 | 579µs | 579µs | Module::Runtime::_is_string |
| 49 | 3 | 2 | 240µs | 821µs | Module::Runtime::module_notional_filename |
| 49 | 1 | 1 | 126µs | 126µs | Module::Runtime::CORE:subst (opcode) |
| 376 | 3 | 1 | 119µs | 119µs | Module::Runtime::CORE:regcomp (opcode) |
| 2 | 2 | 2 | 33µs | 34µs | Module::Runtime::import |
| 1 | 1 | 1 | 14µs | 1.20ms | Module::Runtime::use_module |
| 1 | 1 | 1 | 14µs | 14µs | Module::Runtime::BEGIN@116 |
| 1 | 1 | 1 | 6µs | 6µs | Module::Runtime::BEGIN@289 |
| 6 | 6 | 1 | 6µs | 6µs | Module::Runtime::CORE:qr (opcode) |
| 1 | 1 | 1 | 3µs | 3µs | Module::Runtime::BEGIN@120 |
| 1 | 1 | 1 | 2µs | 2µ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_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 | 29µs | 1 | 14µs | # spent 14µs within Module::Runtime::BEGIN@116 which was called:
# once (14µs+0s) by Module::Implementation::BEGIN@12 at line 116 # spent 14µ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 | 571µs | 1 | 3µs | # spent 3µs within Module::Runtime::BEGIN@120 which was called:
# once (3µs+0s) by Module::Implementation::BEGIN@12 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 | 2µ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 | 8µs | my %export_ok = map { ($_ => undef) } @EXPORT_OK; | ||
| 135 | # spent 34µs (33+1) within Module::Runtime::import which was called 2 times, avg 17µs/call:
# once (21µs+900ns) by Class::Load::BEGIN@10 at line 15 of Class/Load.pm
# once (12µs+500ns) by Module::Implementation::BEGIN@12 at line 12 of Module/Implementation.pm | ||||
| 136 | 2 | 500ns | my $me = shift; | ||
| 137 | 2 | 800ns | my $callpkg = caller(0); | ||
| 138 | 2 | 200ns | my $errs = ""; | ||
| 139 | 2 | 1µs | foreach(@_) { | ||
| 140 | 5 | 3µ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 | 10µs | 5 | 1µs | if(/\A\$(.*)\z/s) { # spent 1µs making 5 calls to Module::Runtime::CORE:match, avg 280ns/call |
| 144 | *{$callpkg."::".$1} = \$$1; | ||||
| 145 | } else { | ||||
| 146 | 5 | 11µs | *{$callpkg."::".$_} = \&$_; | ||
| 147 | } | ||||
| 148 | } else { | ||||
| 149 | $errs .= "\"$_\" is not exported by the $me module\n"; | ||||
| 150 | } | ||||
| 151 | } | ||||
| 152 | 2 | 5µs | 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 579µs within Module::Runtime::_is_string which was called 374 times, avg 2µs/call:
# 374 times (579µs+0s) by Module::Runtime::is_module_name at line 222, avg 2µs/call | ||||
| 161 | 374 | 105µs | my($arg) = @_; | ||
| 162 | 374 | 719µs | 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 | 6µs | 1 | 1µs | our $module_name_rx = qr/[A-Z_a-z][0-9A-Z_a-z]*(?:::[0-9A-Z_a-z]+)*/; # spent 1µ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 | 700ns | my $unqual_top_module_spec_rx = # spent 700ns 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 | 38µs | 2 | 32µs | our $top_module_spec_rx = qr/$qual_module_spec_rx|$unqual_top_module_spec_rx/o; # spent 31µ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 | 700ns | my $unqual_sub_module_spec_rx = qr#[0-9A-Z_a-z]+(?:(?:/|::)[0-9A-Z_a-z]+)*#; # spent 700ns making 1 call to Module::Runtime::CORE:qr |
| 204 | |||||
| 205 | 1 | 28µs | 2 | 23µs | our $sub_module_spec_rx = qr/$qual_module_spec_rx|$unqual_sub_module_spec_rx/o; # spent 22µ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 | 374 | 6.27ms | 1122 | 1.42ms | # spent 6.99ms (5.56+1.42) within Module::Runtime::is_module_name which was called 374 times, avg 19µs/call:
# 374 times (5.56ms+1.42ms) by Module::Runtime::check_module_name at line 241, avg 19µs/call # spent 778µs making 374 calls to Module::Runtime::CORE:match, avg 2µs/call
# spent 579µs making 374 calls to Module::Runtime::_is_string, avg 2µs/call
# spent 66µs making 374 calls to Module::Runtime::CORE:regcomp, avg 177ns/call |
| 223 | |||||
| 224 | =item is_valid_module_name(ARG) | ||||
| 225 | |||||
| 226 | Deprecated alias for L</is_module_name>. | ||||
| 227 | |||||
| 228 | =cut | ||||
| 229 | |||||
| 230 | 1 | 700ns | *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 7.64ms (652µs+6.99) within Module::Runtime::check_module_name which was called 374 times, avg 20µs/call:
# 321 times (564µs+6.58ms) by Class::Load::try_load_class at line 139 of Class/Load.pm, avg 22µs/call
# 49 times (80µs+375µs) by Module::Runtime::module_notional_filename at line 264, avg 9µs/call
# 4 times (7µs+30µs) by Class::Load::load_first_existing_class at line 49 of Class/Load.pm, avg 9µs/call | ||||
| 241 | 374 | 558µs | 374 | 6.99ms | unless(&is_module_name) { # spent 6.99ms making 374 calls to Module::Runtime::is_module_name, avg 19µ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 821µs (240+581) within Module::Runtime::module_notional_filename which was called 49 times, avg 17µs/call:
# 26 times (122µs+325µs) by Module::Runtime::require_module at line 317, avg 17µs/call
# 22 times (113µs+244µs) by Class::Load::try_load_class at line 158 of Class/Load.pm, avg 16µs/call
# once (5µs+13µs) by Class::Load::load_first_existing_class at line 63 of Class/Load.pm | ||||
| 264 | 49 | 38µs | 49 | 455µs | &check_module_name; # spent 455µs making 49 calls to Module::Runtime::check_module_name, avg 9µs/call |
| 265 | 49 | 13µs | my($name) = @_; | ||
| 266 | 49 | 194µs | 49 | 126µs | $name =~ s!::!/!g; # spent 126µs making 49 calls to Module::Runtime::CORE:subst, avg 3µs/call |
| 267 | 49 | 93µs | 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 6µs within Module::Runtime::BEGIN@289 which was called:
# once (6µs+0s) by Module::Implementation::BEGIN@12 at line 294 | ||||
| 290 | *_WORK_AROUND_HINT_LEAKAGE = | ||||
| 291 | "$]" < 5.011 && !("$]" >= 5.009004 && "$]" < 5.010001) | ||||
| 292 | 1 | 2µs | ? sub(){1} : sub(){0}; | ||
| 293 | 1 | 4µs | *_WORK_AROUND_BROKEN_MODULE_STATE = "$]" < 5.009 ? sub(){1} : sub(){0}; | ||
| 294 | 1 | 35µs | 1 | 6µs | } # spent 6µs making 1 call to Module::Runtime::BEGIN@289 |
| 295 | |||||
| 296 | 1 | 3µs | # spent 2µs within Module::Runtime::BEGIN@296 which was called:
# once (2µs+0s) by Module::Implementation::BEGIN@12 at line 301 | ||
| 297 | sub Module::Runtime::__GUARD__::DESTROY { | ||||
| 298 | delete $INC{$_[0]->[0]} if @{$_[0]}; | ||||
| 299 | } | ||||
| 300 | 1; | ||||
| 301 | 1 | 417µs | 1 | 2µs | }; die $@ if $@ ne ""; } } # spent 2µs making 1 call to Module::Runtime::BEGIN@296 |
| 302 | |||||
| 303 | # spent 151ms (11.9+139) within Module::Runtime::require_module which was called 26 times, avg 5.79ms/call:
# 22 times (10.3ms+138ms) by Class::Load::try {...} at line 177 of Class/Load.pm, avg 6.72ms/call
# 3 times (780µs+1.91ms) by Module::Implementation::try {...} at line 88 of Module/Implementation.pm, avg 897µs/call
# once (801µs+-801µs) by Module::Runtime::use_module at line 348 | ||||
| 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 | local %^H if _WORK_AROUND_HINT_LEAKAGE; | ||||
| 309 | 26 | 1µ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 | 26 | 2.28ms | 26 | 447µs | return scalar(require(&module_notional_filename)); # spent 447µs making 26 calls to Module::Runtime::module_notional_filename, avg 17µ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 | # spent 1.20ms (14µs+1.19) within Module::Runtime::use_module which was called:
# once (14µs+1.19ms) by B::Hooks::EndOfScope::XS::BEGIN@13 at line 16 of B/Hooks/EndOfScope/XS.pm | ||||
| 347 | 1 | 800ns | my($name, $version) = @_; | ||
| 348 | 1 | 2µs | 1 | 0s | require_module($name); # spent 1.18ms making 1 call to Module::Runtime::require_module, recursion: max depth 1, sum of overlapping time 1.18ms |
| 349 | 1 | 11µs | 1 | 5µs | if(defined $version) { # spent 5µs making 1 call to UNIVERSAL::VERSION |
| 350 | $name->VERSION($version); | ||||
| 351 | } | ||||
| 352 | 1 | 3µs | 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 | 200ns | *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 6µs within Module::Runtime::CORE:qr which was called 6 times, avg 917ns/call:
# once (1µs+0s) by Module::Implementation::BEGIN@12 at line 179
# once (900ns+0s) by Module::Implementation::BEGIN@12 at line 194
# once (900ns+0s) by Module::Implementation::BEGIN@12 at line 188
# once (900ns+0s) by Module::Implementation::BEGIN@12 at line 205
# once (700ns+0s) by Module::Implementation::BEGIN@12 at line 203
# once (700ns+0s) by Module::Implementation::BEGIN@12 at line 191 | |||||
# spent 119µs within Module::Runtime::CORE:regcomp which was called 376 times, avg 316ns/call:
# 374 times (66µs+0s) by Module::Runtime::is_module_name at line 222, avg 177ns/call
# once (31µs+0s) by Module::Implementation::BEGIN@12 at line 194
# once (22µs+0s) by Module::Implementation::BEGIN@12 at line 205 | |||||
# spent 126µs within Module::Runtime::CORE:subst which was called 49 times, avg 3µs/call:
# 49 times (126µs+0s) by Module::Runtime::module_notional_filename at line 266, avg 3µs/call |