File::PathList - Find a file within a set of paths (like @INC or Java classpaths)
# 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"; }
Many systems that map generic relative paths to absolute paths do so with a set of base paths.
For example, perl itself when loading classes first turn a Class::Name into a path like Class/Name.pm, and thens looks through each element of @INC to find the actual file.
Class::Name
Class/Name.pm
@INC
To aid in portability, all relative paths are provided as unix-style relative paths, and converted to the localised version in the process of looking up the path.
The recommended method for extending File::PathList is to add additional topic-specific find methods.
File::PathList
For example, a subclass that was attempting to duplicate the functionality of perl's @INC and module location may wish to add a find_module method.
find_module
The new constructor creates a new File::PathList.
new
It takes the following options as key/value pairs.
The compulsory paths param should be a reference to an ARRAY of local filesystem paths.
paths
ARRAY
If the optional cache param is set to true, the object will internally cache the results of the file lookups. (false by default)
cache
If the new contructor is provided only a single param, this will be take to mean paths = $param>.
paths =
Returns a new File::PathList object, or undef if a valid path set was not provided.
undef
The paths accessor returns the list of paths use to create the File::PathList object.
Returns a list of localised path strings.
The cache accessor indicates whether or not the File::PathList object is caching the results of the file lookups.
The find_file method takes a unix-style relative file path, and iterates through the list of paths, checking for the file in it.
find_file
Returns the full path to the file, the false null string '' if the file could not be found, or undef if passed a bad file name.
''
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
Adam Kennedy <adamk@cpan.org>
Thank you to Phase N (http://phase-n.com/) for permitting the open sourcing and release of this distribution.
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.
To install File::PathList, copy and paste the appropriate command in to your terminal.
cpanm
cpanm File::PathList
CPAN shell
perl -MCPAN -e shell install File::PathList
For more information on module installation, please visit the detailed CPAN module installation guide.