This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
remove support for running PathTools on MacOS
[perl5.git] / dist / PathTools / lib / File / Spec.pm
CommitLineData
270d1e39
GS
1package File::Spec;
2
270d1e39 3use strict;
270d1e39 4
9b568b53 5our $VERSION = '3.70';
4f642d62 6$VERSION =~ tr/_//d;
270d1e39 7
e229c0fe 8my %module = (
cbc7acb0
JD
9 MSWin32 => 'Win32',
10 os2 => 'OS2',
fa6a1c44 11 VMS => 'VMS',
ffa8448b 12 NetWare => 'Win32', # Yes, File::Spec::Win32 works on NetWare.
27da23d5 13 symbian => 'Win32', # Yes, File::Spec::Win32 works on symbian.
60598624 14 dos => 'OS2', # Yes, File::Spec::OS2 works on DJGPP.
36f66789
AB
15 cygwin => 'Cygwin',
16 amigaos => 'AmigaOS');
ecf68df6 17
cbc7acb0
JD
18
19my $module = $module{$^O} || 'Unix';
ecf68df6 20
cbc7acb0 21require "File/Spec/$module.pm";
1a58b39a 22our @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
110c90cc 85X<canonpath>
ae1c33a1
RK
86
87No physical check on the filesystem, but a logical cleanup of a
88path.
89
90 $cpath = File::Spec->canonpath( $path ) ;
91
60598624
RGS
92Note that this does *not* collapse F<x/../y> sections into F<y>. This
93is by design. If F</foo> on your system is a symlink to F</bar/baz>,
94then F</foo/../quux> is actually F</bar/quux>, not F</quux> as a naive
95F<../>-removal would give you. If you want to do this kind of
96processing, you probably want C<Cwd>'s C<realpath()> function to
97actually traverse the filesystem cleaning up paths like this.
98
5813de03 99=item catdir
110c90cc 100X<catdir>
ae1c33a1
RK
101
102Concatenate two or more directory names to form a complete path ending
103with a directory. But remove the trailing slash from the resulting
104string, because it doesn't look good, isn't necessary and confuses
5b287435 105OS/2. Of course, if this is the root directory, don't cut off the
ae1c33a1
RK
106trailing slash :-)
107
108 $path = File::Spec->catdir( @directories );
109
110=item catfile
110c90cc 111X<catfile>
ae1c33a1
RK
112
113Concatenate one or more directory names and a filename to form a
114complete path ending with a filename
115
116 $path = File::Spec->catfile( @directories, $filename );
117
118=item curdir
110c90cc 119X<curdir>
ae1c33a1
RK
120
121Returns a string representation of the current directory.
122
123 $curdir = File::Spec->curdir();
124
125=item devnull
110c90cc 126X<devnull>
ae1c33a1
RK
127
128Returns a string representation of the null device.
129
130 $devnull = File::Spec->devnull();
131
132=item rootdir
110c90cc 133X<rootdir>
ae1c33a1
RK
134
135Returns a string representation of the root directory.
136
137 $rootdir = File::Spec->rootdir();
138
139=item tmpdir
110c90cc 140X<tmpdir>
ae1c33a1
RK
141
142Returns a string representation of the first writable directory from a
07824bd1
JH
143list of possible temporary directories. Returns the current directory
144if no writable temporary directories are found. The list of directories
5b287435
RGS
145checked depends on the platform; e.g. File::Spec::Unix checks C<$ENV{TMPDIR}>
146(unless taint is on) and F</tmp>.
ae1c33a1
RK
147
148 $tmpdir = File::Spec->tmpdir();
149
150=item updir
110c90cc 151X<updir>
ae1c33a1
RK
152
153Returns a string representation of the parent directory.
154
155 $updir = File::Spec->updir();
156
157=item no_upwards
158
daa60504
DG
159Given a list of files in a directory (such as from C<readdir()>),
160strip out C<'.'> and C<'..'>.
ae1c33a1 161
daa60504
DG
162B<SECURITY NOTE:> This does NOT filter paths containing C<'..'>, like
163C<'../../../../etc/passwd'>, only literal matches to C<'.'> and C<'..'>.
164
165 @paths = File::Spec->no_upwards( readdir $dirhandle );
ae1c33a1
RK
166
167=item case_tolerant
168
169Returns a true or false value indicating, respectively, that alphabetic
5b287435 170case is not or is significant when comparing file specifications.
8e58c70c 171Cygwin and Win32 accept an optional drive argument.
ae1c33a1
RK
172
173 $is_case_tolerant = File::Spec->case_tolerant();
174
175=item file_name_is_absolute
176
5b287435 177Takes as its argument a path, and returns true if it is an absolute path.
ae1c33a1
RK
178
179 $is_absolute = File::Spec->file_name_is_absolute( $path );
180
2586ba89
JH
181This does not consult the local filesystem on Unix, Win32, OS/2, or
182Mac OS (Classic). It does consult the working environment for VMS
183(see L<File::Spec::VMS/file_name_is_absolute>).
ae1c33a1
RK
184
185=item path
110c90cc 186X<path>
ae1c33a1 187
5b287435 188Takes no argument. Returns the environment variable C<PATH> (or the local
638113eb 189platform's equivalent) as a list.
ae1c33a1
RK
190
191 @PATH = File::Spec->path();
192
193=item join
110c90cc 194X<join, path>
ae1c33a1
RK
195
196join is the same as catfile.
197
198=item splitpath
110c90cc 199X<splitpath> X<split, path>
ae1c33a1
RK
200
201Splits a path in to volume, directory, and filename portions. On systems
40d020d9 202with no concept of volume, returns '' for volume.
ae1c33a1 203
2674d7ed
FC
204 ($volume,$directories,$file) =
205 File::Spec->splitpath( $path );
206 ($volume,$directories,$file) =
207 File::Spec->splitpath( $path, $no_file );
ae1c33a1
RK
208
209For systems with no syntax differentiating filenames from directories,
5b287435
RGS
210assumes that the last file is a path unless C<$no_file> is true or a
211trailing separator or F</.> or F</..> is present. On Unix, this means that C<$no_file>
ae1c33a1
RK
212true makes this return ( '', $path, '' ).
213
214The directory portion may or may not be returned with a trailing '/'.
215
216The results can be passed to L</catpath()> to get back a path equivalent to
217(usually identical to) the original path.
218
219=item splitdir
110c90cc 220X<splitdir> X<split, dir>
ae1c33a1 221
2a6dc374 222The opposite of L</catdir>.
ae1c33a1
RK
223
224 @dirs = File::Spec->splitdir( $directories );
225
5b287435 226C<$directories> must be only the directory portion of the path on systems
ae1c33a1
RK
227that have the concept of a volume or that have path syntax that differentiates
228files from directories.
229
230Unlike just splitting the directories on the separator, empty
231directory names (C<''>) can be returned, because these are significant
5b287435 232on some OSes.
ae1c33a1 233
59605c55 234=item catpath()
ae1c33a1
RK
235
236Takes volume, directory and file portions and returns an entire path. Under
5b287435
RGS
237Unix, C<$volume> is ignored, and directory and file are concatenated. A '/' is
238inserted if need be. On other OSes, C<$volume> is significant.
ae1c33a1
RK
239
240 $full_path = File::Spec->catpath( $volume, $directory, $file );
241
242=item abs2rel
110c90cc 243X<abs2rel> X<absolute, path> X<relative, path>
ae1c33a1
RK
244
245Takes a destination path and an optional base path returns a relative path
246from the base path to the destination path:
247
248 $rel_path = File::Spec->abs2rel( $path ) ;
249 $rel_path = File::Spec->abs2rel( $path, $base ) ;
250
23bb49fa 251If C<$base> is not present or '', then L<Cwd::cwd()|Cwd> is used. If C<$base> is
8d48b1f5
JH
252relative, then it is converted to absolute form using
253L</rel2abs()>. This means that it is taken to be relative to
23bb49fa 254L<Cwd::cwd()|Cwd>.
8d48b1f5 255
5b287435 256On systems with the concept of volume, if C<$path> and C<$base> appear to be
638113eb 257on two different volumes, we will not attempt to resolve the two
5b287435
RGS
258paths, and we will instead simply return C<$path>. Note that previous
259versions of this module ignored the volume of C<$base>, which resulted in
638113eb 260garbage results part of the time.
ae1c33a1
RK
261
262On systems that have a grammar that indicates filenames, this ignores the
5b287435 263C<$base> filename as well. Otherwise all path components are assumed to be
ae1c33a1
RK
264directories.
265
5b287435 266If C<$path> is relative, it is converted to absolute form using L</rel2abs()>.
23bb49fa 267This means that it is taken to be relative to L<Cwd::cwd()|Cwd>.
ae1c33a1 268
2586ba89 269No checks against the filesystem are made. On VMS, there is
ae1c33a1
RK
270interaction with the working environment, as logicals and
271macros are expanded.
272
273Based on code written by Shigio Yamaguchi.
274
59605c55 275=item rel2abs()
110c90cc 276X<rel2abs> X<absolute, path> X<relative, path>
ae1c33a1
RK
277
278Converts a relative path to an absolute path.
279
280 $abs_path = File::Spec->rel2abs( $path ) ;
281 $abs_path = File::Spec->rel2abs( $path, $base ) ;
282
23bb49fa 283If C<$base> is not present or '', then L<Cwd::cwd()|Cwd> is used. If C<$base> is relative,
ae1c33a1 284then it is converted to absolute form using L</rel2abs()>. This means that it
23bb49fa 285is taken to be relative to L<Cwd::cwd()|Cwd>.
ae1c33a1 286
5b287435 287On systems with the concept of volume, if C<$path> and C<$base> appear to be
638113eb 288on two different volumes, we will not attempt to resolve the two
5b287435
RGS
289paths, and we will instead simply return C<$path>. Note that previous
290versions of this module ignored the volume of C<$base>, which resulted in
638113eb 291garbage results part of the time.
ae1c33a1
RK
292
293On systems that have a grammar that indicates filenames, this ignores the
5b287435 294C<$base> filename as well. Otherwise all path components are assumed to be
ae1c33a1
RK
295directories.
296
2a6dc374 297If C<$path> is absolute, it is cleaned up and returned using L</canonpath>.
ae1c33a1 298
2586ba89 299No checks against the filesystem are made. On VMS, there is
ae1c33a1
RK
300interaction with the working environment, as logicals and
301macros are expanded.
302
303Based on code written by Shigio Yamaguchi.
304
305=back
306
307For further information, please see L<File::Spec::Unix>,
308L<File::Spec::Mac>, L<File::Spec::OS2>, L<File::Spec::Win32>, or
309L<File::Spec::VMS>.
270d1e39
GS
310
311=head1 SEE ALSO
312
ae1c33a1
RK
313L<File::Spec::Unix>, L<File::Spec::Mac>, L<File::Spec::OS2>,
314L<File::Spec::Win32>, L<File::Spec::VMS>, L<File::Spec::Functions>,
315L<ExtUtils::MakeMaker>
270d1e39 316
5b287435
RGS
317=head1 AUTHOR
318
319Currently maintained by Ken Williams C<< <KWILLIAMS@cpan.org> >>.
320
321The vast majority of the code was written by
322Kenneth Albanowski C<< <kjahds@kjahds.com> >>,
323Andy Dougherty C<< <doughera@lafayette.edu> >>,
324Andreas KE<ouml>nig C<< <A.Koenig@franz.ww.TU-Berlin.DE> >>,
325Tim Bunce C<< <Tim.Bunce@ig.co.uk> >>.
326VMS support by Charles Bailey C<< <bailey@newman.upenn.edu> >>.
327OS/2 support by Ilya Zakharevich C<< <ilya@math.ohio-state.edu> >>.
328Mac support by Paul Schinder C<< <schinder@pobox.com> >>, and
329Thomas Wegner C<< <wegner_thomas@yahoo.com> >>.
330abs2rel() and rel2abs() written by Shigio Yamaguchi C<< <shigio@tamacom.com> >>,
331modified by Barrie Slaymaker C<< <barries@slaysys.com> >>.
332splitpath(), splitdir(), catpath() and catdir() by Barrie Slaymaker.
e021ab8e 333
99f36a73
RGS
334=head1 COPYRIGHT
335
d10039d7 336Copyright (c) 2004-2013 by the Perl 5 Porters. All rights reserved.
99f36a73
RGS
337
338This program is free software; you can redistribute it and/or modify
339it under the same terms as Perl itself.
340
e021ab8e 341=cut