view release on metacpan or  search on metacpan

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

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
loaded.  If C<.> is in C<@INC> and this code is ever run with the current
directory being one writable by a malicious user (such as F</tmp>), then
the malicious user can easily cause the victim to run arbitrary code, by
creating a module file under the predictable spuriously-loaded name in the
writable directory.  Generally, optional module loading should be avoided.

This is mostly the same operation that is performed by the L<base> pragma
to ensure that the specified base classes are available.  The behaviour
of L<base> was simplified in version 2.18, and later improved in version
2.20, and on both occasions this function changed to match.

If a I<VERSION> is specified, the C<VERSION> method of the loaded package 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.
On success, the name of the package is returned.  These aspects of the
function work just like L</use_module>.

=cut

sub use_package_optimistically($;$) {
	my($name, $version) = @_;
	my $fn = module_notional_filename($name);
	eval { local $SIG{__DIE__}; require_module($name); };
	die $@ if $@ ne "" &&
		($@ !~ /\ACan't locate \Q$fn\E .+ at \Q@{[__FILE__]}\E line/s ||
		 $@ =~ /^Compilation\ failed\ in\ require
			 \ at\ \Q@{[__FILE__]}\E\ line/xm);
	$name->VERSION($version) if @_ >= 2;
	return $name;
}

=back

=head2 Module name composition

=over

=item is_module_spec(PREFIX, SPEC)

Returns a truth value indicating
whether I<SPEC> is valid input for L</compose_module_name>.
See below for what that entails.  Whether a I<PREFIX> is supplied affects
the validity of I<SPEC>, but the exact value of the prefix is unimportant,
so this function treats I<PREFIX> as a truth value.