This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: [perl #30783] Test::Builder does not handle overloaded "name" values
[perl5.git] / lib / File / Spec.pm
CommitLineData
270d1e39
GS
1package File::Spec;
2
270d1e39 3use strict;
07824bd1 4use vars qw(@ISA $VERSION);
270d1e39 5
4fdb5a70 6$VERSION = '0.87';
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
638113eb
JH
167Takes no argument, returns the environment variable PATH (or the local
168platform's equivalent) as a list.
ae1c33a1
RK
169
170 @PATH = File::Spec->path();
171
172=item join
173
174join is the same as catfile.
175
176=item splitpath
177
178Splits a path in to volume, directory, and filename portions. On systems
40d020d9 179with no concept of volume, returns '' for volume.
ae1c33a1
RK
180
181 ($volume,$directories,$file) = File::Spec->splitpath( $path );
182 ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );
183
184For systems with no syntax differentiating filenames from directories,
185assumes that the last file is a path unless $no_file is true or a
186trailing separator or /. or /.. is present. On Unix this means that $no_file
187true makes this return ( '', $path, '' ).
188
189The directory portion may or may not be returned with a trailing '/'.
190
191The results can be passed to L</catpath()> to get back a path equivalent to
192(usually identical to) the original path.
193
194=item splitdir
195
196The opposite of L</catdir()>.
197
198 @dirs = File::Spec->splitdir( $directories );
199
200$directories must be only the directory portion of the path on systems
201that have the concept of a volume or that have path syntax that differentiates
202files from directories.
203
204Unlike just splitting the directories on the separator, empty
205directory names (C<''>) can be returned, because these are significant
2586ba89 206on some OSs.
ae1c33a1 207
59605c55 208=item catpath()
ae1c33a1
RK
209
210Takes volume, directory and file portions and returns an entire path. Under
3099fc99 211Unix, $volume is ignored, and directory and file are concatenated. A '/' is
ae1c33a1
RK
212inserted if need be. On other OSs, $volume is significant.
213
214 $full_path = File::Spec->catpath( $volume, $directory, $file );
215
216=item abs2rel
217
218Takes a destination path and an optional base path returns a relative path
219from the base path to the destination path:
220
221 $rel_path = File::Spec->abs2rel( $path ) ;
222 $rel_path = File::Spec->abs2rel( $path, $base ) ;
223
8d48b1f5
JH
224If $base is not present or '', then L<cwd()|Cwd> is used. If $base is
225relative, then it is converted to absolute form using
226L</rel2abs()>. This means that it is taken to be relative to
227L<cwd()|Cwd>.
228
638113eb
JH
229On systems with the concept of volume, if $path and $base appear to be
230on two different volumes, we will not attempt to resolve the two
231paths, and we will instead simply return $path. Note that previous
232versions of this module ignored the volume of $base, which resulted in
233garbage results part of the time.
ae1c33a1
RK
234
235On systems that have a grammar that indicates filenames, this ignores the
236$base filename as well. Otherwise all path components are assumed to be
237directories.
238
239If $path is relative, it is converted to absolute form using L</rel2abs()>.
59605c55 240This means that it is taken to be relative to L<cwd()|Cwd>.
ae1c33a1 241
2586ba89 242No checks against the filesystem are made. On VMS, there is
ae1c33a1
RK
243interaction with the working environment, as logicals and
244macros are expanded.
245
246Based on code written by Shigio Yamaguchi.
247
59605c55 248=item rel2abs()
ae1c33a1
RK
249
250Converts a relative path to an absolute path.
251
252 $abs_path = File::Spec->rel2abs( $path ) ;
253 $abs_path = File::Spec->rel2abs( $path, $base ) ;
254
59605c55 255If $base is not present or '', then L<cwd()|Cwd> is used. If $base is relative,
ae1c33a1 256then it is converted to absolute form using L</rel2abs()>. This means that it
59605c55 257is taken to be relative to L<cwd()|Cwd>.
ae1c33a1 258
638113eb
JH
259On systems with the concept of volume, if $path and $base appear to be
260on two different volumes, we will not attempt to resolve the two
261paths, and we will instead simply return $path. Note that previous
262versions of this module ignored the volume of $base, which resulted in
263garbage results part of the time.
ae1c33a1
RK
264
265On systems that have a grammar that indicates filenames, this ignores the
266$base filename as well. Otherwise all path components are assumed to be
267directories.
268
269If $path is absolute, it is cleaned up and returned using L</canonpath()>.
270
2586ba89 271No checks against the filesystem are made. On VMS, there is
ae1c33a1
RK
272interaction with the working environment, as logicals and
273macros are expanded.
274
275Based on code written by Shigio Yamaguchi.
276
277=back
278
279For further information, please see L<File::Spec::Unix>,
280L<File::Spec::Mac>, L<File::Spec::OS2>, L<File::Spec::Win32>, or
281L<File::Spec::VMS>.
270d1e39
GS
282
283=head1 SEE ALSO
284
ae1c33a1
RK
285L<File::Spec::Unix>, L<File::Spec::Mac>, L<File::Spec::OS2>,
286L<File::Spec::Win32>, L<File::Spec::VMS>, L<File::Spec::Functions>,
287L<ExtUtils::MakeMaker>
270d1e39
GS
288
289=head1 AUTHORS
290
ae1c33a1 291Kenneth Albanowski <kjahds@kjahds.com>, Andy Dougherty
36816da2 292<doughera@lafayette.edu>, Andreas KE<ouml>nig
2586ba89
JH
293<A.Koenig@franz.ww.TU-Berlin.DE>, Tim Bunce <Tim.Bunce@ig.co.uk.
294VMS support by Charles Bailey <bailey@newman.upenn.edu>.
295OS/2 support by Ilya Zakharevich <ilya@math.ohio-state.edu>.
296Mac support by Paul Schinder <schinder@pobox.com>, and Thomas Wegner
297<wegner_thomas@yahoo.com>. abs2rel() and rel2abs() written by Shigio
298Yamaguchi <shigio@tamacom.com>, modified by Barrie Slaymaker
299<barries@slaysys.com>. splitpath(), splitdir(), catpath() and
300catdir() by Barrie Slaymaker.
e021ab8e
JH
301
302=cut