NAME

Module::Which::P5Path - Translate paths to Config-relative paths

SYNOPSIS

   use Module::Which::P5Path qw(path_to_p5path p5path_to_path);

   $path = "$Config{installarchlib}/A/B.pm";
   $p5path = path_to_p5path($path); # => '${installarchlib}/A/B.pm'

   $p5path = path_to_p5path($path, install_vars => [ qw(archlib sitelib vendorlib) ]);

   $path = p5path_to_path('${sitelib_stem}/X/Y/Z.pm'); # the same as "$Config{sitelib_stem}/X/Y/Z.pm"

   # translate your @INC
   for (@INC) {
           print "$_ -> ", path_to_p5path($_), "\n";
   }

DESCRIPTION

The Perl 5 configuration has a number of parameters which are library paths used for finding .pm, .pl and related files. For example, installarchlib and sitelib. These are used by the perl executable to build the @INC variable at script startup.

Module::Which is intented to find out information about installed modules, including path and version. To help Module::Which to provide sensible information, this module provides functions to express a path like /usr/lib/perl5/5.8.2/CPAN/Config.pm as ${installprivlib}/CPAN/Config.pm. Here such paths are called p5-paths and hence the name of the module.

By default, we consider the following Config variables:

   installarchlib archlib installprivlib privlib 
   installsitearch installsitelib sitelib sitelib_stem
   installvendorarch installvendorlib vendorlib vendorlib_stem

Some of these can be empty (undef, '', and so on) and some can hold the same value. For example, in a typical Windows installation, there are only two different paths, one for core libs and another for site libs. We deal with such cases by discarding empty variables and considering only the first variable in the same order shown above.

That is, in a Cygwin installation where the following configuration was found:

        installarchlib    = /usr/lib/perl5/5.8/cygwin
        archlib           = /usr/lib/perl5/5.8/cygwin
        installprivlib    = /usr/lib/perl5/5.8
        privlib           = /usr/lib/perl5/5.8
        installsitearch   = /usr/lib/perl5/site_perl/5.8/cygwin
        installsitelib    = /usr/lib/perl5/site_perl/5.8
        sitelib           = /usr/lib/perl5/site_perl/5.8
        sitelib_stem      = /usr/lib/perl5/site_perl/5.8
        installvendorarch = /usr/lib/perl5/vendor_perl/5.8/cygwin
        installvendorlib  = /usr/lib/perl5/vendor_perl/5.8
        vendorlib         = /usr/lib/perl5/vendor_perl/5.8
        vendorlib_stem    = /usr/lib/perl5/vendor_perl/5.8

only the following are used to resolve literal paths into p5-paths:

        installarchlib    = /usr/lib/perl5/5.8/cygwin
        installprivlib    = /usr/lib/perl5/5.8
        installsitearch   = /usr/lib/perl5/site_perl/5.8/cygwin
        installsitelib    = /usr/lib/perl5/site_perl/5.8
        installvendorarch = /usr/lib/perl5/vendor_perl/5.8/cygwin
        installvendorlib  = /usr/lib/perl5/vendor_perl/5.8

p5path_to_path

    $path = p5path_to_path($p5path)

Translates from p5-paths to ordinary paths. It is done by merely replacing the match of pattern /^\$\{(\w+)\}/ with $Config{$1}.

path_to_p5path

    $p5path = path_to_p5path($path)
        $p5path = path_to_p5path($path, install_vars => $arrayref)

Resolves an ordinary path to a p5-path. This is done by trying to match $Config{$ivar} to the start of the path for each $ivar on a list of Config variables (named installation variables due to their relation to Perl 5 installation paths). At the first match, it replaces the prefix with "\$\{$ivar\}".

The list of Config variables is given by the array ref given by option install_vars or by a reference to the package variable @Module::Which::P5Path::DEFAULT_IVARS which holds

   installarchlib archlib installprivlib privlib 
   installsitearch installsitelib sitelib sitelib_stem
   installvendorarch installvendorlib vendorlib vendorlib_stem

in this order.

This function is smart enough to discount case-tolerance of certain filesystems when trying to match a prefix to a path.

path_to_p5

        $p5path = path_to_p5($path)
        ($p5path, $p5base) = path_to_p5($path)

Works just like path_to_p5path but, in list context, returns also the p5-base. For example, given $Config{installarchlib} eq '/usr/local/lib/perl5',

    ($p5path, $p5base) = path_to_p5('/usr/local/lib/perl5/M.pm')

assigns '${installarchlib}/M.pm' to $p5path and '${installarchlib}/' to $p5base. Beware of this behavior when calling functions that are not prototyped and list operators.

    print "p5-path: ", path_to_p5('/usr/local/lib/perl5/M.pm'), "\n"

prints "p5-path: ${installarchlib}/M.pm${installarchlib}/" rather than "p5-path: ${installarchlib}/M.pm" that would be generated by

    print "p5-path: ", scalar path_to_p5('/usr/local/lib/perl5/M.pm'), "\n"