File::SearchPath(3pm)

💖 File::SearchPath 💖

okay so bestie, this is the manual page for the Perl module File::SearchPath, part of the User Contributed Perl Documentation. it's a tiny little module with one big job and honestly? it ate. let's get into it 🫶

---

🌸 NAME 🌸

File::SearchPath — search for a file in an environment variable path ✨

like, you've got a path-like env var. you want to find a file in it. that's the whole vibe.

---

🎀 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 gives you the ability to search a path-like environment variable for a file. and no, that file does not have to be an executable — it can be literally anything you want, it's giving range. 💅

---

✨ FUNCTIONS ✨

the following functions can be exported by this module. (yes, there's one. she's the main character. periodt.)

🌟 searchpath

this is the core function, the moment, the icon. the only mandatory argument is the name of a file to be located. that filename should not be absolute, though it can include directory specifications. iykyk.

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

if you only pass two arguments, it just assumes the second one is a path-like string. this interface exists purely for backwards compatibility with File::SearchPath version 0.01. it is not as portable as specifying the name of the environment variable, bestie. also note — when you call the subroutine this way, no specific attempt is made to check whether the file is executable. nope, none. 😭

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

by default, this searches $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 the dir option is specified, exe will always default to false. the way that works 💅
• 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 — that triggers a croak() on error. so like, pick a lane babe.
• subdir — if you know your file is in a subdirectory of the path described by the environment variable, you can specify that directory here. alternatively, you can just include the path in the file name itself. your call, both slay. ✨

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 an empty list) if no match could be found. no match, no vibes, it happens. 😭

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. legend behaviour fr fr 🫶

---

💜 NOTES 💜

if the Env::Path module is installed it will be used. this allows for more flexibility than simply assuming colon-separated paths. obsessed with a module that upgrades itself. 🌈

---

🌸 SEE ALSO 🌸

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

---

💅 AUTHOR 💅

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. (not me warning you about implied warranties, but like, it's in there. 💀)

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.

---

and that's the whole page bestie, no notes. 🎀

this was perl v5.40.0, dated 2024-11-22, and it lives in the File::SearchPath(3pm) manual. mwah. 💖✨🦋