File::SearchPath3pm

Usage

  use File::SearchPath qw/ searchpath /;
  $file = searchpath( 'libperl.a', env => 'LD_LIBRARY_PATH' );
  $file = searchpath( 'my.cfg', env => 'CFG_DIR', subdir => 'ME' );
  $path = searchpath( $file, env => 'PATH', exe => 1 );
  $path = searchpath( $file, env => 'PATH', dir => 1 );
  $file = searchpath( 'ls', $ENV{PATH} );
  $exe = searchpath( 'ls' );

Overview

This module provides the ability to search a path-like environment variable for a file (that does not necessarily have to be an executable).

Functions

The following functions can be exported by this module.

searchpath

This is the core function. The only mandatory argument is the name of a file to be located. The filename should not be absolute although it can include directory specifications.

  $path = searchpath( $file );
  @matches = searchpath( $file );

If only two arguments are provided, it is assumed that the second argument is a path-like string. This interface is provided for backwards compatibility with "File::SearchPath" version 0.01. It is not as portable as specifying the name of the environment variable. Note also that no specific attempt will be made to check whether the file is executable when the subroutine is called in this way.

  $path = searchpath( $file, $ENV{PATH} );

By default, this will search in $PATH for executable files and is equivalent to:

  $path = searchpath( $file, env => 'PATH', exe => 0 );

Hash-like options can be used to alter the behaviour of the search:

env

Name of the environment variable to use as a starting point for the search. Should be a path-like environment variable such as $PATH, $LD_LIBRARY_PATH etc. Defaults to $PATH. An error occurs if the environment variable is not set or not defined. If it is defined but contains a blank string, the current directory will be assumed.

exe

If true, only executable files will be located in the search path. If $PATH is being searched, the default is for this to be true. For all other environment variables the default is false. If "dir" option is specified "exe" will always default to false.

dir

If true, only directories will be located in the search path. Default is false. "dir" and "exe" are not allowed to be true in the same call. (triggering a croak() on error).

subdir

If you know that your file is in a subdirectory of the path described by the environment variable, this direcotry can be specified here. Alternatively, the path can be included in the file name itself.

In scalar context the first match is returned. In list context all matches are returned in the order corresponding to the directories listed in the environment variable.

Returns undef (or empty list) if no match could be found.

If an absolute file name is provided, that filename is returned if it exists and is readable, else undef is returned.

Notes

If "Env::Path" module is installed it will be used. This allows for more flexibility than simply assuming colon-separated paths.