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