/ 
Dir-Which-0.3
River stage one • 1 direct dependent • 1 total dependent
/ Dir::Which

NAME

Dir::Which - Search for directory entries in a list of directories.

SYNOPSIS

use Dir::Which qw/ which /;

@entries = which(
             -entry => "myprog.conf", 
             -env => "myprog_path", 
             -defaultpath => ".:".$FindBin::Bin.":/etc:/usr/local/etc") ;

DESCRIPTION

This module searches directory entries (files, dirs, links, named pipes...) in a list of directories specified as a path-like string.

The path string can be specified in an environment variable or as an argument.

EXPORT

which

FUNCTION

which

This fonction takes named arguments :

-entry (mandatory)

The name of the searched entry.

-env (optional)

The name of a environment variable supposed to be a path-like string, and which be used to search the specified entry. If one or more entries are found in this path, the search ends and returns these values.

-defaultpath (optional)

The path used to search the specified entry, if -env argument is missing, or if this environment variable doesn't exist, or if no entry have been found in it.

RETURN VALUE

In scalar context, the first match is returned according to the order of the directories listed in the path string, or undef if no match can be found.

In list context, all matches are returned in the order corresponding to the directories listed in the path string (and so an empty list if no match is found).

EXAMPLES

use Dir::Which qw/ which /;

$file = which(
             -entry => "myprog.conf", 
             -defaultpath => "/etc:/usr/local/etc"
        ) ;

Searches the absolute name of myprog.conf successivement in the directories /etc and /usr/local/etc. Returns the first entry found.

use Dir::Which qw/ which /;
use FindBin qw($Bin) ;

@entries = which(
             -entry => "myprog.d", 
             -defaultpath => ".:".$FindBin::Bin.":/etc:/usr/local/etc"
           ) ;

Returns the absolute names of myprog.d searched in the current directory, the directory which contains the program binary, /etc and /usr/local/etc.

use Dir::Which qw/ which /;

$file = which(
             -entry => "myprog.conf", 
             -env => "myprog_path"
        ) ;

Searches the absolute name of myprog.conf in the path stored in the environment variable myprog_path. Returns the name of the first file found, or undef if no entry found.

use Dir::Which qw/ which /;
use FindBin qw($Bin) ;

$file = which(
             -entry => "myprog.conf", 
             -env => "myprog_path", 
             -defaultpath => ".:".$FindBin::Bin.":/etc:/usr/local/etc"
        ) ;

Searches the absolute name of myprog.conf in the path stored in the environment variable myprog_path. If no file has been found, searches successivement in the current directory, the directory which contains the program binary, /etc and /usr/local/etc. Returns the name of the first entry found, or undef if no entry found.

NOTES

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

SEE ALSO

File::SearchPath, FindBin, Env::Path, File::Which.

AUTHOR

Jacquelin Charbonnel, <jacquelin.charbonnel at math.cnrs.fr>

BUGS

Please report any bugs or feature requests to bug-dir-which at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dir-Which. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Dir::Which

You can also look for information at:

ACKNOWLEDGEMENTS

Dir::Which is inspired by File::SearchPath written by Tim Jenness. Thanks to Tim for allowing me to reuse his idea.

COPYRIGHT & LICENSE

Copyright Jacquelin Charbonnel <jacquelin.charbonnel at math.cnrs.fr>

This software is governed by the CeCILL-C license under French law and abiding by the rules of distribution of free software. You can use, modify and/ or redistribute the software under the terms of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following URL "http://www.cecill.info".

As a counterpart to the access to the source code and rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software's author, the holder of the economic rights, and the successive licensors have only limited liability.

In this respect, the user's attention is drawn to the risks associated with loading, using, modifying and/or developing or reproducing the software by the user in light of its specific status of free software, that may mean that it is complicated to manipulate, and that also therefore means that it is reserved for developers and experienced professionals having in-depth computer knowledge. Users are therefore encouraged to load and test the software's suitability as regards their requirements in conditions enabling the security of their systems and/or data to be ensured and, more generally, to use and operate it in the same conditions as regards security.

The fact that you are presently reading this means that you have had knowledge of the CeCILL-C license and that you accept its terms.