NAME
Module::Path::More - Get path to locally installed Perl module
VERSION
This document describes version 0.31 of Module::Path::More (from Perl distribution Module-Path-More), released on 2016-08-03.
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.
FUNCTIONS
module_path(%args) -> str|array[str]
Get path to locally installed Perl module.
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 => bool (default: 1)
Whether to find .pm files.
find_pmc => bool (default: 1)
Whether to find .pmc files.
find_pod => bool (default: 0)
Whether to find .pod files.
find_prefix => bool (default: 0)
Whether to find module prefixes.
module* => str
Module name to search.
Return value: (str|array[str])
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
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 which uses this module.
References:
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2016 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.