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