.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Module::Path 3pm"
.TH Module::Path 3pm "2014-10-14" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Module::Path \- get the full path to a locally installed module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Module::Path \*(Aqmodule_path\*(Aq;
\& 
\& $path = module_path(\*(AqTest::More\*(Aq);
\& if (defined($path)) {
\&   print "Test::More found at $path\en";
\& } else {
\&   print "Danger Will Robinson!\en";
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a single function, \f(CW\*(C`module_path()\*(C'\fR,
which takes a module name and finds the first directory in your \f(CW@INC\fR path
where the module is installed locally.
It returns the full path to that file, resolving any symlinks.
It is portable and only depends on core modules.
.PP
It works by looking in all the directories in \f(CW@INC\fR
for an appropriately named file:
.IP "\(bu" 4
Foo::Bar becomes \f(CW\*(C`Foo/Bar.pm\*(C'\fR, using the correct directory path
separator for your operating system.
.IP "\(bu" 4
Iterate over \f(CW@INC\fR, ignoring any references
(see \*(L"require\*(R" in \*(L"perlfunc\*(R" if you're surprised to hear
that you might find references in \f(CW@INC\fR).
.IP "\(bu" 4
For each directory in \f(CW@INC\fR, append the partial path (\f(CW\*(C`Foo/Bar.pm\*(C'\fR),
again using the correct directory path separator.
If the resulting file exists, return this path.
.IP "\(bu" 4
If a directory in \f(CW@INC\fR is a symlink, then we resolve the path,
and return a path containing the linked-to directory.
.IP "\(bu" 4
If no file was found, return \f(CW\*(C`undef\*(C'\fR.
.PP
I wrote this module because I couldn't find an alternative
which dealt with the points listed above, and didn't pull in
what seemed like too many dependencies to me.
.PP
The distribution for \f(CW\*(C`Module::Path\*(C'\fR includes the \f(CW\*(C`mpath\*(C'\fR
script, which lets you get the path for a module from the command-line:
.PP
.Vb 1
\& % mpath Module::Path
.Ve
.PP
The \f(CW\*(C`module_path()\*(C'\fR function will also cope if the module name includes \f(CW\*(C`.pm\*(C'\fR;
this means you can pass a partial path, such as used as the keys in \f(CW%INC\fR:
.PP
.Vb 1
\&  module_path(\*(AqTest/More.pm\*(Aq) eq $INC{\*(AqTest/More.pm\*(Aq}
.Ve
.PP
The above is the basis for one of the tests.
.SH "BUGS"
.IX Header "BUGS"
Obviously this only works where the module you're after has its own \f(CW\*(C`.pm\*(C'\fR
file. If a file defines multiple packages, this won't work.
.PP
This also won't find any modules that are being loaded in some special
way, for example using a code reference in \f(CW@INC\fR, as described
in \*(L"require\*(R" in \*(L"perlfunc\*(R".
.SH "SEE ALSO"
.IX Header "SEE ALSO"
There are a number of other modules on \s-1CPAN\s0 which provide the
same or similar functionality:
App::whichpm,
Class::Inspector,
Module::Data,
Module::Filename,
Module::Finder,
Module::Info,
Module::Locate,
Module::Mapper,
Module::Metadata,
Module::Runtime,
Module::Util,
and Path::ScanINC.
.PP
I've written a review of all such modules that I'm aware of:
.Sp
.RS 4
<http://neilb.org/reviews/module\-path.html>
.RE
.PP
Module::Path was written to be fast, portable, and have a low number of
core-only runtime dependencies. It you only want to look up the path to
a module, it's a good choice.
.PP
If you want more information, such as the module's version, what functions
are provided, etc, then start by looking at Module::Info,
Module::Metadata, and Class::Inspector.
.PP
The following scripts can also give you the path:
perldoc,
whichpm <https://www.metacpan.org/module/whichpm>.
.SH "REPOSITORY"
.IX Header "REPOSITORY"
<https://github.com/neilbowers/Module\-Path>
.SH "AUTHOR"
.IX Header "AUTHOR"
Neil Bowers <neilb@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Neil Bowers <neilb@cpan.org>.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.