This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to Pod::LaTeX 0.58
[perl5.git] / lib / File / Spec.pm
CommitLineData
270d1e39
GS
1package File::Spec;
2
270d1e39 3use strict;
07824bd1 4use vars qw(@ISA $VERSION);
270d1e39 5
21f4e7e5 6$VERSION = '3.01';
5b287435 7$VERSION = eval $VERSION;
270d1e39 8
cbc7acb0
JD
9my %module = (MacOS => 'Mac',
10 MSWin32 => 'Win32',
11 os2 => 'OS2',
fa6a1c44 12 VMS => 'VMS',
ecf68df6 13 epoc => 'Epoc',
ffa8448b 14 NetWare => 'Win32', # Yes, File::Spec::Win32 works on NetWare.
d835d330 15 dos => 'OS2', # Yes, File::Spec::OS2 works on DJGPP.
ecf68df6
DR
16 cygwin => 'Cygwin');
17
cbc7acb0
JD
18
19my $module = $module{$^O} || 'Unix';
ecf68df6 20
cbc7acb0
JD
21require "File/Spec/$module.pm";
22@ISA = ("File::Spec::$module");
270d1e39
GS
23
241;
ae1c33a1 25
270d1e39
GS
26__END__
27
28=head1 NAME
29
30File::Spec - portably perform operations on file names
31
32=head1 SYNOPSIS
33
5c609535 34 use File::Spec;
270d1e39 35
5c609535 36 $x=File::Spec->catfile('a', 'b', 'c');
270d1e39 37
5c609535
JD
38which returns 'a/b/c' under Unix. Or:
39
40 use File::Spec::Functions;
41
42 $x = catfile('a', 'b', 'c');
270d1e39
GS
43
44=head1 DESCRIPTION
45
46This module is designed to support operations commonly performed on file
47specifications (usually called "file names", but not to be confused with the
48contents of a file, or Perl's file handles), such as concatenating several
49directory and file names into a single path, or determining whether a path
50is rooted. It is based on code directly taken from MakeMaker 5.17, code
51written by Andreas KE<ouml>nig, Andy Dougherty, Charles Bailey, Ilya
52Zakharevich, Paul Schinder, and others.
53
54Since these functions are different for most operating systems, each set of
55OS specific routines is available in a separate module, including:
56
57 File::Spec::Unix
58 File::Spec::Mac
59 File::Spec::OS2
60 File::Spec::Win32
61 File::Spec::VMS
62
63The module appropriate for the current OS is automatically loaded by
5c609535
JD
64File::Spec. Since some modules (like VMS) make use of facilities available
65only under that OS, it may not be possible to load all modules under all
66operating systems.
270d1e39 67
2586ba89 68Since File::Spec is object oriented, subroutines should not be called directly,
270d1e39
GS
69as in:
70
71 File::Spec::catfile('a','b');
5c609535 72
270d1e39
GS
73but rather as class methods:
74
75 File::Spec->catfile('a','b');
76
5c609535
JD
77For simple uses, L<File::Spec::Functions> provides convenient functional
78forms of these methods.
79
ae1c33a1
RK
80=head1 METHODS
81
82=over 2
83
5813de03 84=item canonpath
ae1c33a1
RK
85
86No physical check on the filesystem, but a logical cleanup of a
87path.
88
89 $cpath = File::Spec->canonpath( $path ) ;
90
5813de03 91=item catdir
ae1c33a1
RK
92
93Concatenate two or more directory names to form a complete path ending
94with a directory. But remove the trailing slash from the resulting
95string, because it doesn't look good, isn't necessary and confuses
5b287435 96OS/2. Of course, if this is the root directory, don't cut off the
ae1c33a1
RK
97trailing slash :-)
98
99 $path = File::Spec->catdir( @directories );
100
101=item catfile
102
103Concatenate one or more directory names and a filename to form a
104complete path ending with a filename
105
106 $path = File::Spec->catfile( @directories, $filename );
107
108=item curdir
109
110Returns a string representation of the current directory.
111
112 $curdir = File::Spec->curdir();
113
114=item devnull
115
116Returns a string representation of the null device.
117
118 $devnull = File::Spec->devnull();
119
120=item rootdir
121
122Returns a string representation of the root directory.
123
124 $rootdir = File::Spec->rootdir();
125
126=item tmpdir
127
128Returns a string representation of the first writable directory from a
07824bd1
JH
129list of possible temporary directories. Returns the current directory
130if no writable temporary directories are found. The list of directories
5b287435
RGS
131checked depends on the platform; e.g. File::Spec::Unix checks C<$ENV{TMPDIR}>
132(unless taint is on) and F</tmp>.
ae1c33a1
RK
133
134 $tmpdir = File::Spec->tmpdir();
135
136=item updir
137
138Returns a string representation of the parent directory.
139
140 $updir = File::Spec->updir();
141
142=item no_upwards
143
144Given a list of file names, strip out those that refer to a parent
145directory. (Does not strip symlinks, only '.', '..', and equivalents.)
146
147 @paths = File::Spec->no_upwards( @paths );
148
149=item case_tolerant
150
151Returns a true or false value indicating, respectively, that alphabetic
5b287435 152case is not or is significant when comparing file specifications.
ae1c33a1
RK
153
154 $is_case_tolerant = File::Spec->case_tolerant();
155
156=item file_name_is_absolute
157
5b287435 158Takes as its argument a path, and returns true if it is an absolute path.
ae1c33a1
RK
159
160 $is_absolute = File::Spec->file_name_is_absolute( $path );
161
2586ba89
JH
162This does not consult the local filesystem on Unix, Win32, OS/2, or
163Mac OS (Classic). It does consult the working environment for VMS
164(see L<File::Spec::VMS/file_name_is_absolute>).
ae1c33a1
RK
165
166=item path
167
5b287435 168Takes no argument. Returns the environment variable C<PATH> (or the local
638113eb 169platform's equivalent) as a list.
ae1c33a1
RK
170
171 @PATH = File::Spec->path();
172
173=item join
174
175join is the same as catfile.
176
177=item splitpath
178
179Splits a path in to volume, directory, and filename portions. On systems
40d020d9 180with no concept of volume, returns '' for volume.
ae1c33a1
RK
181
182 ($volume,$directories,$file) = File::Spec->splitpath( $path );
183 ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );
184
185For systems with no syntax differentiating filenames from directories,
5b287435
RGS
186assumes that the last file is a path unless C<$no_file> is true or a
187trailing separator or F</.> or F</..> is present. On Unix, this means that C<$no_file>
ae1c33a1
RK
188true makes this return ( '', $path, '' ).
189
190The directory portion may or may not be returned with a trailing '/'.
191
192The results can be passed to L</catpath()> to get back a path equivalent to
193(usually identical to) the original path.
194
195=item splitdir
196
197The opposite of L</catdir()>.
198
199 @dirs = File::Spec->splitdir( $directories );
200
5b287435 201C<$directories> must be only the directory portion of the path on systems
ae1c33a1
RK
202that have the concept of a volume or that have path syntax that differentiates
203files from directories.
204
205Unlike just splitting the directories on the separator, empty
206directory names (C<''>) can be returned, because these are significant
5b287435 207on some OSes.
ae1c33a1 208
59605c55 209=item catpath()
ae1c33a1
RK
210
211Takes volume, directory and file portions and returns an entire path. Under
5b287435
RGS
212Unix, C<$volume> is ignored, and directory and file are concatenated. A '/' is
213inserted if need be. On other OSes, C<$volume> is significant.
ae1c33a1
RK
214
215 $full_path = File::Spec->catpath( $volume, $directory, $file );
216
217=item abs2rel
218
219Takes a destination path and an optional base path returns a relative path
220from the base path to the destination path:
221
222 $rel_path = File::Spec->abs2rel( $path ) ;
223 $rel_path = File::Spec->abs2rel( $path, $base ) ;
224
5b287435 225If C<$base> is not present or '', then L<cwd()|Cwd> is used. If C<$base> is
8d48b1f5
JH
226relative, then it is converted to absolute form using
227L</rel2abs()>. This means that it is taken to be relative to
228L<cwd()|Cwd>.
229
5b287435 230On systems with the concept of volume, if C<$path> and C<$base> appear to be
638113eb 231on two different volumes, we will not attempt to resolve the two
5b287435
RGS
232paths, and we will instead simply return C<$path>. Note that previous
233versions of this module ignored the volume of C<$base>, which resulted in
638113eb 234garbage results part of the time.
ae1c33a1
RK
235
236On systems that have a grammar that indicates filenames, this ignores the
5b287435 237C<$base> filename as well. Otherwise all path components are assumed to be
ae1c33a1
RK
238directories.
239
5b287435 240If C<$path> is relative, it is converted to absolute form using L</rel2abs()>.
59605c55 241This means that it is taken to be relative to L<cwd()|Cwd>.
ae1c33a1 242
2586ba89 243No checks against the filesystem are made. On VMS, there is
ae1c33a1
RK
244interaction with the working environment, as logicals and
245macros are expanded.
246
247Based on code written by Shigio Yamaguchi.
248
59605c55 249=item rel2abs()
ae1c33a1
RK
250
251Converts a relative path to an absolute path.
252
253 $abs_path = File::Spec->rel2abs( $path ) ;
254 $abs_path = File::Spec->rel2abs( $path, $base ) ;
255
5b287435 256If C<$base> is not present or '', then L<cwd()|Cwd> is used. If C<$base> is relative,
ae1c33a1 257then it is converted to absolute form using L</rel2abs()>. This means that it
59605c55 258is taken to be relative to L<cwd()|Cwd>.
ae1c33a1 259
5b287435 260On systems with the concept of volume, if C<$path> and C<$base> appear to be
638113eb 261on two different volumes, we will not attempt to resolve the two
5b287435
RGS
262paths, and we will instead simply return C<$path>. Note that previous
263versions of this module ignored the volume of C<$base>, which resulted in
638113eb 264garbage results part of the time.
ae1c33a1
RK
265
266On systems that have a grammar that indicates filenames, this ignores the
5b287435 267C<$base> filename as well. Otherwise all path components are assumed to be
ae1c33a1
RK
268directories.
269
5b287435 270If C<$path> is absolute, it is cleaned up and returned using L</canonpath()>.
ae1c33a1 271
2586ba89 272No checks against the filesystem are made. On VMS, there is
ae1c33a1
RK
273interaction with the working environment, as logicals and
274macros are expanded.
275
276Based on code written by Shigio Yamaguchi.
277
278=back
279
280For further information, please see L<File::Spec::Unix>,
281L<File::Spec::Mac>, L<File::Spec::OS2>, L<File::Spec::Win32>, or
282L<File::Spec::VMS>.
270d1e39
GS
283
284=head1 SEE ALSO
285
ae1c33a1
RK
286L<File::Spec::Unix>, L<File::Spec::Mac>, L<File::Spec::OS2>,
287L<File::Spec::Win32>, L<File::Spec::VMS>, L<File::Spec::Functions>,
288L<ExtUtils::MakeMaker>
270d1e39 289
5b287435
RGS
290=head1 AUTHOR
291
292Currently maintained by Ken Williams C<< <KWILLIAMS@cpan.org> >>.
293
294The vast majority of the code was written by
295Kenneth Albanowski C<< <kjahds@kjahds.com> >>,
296Andy Dougherty C<< <doughera@lafayette.edu> >>,
297Andreas KE<ouml>nig C<< <A.Koenig@franz.ww.TU-Berlin.DE> >>,
298Tim Bunce C<< <Tim.Bunce@ig.co.uk> >>.
299VMS support by Charles Bailey C<< <bailey@newman.upenn.edu> >>.
300OS/2 support by Ilya Zakharevich C<< <ilya@math.ohio-state.edu> >>.
301Mac support by Paul Schinder C<< <schinder@pobox.com> >>, and
302Thomas Wegner C<< <wegner_thomas@yahoo.com> >>.
303abs2rel() and rel2abs() written by Shigio Yamaguchi C<< <shigio@tamacom.com> >>,
304modified by Barrie Slaymaker C<< <barries@slaysys.com> >>.
305splitpath(), splitdir(), catpath() and catdir() by Barrie Slaymaker.
e021ab8e
JH
306
307=cut