1File::PathList(3)     User Contributed Perl Documentation    File::PathList(3)
2
3
4

NAME

6       File::PathList - Find a file within a set of paths (like @INC or Java
7       classpaths)
8

SYNOPSIS

10         # Create a basic pathset
11         my $inc  = File::PathList->new( \@INC );
12
13         # Again, but with more explicit params
14         my $inc2 = File::PathList->new(
15               paths => \@INC,
16               cache => 1,
17               );
18
19         # Get the full (localised) path for a unix-style relative path
20         my $file = "foo/bar/baz.txt";
21         my $path = $inc->find_file( $file );
22
23         if ( $path ) {
24             print "Found '$file' at '$path'\n";
25         } else {
26             print "Failed to find '$file'\n";
27         }
28

DESCRIPTION

30       Many systems that map generic relative paths to absolute paths do so
31       with a set of base paths.
32
33       For example, perl itself when loading classes first turn a
34       "Class::Name" into a path like "Class/Name.pm", and thens looks through
35       each element of @INC to find the actual file.
36
37       To aid in portability, all relative paths are provided as unix-style
38       relative paths, and converted to the localised version in the process
39       of looking up the path.
40

EXTENDING

42       The recommended method for extending "File::PathList" is to add
43       additional topic-specific find methods.
44
45       For example, a subclass that was attempting to duplicate the
46       functionality of perl's @INC and module location may wish to add a
47       "find_module" method.
48

METHODS

50   new \@path | param => $value, ...
51       The "new" constructor creates a new "File::PathList".
52
53       It takes the following options as key/value pairs.
54
55       paths
56           The compulsory "paths" param should be a reference to an "ARRAY" of
57           local filesystem paths.
58
59       cache
60           If the optional "cache" param is set to true, the object will
61           internally cache the results of the file lookups. (false by
62           default)
63
64       If the "new" contructor is provided only a single param, this will be
65       take to mean "paths =" $param>.
66
67       Returns a new "File::PathList" object, or "undef" if a valid path set
68       was not provided.
69
70   paths
71       The "paths" accessor returns the list of paths use to create the
72       "File::PathList" object.
73
74       Returns a list of localised path strings.
75
76   cache
77       The "cache" accessor indicates whether or not the "File::PathList"
78       object is caching the results of the file lookups.
79
80   find_file $unix_path
81       The "find_file" method takes a unix-style relative file path, and
82       iterates through the list of paths, checking for the file in it.
83
84       Returns the full path to the file, the false null string '' if the file
85       could not be found, or "undef" if passed a bad file name.
86

SUPPORT

88       Bugs should always be submitted via the CPAN bug tracker
89
90       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-PathList>
91
92       For other issues, contact the maintainer
93

AUTHOR

95       Adam Kennedy <adamk@cpan.org>
96

ACKNOWLEDGEMENTS

98       Thank you to Phase N (<http://phase-n.com/>) for permitting the open
99       sourcing and release of this distribution.
100

102       Copyright 2005 - 2008 Adam Kennedy.
103
104       This program is free software; you can redistribute it and/or modify it
105       under the same terms as Perl itself.
106
107       The full text of the license can be found in the LICENSE file included
108       with this module.
109
110
111
112perl v5.36.0                      2023-01-20                 File::PathList(3)
Impressum