File::PathList(3)

💖 File::PathList 💖

okay bestie, so this is a User Contributed Perl Documentation page, and honestly? It's giving "little utility module that quietly carries the whole ecosystem." It's File::PathList, and it does exactly one thing extremely well. Let's get into it 🫶

---

✨ NAME ✨

File::PathList — find a file within a set of paths, like @INC or Java classpaths. iykyk 💅

---

🌸 SYNOPSIS 🌸

# Create a basic pathset
my $inc  = File::PathList->new( \@INC );

# Again, but with more explicit params
my $inc2 = File::PathList->new(
      paths => \@INC,
      cache => 1,
      );

# Get the full (localised) path for a unix-style relative path
my $file = "foo/bar/baz.txt";
my $path = $inc->find_file( $file );

if ( $path ) {
    print "Found '$file' at '$path'\n";
} else {
    print "Failed to find '$file'\n";
}

look at that. clean. no notes. 🌈

---

🦋 DESCRIPTION 🦋

so basically, a bunch of systems out there need to take a generic relative path and turn it into a real absolute path, and they do that by searching through a whole set of base paths. it's a vibe.

for example (and this is the classic one), perl itself, when it's loading classes, first turns a "Class::Name" into a path like "Class/Name.pm", and then it goes through every single element of @INC to find the actual file. iconic behaviour honestly.

and to help with portability, every relative path you hand this thing is a unix-style relative path, and it gets converted to the localised version while it's doing the lookup. so you don't have to worry about it. she handles it. 💅

---

🧚 EXTENDING 🧚

the recommended way to extend File::PathList is to just... add more topic-specific find methods. that's it. that's the whole strategy. lowkey elegant.

like, say you've got a subclass that's trying to duplicate the functionality of perl's @INC and module location — you'd probably want to add a find_module method to it. slay ✨

---

👑 METHODS 👑

💜 new \@path | param => $value, ...

the new constructor creates a brand new File::PathList.

it takes the following options as key/value pairs.

• paths — the compulsory paths param should be a reference to an ARRAY of local filesystem paths. (compulsory, bestie. you gotta give it this one.)
• cache — if the optional cache param is set to true, the object will internally cache the results of the file lookups. it's false by default, so don't come for me if it's not caching.

and here's a lil shortcut for you: if the new constructor is given only a single param, that one param gets taken to mean paths = $param. easy.

Returns a new File::PathList object, or undef if a valid path set was not provided. (so like, check your return value, okay? 🙈)

💜 paths

the paths accessor returns the list of paths used to create the File::PathList object.

Returns a list of localised path strings. 🎀

💜 cache

the cache accessor tells you whether or not the File::PathList object is caching the results of the file lookups. just a lil vibe check on your own object.

💜 find_file $unix_path

the find_file method takes a unix-style relative file path and iterates through the list of paths, checking for the file in each one. one by one. she's thorough. 💖

Returns the full path to the file, the false null string '' if the file could not be found, or undef if you passed it a bad file name. three different outcomes, so like... read carefully before you if ($path). 😭

---

💀 SUPPORT 💀

bugs should always be submitted via the CPAN bug tracker:

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-PathList>

for other issues, contact the maintainer. 🫶

---

⭐ AUTHOR ⭐

Adam Kennedy <adamk@cpan.org>

---

🍓 ACKNOWLEDGEMENTS 🍓

thank you to Phase N (<http://phase-n.com/>) for permitting the open sourcing and release of this distribution. absolute legends. 👑

---

💜 COPYRIGHT 💜

Copyright 2005 - 2008 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

the full text of the license can be found in the LICENSE file included with this module. go read it, fr fr 📖

---

and that's the whole page, bestie!! 🎀 this was File::PathList, shipped as part of perl v5.42.0 and dated 2025-07-25. stay slay, stay localised, and may all your lookups find their file 💅✨🦋