view release on metacpan or  search on metacpan

lib/Module/Runtime.pm  view on Meta::CPAN

The I<NAME> is a string, which should be a valid module name (one or
more C<::>-separated segments).  If it is not a valid name, the function
C<die>s.

The notional filename for the named module is generated and returned.
This filename is always in Unix style, with C</> directory separators
and a C<.pm> suffix.  This kind of filename can be used as an argument to
C<require>, and is the key that appears in C<%INC> to identify a module,
regardless of actual local filename syntax.

=cut

sub module_notional_filename($) {
	&check_module_name;
	my($name) = @_;
	$name =~ s!::!/!g;
	return $name.".pm";
}

=item require_module(NAME)

This is essentially the bareword form of C<require>, in runtime form.
The I<NAME> is a string, which should be a valid module name (one or
more C<::>-separated segments).  If it is not a valid name, the function
C<die>s.

The module specified by I<NAME> is loaded, if it hasn't been already,
in the manner of the bareword form of C<require>.  That means that a
search through C<@INC> is performed, and a byte-compiled form of the
module will be used if available.

The return value is as for C<require>.  That is, it is the value returned
by the module itself if the module is loaded anew, or C<1> if the module
was already loaded.

=cut

# Don't "use constant" here, to avoid dependencies.
BEGIN {
	*_WORK_AROUND_HINT_LEAKAGE =
		"$]" < 5.011 && !("$]" >= 5.009004 && "$]" < 5.010001)
			? sub(){1} : sub(){0};
	*_WORK_AROUND_BROKEN_MODULE_STATE = "$]" < 5.009 ? sub(){1} : sub(){0};
}

BEGIN { if(_WORK_AROUND_BROKEN_MODULE_STATE) { eval q{
	sub Module::Runtime::__GUARD__::DESTROY {
		delete $INC{$_[0]->[0]} if @{$_[0]};
	}
	1;
}; die $@ if $@ ne ""; } }

sub require_module($) {
	# Localise %^H to work around [perl #68590], where the bug exists
	# and this is a satisfactory workaround.  The bug consists of
	# %^H state leaking into each required module, polluting the
	# module's lexical state.
	local %^H if _WORK_AROUND_HINT_LEAKAGE;
	if(_WORK_AROUND_BROKEN_MODULE_STATE) {
		my $notional_filename = &module_notional_filename;
		my $guard = bless([ $notional_filename ],
				"Module::Runtime::__GUARD__");
		my $result = CORE::require($notional_filename);
		pop @$guard;
		return $result;
	} else {
		return scalar(CORE::require(&module_notional_filename));
	}
}

=back

=head2 Structured module use

=over

=item use_module(NAME[, VERSION])

This is essentially C<use> in runtime form, but without the importing
feature (which is fundamentally a compile-time thing).  The I<NAME> is
handled just like in C<require_module> above: it must be a module name,
and the named module is loaded as if by the bareword form of C<require>.

If a I<VERSION> is specified, the C<VERSION> method of the loaded module is
called with the specified I<VERSION> as an argument.  This normally serves to
ensure that the version loaded is at least the version required.  This is
the same functionality provided by the I<VERSION> parameter of C<use>.

On success, the name of the module is returned.  This is unlike
L</require_module>, and is done so that the entire call to L</use_module>
can be used as a class name to call a constructor, as in the example in
the synopsis.

=cut

sub use_module($;$) {
	my($name, $version) = @_;
	require_module($name);
	$name->VERSION($version) if @_ >= 2;
	return $name;
}

=item use_package_optimistically(NAME[, VERSION])

This is an analogue of L</use_module> for the situation where there is
uncertainty as to whether a package/class is defined in its own module
or by some other means.  It attempts to arrange for the named package to
be available, either by loading a module or by doing nothing and hoping.

An attempt is made to load the named module (as if by the bareword form
of C<require>).  If the module cannot be found then it is assumed that
the package was actually already loaded by other means, and no error
is signalled.  That's the optimistic bit.

I<Warning:> this optional module loading is liable to cause unreliable
behaviour, including security problems.  It interacts especially badly
with having C<.> in C<@INC>, which was the default state of affairs in
Perls prior to 5.25.11.  If a package is actually defined by some means
other than a module, then applying this function to it causes a spurious
attempt to load a module that is expected to be non-existent.  If a
module actually exists under that name then it will be unintentionally