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

       Tim Jenness <tjenness@cpan.org>

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

perl v5.40.0                                       2024-11-22                              File::SearchPath(3pm)

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

       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.

       "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.

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

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

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

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