/ 
Module-Installed-Tiny-0.011
River stage three • 17 direct dependents • 975 total dependents
/ Module::Installed::Tiny

NAME

Module::Installed::Tiny - Check if a module is installed, with as little code as possible

VERSION

This document describes version 0.011 of Module::Installed::Tiny (from Perl distribution Module-Installed-Tiny), released on 2022-08-22.

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:

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" function 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 https://metacpan.org/release/Module-Installed-Tiny.

SOURCE

Source repository is at https://github.com/perlancar/perl-Module-Installed-Tiny.

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, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. 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 https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Installed-Tiny

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.