NAME

File::SearchPath - Search for a file in an environment variable path

SYNOPSIS

use File::SearchPath qw/ searchpath /;

$file = searchpath( 'libperl.a', env => 'LD_LIBRARY_PATH' );

$exe = searchpath( 'ls' );

DESCRIPTION

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 );

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

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

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.

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. Alterntaively, 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.

WHY?

There are many modules that search for an executable in the path but I couldn't find any that would also search for a non-executable file in a path-like environment variable. Yes, File::Find would work but I'm doing this a lot so I wanted to replace the unneeded complexity of File::Find with something more targetted.

SEE ALSO

Env::Path, File::Which, File::Find, File::Find::Run, File::Where.

AUTHOR

Tim Jenness <t.jenness@jach.hawaii.edu>

Copyright 2005 Particle Physics and Astronomy Research Council. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA