NAME
Module::Installed::Tiny - Check if a module is installed, with as little
code as possible
VERSION
This document describes version 0.010 of Module::Installed::Tiny (from
Perl distribution Module-Installed-Tiny), released on 2022-07-30.
SYNOPSIS
use Module::Installed::Tiny qw(module_installed module_source);
# check if a module is available
if (module_installed "Foo::Bar") {
# Foo::Bar is available
} elsif (module_installed "Foo/Baz.pm") {
# Foo::Baz is available
}
# get a module's source code, dies on failure
my $src = module_source("Foo/Baz.pm");
DESCRIPTION
To check if a module is installed (available), generally the simplest
way is to try to "require()" it:
if (eval { require Foo::Bar; 1 }) {
# Foo::Bar is available
}
# or
my $mod_pm = "Foo/Bar.pm";
if (eval { require $mod_pm; 1 }) {
# Foo::Bar is available
}
However, this actually loads the module. There are some cases where this
is not desirable: 1) we have to check a lot of modules (actually loading
the modules will take a lot of CPU time and memory; 2) some of the
modules conflict with one another and cannot all be loaded; 3) the
module is OS specific and might not load under another OS; 4) we simply
do not want to execute the module, for security or other reasons.
"Module::Installed::Tiny" provides a routine "module_installed()" which
works like Perl's "require" but does not actually load the module.
This module does not require any other module except Exporter.
FUNCTIONS
module_source
Usage:
module_source($name [ , \%opts ]) => str | list
Return module's source code, without actually loading/executing it.
Module source will be searched in @INC the way Perl's "require()" finds
modules. This include executing require hooks in @INC if there are any.
Die on failure (e.g. module named $name not found in @INC or module
source file cannot be read) with the same/similar message as Perl's
"require()":
Can't locate Foo/Bar.pm (you may need to install the Foo::Bar module) ...
Module $name can be in the form of "Foo::Bar", "Foo/Bar.pm" or
"Foo\Bar.pm" (on Windows).
In list context, will return a record of information:
# [0] [1] [2] [3] [4] [5] [6]
my ($src, $path, $entry, $index, $name_mod, $name_pm, $name_path) = module_source($name);
where:
* $src
String. The module source code.
* $path
String. The filesystem path ("undef" if source comes from a require
hook).
* $entry
The element in @INC where the source comes from.
* $index
Integer, the index of entry in @INC where the source comes from, 0
means the first entry.
* $name_mod
Module name normalized to "Foo::Bar" form.
* $name_pm
Module name normalized to "Foo/Bar.pm" form.
* $name_path
Module name normalized to "Foo/Bar.pm" form or "Foo\Bar.pm" form
depending on the native path separator character.
Options:
* die
Bool. Default true. If set to false, won't die upon failure but
instead will return undef (or empty list in list context).
* find_prefix
Bool. If set to true, when a module (e.g. "Foo/Bar.pm") is not found
in the fileysstem but its directory is ("Foo/Bar/"), then instead of
dying or returning undef/empty list, the function will return:
\$path
in scalar context, or:
(undef, $path, $entry, $index, $name_mod, $name_pm, $name_path)
in list context. In scalar context, you can differentiate path from
module source because the path is returned as a scalar reference. So
to get the path:
$source_or_pathref = module_source("Foo/Bar.pm", {find_prefix=>1});
if (ref $source_or_pathref eq 'SCALAR') {
say "Path is ", $$source_or_pathref;
} else {
say "Module source code is $source_or_pathref";
}
* all
Bool. If set to true, then instead of stopping after one source is
found, the function will continue finding sources until all entries
in @INC is exhausted. Then will return all the found sources as an
arrayref:
my $sources = module_source($name, {all=>1});
In list context, will return a list of records instead of a single
record:
my @records = module_source($name, {all=>1});
for my $record (@records) {
my ($src, $path, $entry, $index, $name_mod, $name_pm, $name_path) = @$record;
...
}
module_installed
Usage:
module_installed($name [ , \%opts ]) => bool
Check that module named $name is available to load, without actually
loading/executing the module. Module will be searched in @INC the way
Perl's "require()" finds modules. This include executing require hooks
in @INC if there are any.
Note that this does not guarantee that the module can eventually be
loaded successfully, as there might be syntax or runtime errors in the
module's source. To check for that, one would need to actually load the
module using "require".
Module $name can be in the form of "Foo::Bar", "Foo/Bar.pm" or
Foo\Bar.pm (on Windows).
Options:
* find_prefix
See "module_source" documentation.
FAQ
How to get module source without dying? I want to just get undef if module source is not available.
Set the "die" option to false:
my $src = module_source($name, {die=>0});
This is what "module_installed()" does.
How to know which @INC entry the source comes from?
Call the "module_source" in list context, where you will get more
information including the entry. See the function documentation for more
details.
HOMEPAGE
Please visit the project's homepage at
SOURCE
Source repository is at
SEE ALSO
Module::Load::Conditional provides "check_install" which also does what
"module_installed" does, plus can check module version. It also has a
couple other knobs to customize its behavior. It's less tiny than
Module::Installed::Tiny though.
Module::Path and Module::Path::More. These modules can also be used to
check if a module on the filesystem is available. They do not handle
require hooks, nor do they actually check that the module file is
readable.
AUTHOR
perlancar <perlancar@cpan.org>
CONTRIBUTING
To contribute, you can send patches by email/via RT, or send pull
requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You
can simply modify the code, then test via:
% prove -l
If you want to build the distribution (e.g. to try to install it locally
on your system), you can install Dist::Zilla,
Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two
other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional
steps required beyond that are considered a bug and can be reported to
me.
COPYRIGHT AND LICENSE
This software is copyright (c) 2022, 2021, 2020, 2016 by perlancar
<perlancar@cpan.org>.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
BUGS
Please report any bugs or feature requests on the bugtracker website
>
When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.