NAME
Module::Path::More - Get path to locally installed Perl module
VERSION
This document describes version 0.340 of Module::Path::More (from Perl distribution Module-Path-More), released on 2021-07-20.
SYNOPSIS
use Module::Path::More qw(module_path pod_path);
$path = module_path(module=>'Test::More');
if (defined($path)) {
print "Test::More found at $path\n";
} else {
print "Danger Will Robinson!\n";
}
# find all found modules, as well as .pmc and .pod files
$paths = module_path(module=>'Foo::Bar', all=>1, find_pmc=>1, find_pod=>1);
# just a shortcut for module_path(module=>'Foo',
# find_pm=>0, find_pmc=>0, find_pod=>1);
$path = pod_path(module=>'Foo');DESCRIPTION
Module::Path::More provides a function, module_path(), which will find where a module (or module prefix, or .pod file) is installed locally. (There is also another function pod_path() which is just a convenience wrapper.)
It works by looking in all the directories in @INC for an appropriately named file. If module is Foo::Bar, will search for Foo/Bar.pm, Foo/Bar.pmc (if find_pmc argument is true), Foo/Bar directory (if find_prefix argument is true), or Foo/Bar.pod (if find_pod argument is true).
Caveats: Obviously this only works where the module you're after has its own .pm file. If a file defines multiple packages, this won't work. This also won't find any modules that are being loaded in some special way, for example using a code reference in @INC, as described in require in perlfunc.
To check whether a module is available/loadable, it's generally better to use something like:
if (eval { require Some::Module; 1 }) {
# module is available
}because this works with fatpacking or any other @INC hook that might be installed. If you use:
if (module_path(module => "Some::Module")) {
# module is available
}then it only works if the module is locatable in the filesystem. But on the other hand this method can avoid actual loading of the module.
CONTRIBUTOR
Steven Haryanto <sharyanto@cpan.org>
FUNCTIONS
module_path
Usage:
module_path(%args) -> str|array[str]Get path to locally installed Perl module.
Examples:
Find the first Foo::Bar (.pm or .pmc) in @INC:
module_path(module => "Foo::Bar");Result:
"/home/s1/perl5/perlbrew/perls/perl-5.30.2/lib/site_perl/5.30.2/Foo/Bar.pm"Find all Foo::Bar (.pm or .pmc) in @INC, return absolute paths:
module_path(module => "Foo::Bar", abs => 1, all => 1);Result:
[ "/zpool_host_mnt/mnt/home/s1/perl5/perlbrew/perls/perl-5.30.2/lib/site_perl/5.30.2/Foo/Bar.pm", ]Find the Rinci (.pod first, then .pm) in @INC:
module_path(module => "Rinci", find_pm => 2, find_pmc => 0, find_pod => 1);Result:
"/home/s1/perl5/perlbrew/perls/perl-5.30.2/lib/site_perl/5.30.2/Rinci.pod"
Search @INC (reference entries are skipped) and return path(s) to Perl module files with the requested name.
This function is like the one from Module::Path, except with a different interface and more options (finding all matches instead of the first, the option of not absolutizing paths, finding .pmc & .pod files, finding module prefixes).
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
abs => bool (default: 0)
Whether to return absolute paths.
all => bool (default: 0)
Return all results instead of just the first.
find_pm => int (default: 1)
Whether to find .pm files.
The value of this option is an integer number from 0. 0 means to not search for .pm files, while number larger than 0 means to search for .pm files. The larger the number, the lower the priority. If more than one type is found (prefix, .pm, .pmc, .pod) then the type with the lowest number is returned first.
find_pmc => int (default: 2)
Whether to find .pmc files.
The value of this option is an integer number from 0. 0 means to not search for .pmc files, while number larger than 0 means to search for .pmc files. The larger the number, the lower the priority. If more than one type is found (prefix, .pm, .pmc, .pod) then the type with the lowest number is returned first.
find_pod => int (default: 0)
Whether to find .pod files.
The value of this option is an integer number from 0. 0 means to not search for .pod files, while number larger than 0 means to search for .pod files. The larger the number, the lower the priority. If more than one type is found (prefix, .pm, .pmc, .pod) then the type with the lowest number is returned first.
find_prefix => int (default: 0)
Whether to find module prefixes.
The value of this option is an integer number from 0. 0 means to not search for module prefix, while number larger than 0 means to search for module prefix. The larger the number, the lower the priority. If more than one type is found (prefix, .pm, .pmc, .pod) then the type with the lowest number is returned first.
module* => str
Module name to search.
Return value: (str|array[str])
pod_path
Usage:
pod_path(%args) -> str|array[str]Get path to locally installed POD.
This is a shortcut for:
module_path(%args, find_pm=>0, find_pmc=>0, find_pod=>1, find_prefix=>0)This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
abs => bool (default: 0)
Whether to return absolute paths.
all => bool (default: 0)
Return all results instead of just the first.
module* => str
Module name to search.
Return value: (str|array[str])
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Module-Path-More.
SOURCE
Source repository is at https://github.com/perlancar/perl-Module-Path-More.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Path-More
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.
SEE ALSO
Similar modules
Module::Path. Module::Path::More is actually a fork of Module::Path. Module::Path::More contains features that are not (or have not been accepted) in the original module, namely: finding all matches instead of the first found match, and finding .pmc/.pod in addition to .pm files. Note that the interface is different (Module::Path::More accepts hash/named arguments) so the two modules are not drop-in replacements for each other. Also, note that by default Module::Path::More does not do an abs_path() to each file it finds. I think this module's choice (not doing abs_path) is a more sensible default, because usually there is no actual need to do so and doing abs_path() or resolving symlinks will sometimes fail or expose filesystem quirks that we might not want to deal with at all. However, if you want to do abs_path, you can do so by setting abs option to true.
Command-line utility is not included in this distribution, unlike mpath in Module-Path. However, you can use pmpath from App::PMUtils distribution which uses this module.
References:
Task-related
If you want to check if a module is "installed", use Module::Installed::Tiny instead. Module::Path::More only tries to find the module file in the filesystem, but Perl can actually search for modules in other sources (read about %INC hook in require() section of perlfunc). Module::Installed::Tiny can mimic Perl's behavior in searching for modules, without actually loading the module.
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2021, 2017, 2016, 2015, 2014 by 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.