| Filename | /home/s1/perl5/perlbrew/perls/perl-5.22.1/lib/site_perl/5.22.1/Module/Runtime.pm |
| Statements | Executed 51 statements in 2.43ms |
| Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
|---|---|---|---|---|---|
| 1 | 1 | 1 | 723µs | 1.28ms | Module::Runtime::require_module |
| 3 | 3 | 1 | 115µs | 115µs | Module::Runtime::CORE:regcomp (opcode) |
| 3 | 3 | 3 | 55µs | 59µs | Module::Runtime::import |
| 1 | 1 | 1 | 35µs | 35µs | Module::Runtime::BEGIN@116 |
| 1 | 1 | 1 | 16µs | 53µs | Module::Runtime::is_module_name |
| 1 | 1 | 1 | 14µs | 76µs | Module::Runtime::module_notional_filename |
| 1 | 1 | 1 | 12µs | 12µs | Module::Runtime::BEGIN@289 |
| 4 | 2 | 1 | 10µs | 10µs | Module::Runtime::CORE:match (opcode) |
| 6 | 6 | 1 | 7µs | 7µs | Module::Runtime::CORE:qr (opcode) |
| 1 | 1 | 1 | 6µs | 6µs | Module::Runtime::BEGIN@120 |
| 1 | 1 | 1 | 5µs | 5µs | Module::Runtime::BEGIN@296 |
| 1 | 1 | 1 | 5µs | 58µs | Module::Runtime::check_module_name |
| 1 | 1 | 1 | 3µs | 3µs | Module::Runtime::_is_string |
| 1 | 1 | 1 | 3µs | 3µs | Module::Runtime::CORE:subst (opcode) |
| 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 syntax | ||||
| 46 | that is used for barewords in Perl source. In principle this syntax | ||||
| 47 | can vary between versions of Perl, and this module applies the syntax of | ||||
| 48 | the Perl on which it is running. In practice the usable syntax hasn't | ||||
| 49 | changed yet. There's some intent for Unicode module names to be supported | ||||
| 50 | in the future, but this hasn't yet amounted to any consistent facility. | ||||
| 51 | |||||
| 52 | The functions of this module whose purpose is to load modules include | ||||
| 53 | workarounds for three old Perl core bugs regarding C<require>. These | ||||
| 54 | workarounds are applied on any Perl version where the bugs exist, except | ||||
| 55 | for a case where one of the bugs cannot be adequately worked around in | ||||
| 56 | pure Perl. | ||||
| 57 | |||||
| 58 | =head2 Module name syntax | ||||
| 59 | |||||
| 60 | The usable module name syntax has not changed from Perl 5.000 up to | ||||
| 61 | Perl 5.19.8. The syntax is composed entirely of ASCII characters. | ||||
| 62 | From Perl 5.6 onwards there has been some attempt to allow the use of | ||||
| 63 | non-ASCII Unicode characters in Perl source, but it was fundamentally | ||||
| 64 | broken (like the entirety of Perl 5.6's Unicode handling) and remained | ||||
| 65 | pretty much entirely unusable until it got some attention in the Perl | ||||
| 66 | 5.15 series. Although Unicode is now consistently accepted by the | ||||
| 67 | parser in some places, it remains broken for module names. Furthermore, | ||||
| 68 | there has not yet been any work on how to map Unicode module names into | ||||
| 69 | filenames, so in that respect also Unicode module names are unusable. | ||||
| 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 | 62µs | 1 | 35µs | # spent 35µs within Module::Runtime::BEGIN@116 which was called:
# once (35µs+0s) by Module::Implementation::BEGIN@8 at line 116 # spent 35µ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 | 959µs | 1 | 6µs | # spent 6µs within Module::Runtime::BEGIN@120 which was called:
# once (6µs+0s) by Module::Implementation::BEGIN@8 at line 120 # spent 6µs making 1 call to Module::Runtime::BEGIN@120 |
| 121 | # Don't "use strict" here, to avoid dependencies. | ||||
| 122 | |||||
| 123 | 1 | 900ns | our $VERSION = "0.014"; | ||
| 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 | 13µs | my %export_ok = map { ($_ => undef) } @EXPORT_OK; | ||
| 135 | # spent 59µs (55+3) within Module::Runtime::import which was called 3 times, avg 20µs/call:
# once (19µs+1µs) by DateTime::TimeZone::Local::BEGIN@8 at line 8 of DateTime/TimeZone/Local.pm
# once (19µs+1µs) by Module::Implementation::BEGIN@8 at line 8 of Module/Implementation.pm
# once (17µs+1µs) by DateTime::TimeZone::BEGIN@14 at line 14 of DateTime/TimeZone.pm | ||||
| 136 | 3 | 2µs | my $me = shift; | ||
| 137 | 3 | 2µs | my $callpkg = caller(0); | ||
| 138 | 3 | 800ns | my $errs = ""; | ||
| 139 | 3 | 5µs | foreach(@_) { | ||
| 140 | 3 | 6µ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 | 3 | 18µs | 3 | 4µs | if(/\A\$(.*)\z/s) { # spent 4µs making 3 calls to Module::Runtime::CORE:match, avg 1µs/call |
| 144 | *{$callpkg."::".$1} = \$$1; | ||||
| 145 | } else { | ||||
| 146 | 3 | 17µs | *{$callpkg."::".$_} = \&$_; | ||
| 147 | } | ||||
| 148 | } else { | ||||
| 149 | $errs .= "\"$_\" is not exported by the $me module\n"; | ||||
| 150 | } | ||||
| 151 | } | ||||
| 152 | 3 | 15µ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 3µs within Module::Runtime::_is_string which was called:
# once (3µs+0s) by Module::Runtime::is_module_name at line 222 | ||||
| 161 | 1 | 500ns | my($arg) = @_; | ||
| 162 | 1 | 6µ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 | 11µ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 | 4µ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 | 4µ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 | 62µs | 2 | 51µs | our $top_module_spec_rx = qr/$qual_module_spec_rx|$unqual_top_module_spec_rx/o; # spent 50µs making 1 call to Module::Runtime::CORE:regcomp
# spent 1µs 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 | 4µ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 | 46µs | 2 | 38µs | our $sub_module_spec_rx = qr/$qual_module_spec_rx|$unqual_sub_module_spec_rx/o; # spent 37µs making 1 call to Module::Runtime::CORE:regcomp
# spent 1µs 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 | 1 | 50µs | 3 | 37µs | # spent 53µs (16+37) within Module::Runtime::is_module_name which was called:
# once (16µs+37µs) by Module::Runtime::check_module_name at line 241 # spent 27µs making 1 call to Module::Runtime::CORE:regcomp
# spent 6µs making 1 call to Module::Runtime::CORE:match
# spent 3µs making 1 call to Module::Runtime::_is_string |
| 223 | |||||
| 224 | =item is_valid_module_name(ARG) | ||||
| 225 | |||||
| 226 | Deprecated alias for L</is_module_name>. | ||||
| 227 | |||||
| 228 | =cut | ||||
| 229 | |||||
| 230 | 1 | 2µ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 58µs (5+53) within Module::Runtime::check_module_name which was called:
# once (5µs+53µs) by Module::Runtime::module_notional_filename at line 264 | ||||
| 241 | 1 | 6µs | 1 | 53µs | unless(&is_module_name) { # spent 53µs making 1 call to Module::Runtime::is_module_name |
| 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 76µs (14+61) within Module::Runtime::module_notional_filename which was called:
# once (14µs+61µs) by Module::Runtime::require_module at line 317 | ||||
| 264 | 1 | 2µs | 1 | 58µs | &check_module_name; # spent 58µs making 1 call to Module::Runtime::check_module_name |
| 265 | 1 | 600ns | my($name) = @_; | ||
| 266 | 1 | 9µs | 1 | 3µs | $name =~ s!::!/!g; # spent 3µs making 1 call to Module::Runtime::CORE:subst |
| 267 | 1 | 5µ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 12µs within Module::Runtime::BEGIN@289 which was called:
# once (12µs+0s) by Module::Implementation::BEGIN@8 at line 294 | ||||
| 290 | *_WORK_AROUND_HINT_LEAKAGE = | ||||
| 291 | "$]" < 5.011 && !("$]" >= 5.009004 && "$]" < 5.010001) | ||||
| 292 | 1 | 4µs | ? sub(){1} : sub(){0}; | ||
| 293 | 1 | 12µs | *_WORK_AROUND_BROKEN_MODULE_STATE = "$]" < 5.009 ? sub(){1} : sub(){0}; | ||
| 294 | 1 | 62µs | 1 | 12µs | } # spent 12µs making 1 call to Module::Runtime::BEGIN@289 |
| 295 | |||||
| 296 | 1 | 6µs | # spent 5µs within Module::Runtime::BEGIN@296 which was called:
# once (5µs+0s) by Module::Implementation::BEGIN@8 at line 301 | ||
| 297 | sub Module::Runtime::__GUARD__::DESTROY { | ||||
| 298 | delete $INC{$_[0]->[0]} if @{$_[0]}; | ||||
| 299 | } | ||||
| 300 | 1; | ||||
| 301 | 1 | 714µs | 1 | 5µs | }; die $@ if $@ ne ""; } } # spent 5µs making 1 call to Module::Runtime::BEGIN@296 |
| 302 | |||||
| 303 | # spent 1.28ms (723µs+560µs) within Module::Runtime::require_module which was called:
# once (723µs+560µs) by Module::Implementation::try {...} at line 93 of Module/Implementation.pm | ||||
| 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 | 1 | 300ns | 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 = CORE::require($notional_filename); | ||||
| 314 | pop @$guard; | ||||
| 315 | return $result; | ||||
| 316 | } else { | ||||
| 317 | 1 | 299µs | 1 | 76µs | return scalar(CORE::require(&module_notional_filename)); # spent 76µs making 1 call to Module::Runtime::module_notional_filename |
| 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 | $name->VERSION($version) if @_ >= 2; | ||||
| 350 | return $name; | ||||
| 351 | } | ||||
| 352 | |||||
| 353 | =item use_package_optimistically(NAME[, VERSION]) | ||||
| 354 | |||||
| 355 | This is an analogue of L</use_module> for the situation where there is | ||||
| 356 | uncertainty as to whether a package/class is defined in its own module | ||||
| 357 | or by some other means. It attempts to arrange for the named package to | ||||
| 358 | be available, either by loading a module or by doing nothing and hoping. | ||||
| 359 | |||||
| 360 | An attempt is made to load the named module (as if by the bareword form | ||||
| 361 | of C<require>). If the module cannot be found then it is assumed that | ||||
| 362 | the package was actually already loaded by other means, and no error | ||||
| 363 | is signalled. That's the optimistic bit. | ||||
| 364 | |||||
| 365 | This is mostly the same operation that is performed by the L<base> pragma | ||||
| 366 | to ensure that the specified base classes are available. The behaviour | ||||
| 367 | of L<base> was simplified in version 2.18, and later improved in version | ||||
| 368 | 2.20, and on both occasions this function changed to match. | ||||
| 369 | |||||
| 370 | If a I<VERSION> is specified, the C<VERSION> method of the loaded package is | ||||
| 371 | called with the specified I<VERSION> as an argument. This normally serves | ||||
| 372 | to ensure that the version loaded is at least the version required. | ||||
| 373 | On success, the name of the package is returned. These aspects of the | ||||
| 374 | function work just like L</use_module>. | ||||
| 375 | |||||
| 376 | =cut | ||||
| 377 | |||||
| 378 | sub use_package_optimistically($;$) { | ||||
| 379 | my($name, $version) = @_; | ||||
| 380 | my $fn = module_notional_filename($name); | ||||
| 381 | eval { local $SIG{__DIE__}; require_module($name); }; | ||||
| 382 | die $@ if $@ ne "" && | ||||
| 383 | ($@ !~ /\ACan't locate \Q$fn\E .+ at \Q@{[__FILE__]}\E line/s || | ||||
| 384 | $@ =~ /^Compilation\ failed\ in\ require | ||||
| 385 | \ at\ \Q@{[__FILE__]}\E\ line/xm); | ||||
| 386 | $name->VERSION($version) if @_ >= 2; | ||||
| 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 | 400ns | *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 BUGS | ||||
| 472 | |||||
| 473 | On Perl versions 5.7.2 to 5.8.8, if C<require> is overridden by the | ||||
| 474 | C<CORE::GLOBAL> mechanism, it is likely to break the heuristics used by | ||||
| 475 | L</use_package_optimistically>, making it signal an error for a missing | ||||
| 476 | module rather than assume that it was already loaded. From Perl 5.8.9 | ||||
| 477 | onwards, and on 5.7.1 and earlier, this module can avoid being confused | ||||
| 478 | by such an override. On the affected versions, a C<require> override | ||||
| 479 | might be installed by L<Lexical::SealRequireHints>, if something requires | ||||
| 480 | its bugfix but for some reason its XS implementation isn't available. | ||||
| 481 | |||||
| 482 | =head1 SEE ALSO | ||||
| 483 | |||||
| 484 | L<Lexical::SealRequireHints>, | ||||
| 485 | L<base>, | ||||
| 486 | L<perlfunc/require>, | ||||
| 487 | L<perlfunc/use> | ||||
| 488 | |||||
| 489 | =head1 AUTHOR | ||||
| 490 | |||||
| 491 | Andrew Main (Zefram) <zefram@fysh.org> | ||||
| 492 | |||||
| 493 | =head1 COPYRIGHT | ||||
| 494 | |||||
| 495 | Copyright (C) 2004, 2006, 2007, 2009, 2010, 2011, 2012, 2014 | ||||
| 496 | Andrew Main (Zefram) <zefram@fysh.org> | ||||
| 497 | |||||
| 498 | =head1 LICENSE | ||||
| 499 | |||||
| 500 | This module is free software; you can redistribute it and/or modify it | ||||
| 501 | under the same terms as Perl itself. | ||||
| 502 | |||||
| 503 | =cut | ||||
| 504 | |||||
| 505 | 1 | 18µ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@8 at line 179
# once (1µs+0s) by Module::Implementation::BEGIN@8 at line 194
# once (1µs+0s) by Module::Implementation::BEGIN@8 at line 205
# once (900ns+0s) by Module::Implementation::BEGIN@8 at line 188
# once (800ns+0s) by Module::Implementation::BEGIN@8 at line 203
# once (800ns+0s) by Module::Implementation::BEGIN@8 at line 191 | |||||
sub Module::Runtime::CORE:regcomp; # opcode | |||||
# spent 3µs within Module::Runtime::CORE:subst which was called:
# once (3µs+0s) by Module::Runtime::module_notional_filename at line 266 |