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

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

           If a second argument is provided, it is assumed to be a path like variable. 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 => 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. 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.

HISTORY

       "File::SearchPath" used to exist on CPAN (now on backpan) and was written by Robert Spier.
       This version is completely new but retains an interface that is compatible with Robert's
       version. Thanks to Robert for allowing me to reuse this module name.

NOTES

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

SEE ALSO

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

AUTHOR

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

       Copyright (C) 2005,2006, 2008 Particle Physics and Astronomy Research Council.  Copyright
       (C) 2009-2010 Science and Technology Facilities 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