lib/File/Spec.pm

package File::Spec;

use strict;
use vars qw(@ISA $VERSION);

$VERSION = '3.05';
$VERSION = eval $VERSION;

my %module = (MacOS   => 'Mac',
              MSWin32 => 'Win32',
              os2     => 'OS2',
              VMS     => 'VMS',
              epoc    => 'Epoc',
              NetWare => 'Win32', # Yes, File::Spec::Win32 works on NetWare.
              dos     => 'OS2',   # Yes, File::Spec::OS2 works on DJGPP.
              cygwin  => 'Cygwin');


my $module = $module{$^O} || 'Unix';

require "File/Spec/$module.pm";
@ISA = ("File::Spec::$module");

1;

__END__

=head1 NAME

File::Spec - portably perform operations on file names

=head1 SYNOPSIS

        use File::Spec;

        $x=File::Spec->catfile('a', 'b', 'c');

which returns 'a/b/c' under Unix. Or:

        use File::Spec::Functions;

        $x = catfile('a', 'b', 'c');

=head1 DESCRIPTION

This module is designed to support operations commonly performed on file
specifications (usually called "file names", but not to be confused with the
contents of a file, or Perl's file handles), such as concatenating several
directory and file names into a single path, or determining whether a path
is rooted. It is based on code directly taken from MakeMaker 5.17, code
written by Andreas KE<ouml>nig, Andy Dougherty, Charles Bailey, Ilya
Zakharevich, Paul Schinder, and others.

Since these functions are different for most operating systems, each set of
OS specific routines is available in a separate module, including:

        File::Spec::Unix
        File::Spec::Mac
        File::Spec::OS2
        File::Spec::Win32
        File::Spec::VMS

The module appropriate for the current OS is automatically loaded by
File::Spec. Since some modules (like VMS) make use of facilities available
only under that OS, it may not be possible to load all modules under all
operating systems.

Since File::Spec is object oriented, subroutines should not be called directly,
as in:

        File::Spec::catfile('a','b');

but rather as class methods:

        File::Spec->catfile('a','b');

For simple uses, L<File::Spec::Functions> provides convenient functional
forms of these methods.

=head1 METHODS

=over 2

=item canonpath

No physical check on the filesystem, but a logical cleanup of a
path.

    $cpath = File::Spec->canonpath( $path ) ;

=item catdir

Concatenate two or more directory names to form a complete path ending
with a directory. But remove the trailing slash from the resulting
string, because it doesn't look good, isn't necessary and confuses
OS/2. Of course, if this is the root directory, don't cut off the
trailing slash :-)

    $path = File::Spec->catdir( @directories );

=item catfile

Concatenate one or more directory names and a filename to form a
complete path ending with a filename

    $path = File::Spec->catfile( @directories, $filename );

=item curdir

Returns a string representation of the current directory.

    $curdir = File::Spec->curdir();

=item devnull

Returns a string representation of the null device.

    $devnull = File::Spec->devnull();

=item rootdir

Returns a string representation of the root directory.

    $rootdir = File::Spec->rootdir();

=item tmpdir

Returns a string representation of the first writable directory from a
list of possible temporary directories.  Returns the current directory
if no writable temporary directories are found.  The list of directories
checked depends on the platform; e.g. File::Spec::Unix checks C<$ENV{TMPDIR}>
(unless taint is on) and F</tmp>.

    $tmpdir = File::Spec->tmpdir();

=item updir

Returns a string representation of the parent directory.

    $updir = File::Spec->updir();

=item no_upwards

Given a list of file names, strip out those that refer to a parent
directory. (Does not strip symlinks, only '.', '..', and equivalents.)

    @paths = File::Spec->no_upwards( @paths );

=item case_tolerant

Returns a true or false value indicating, respectively, that alphabetic
case is not or is significant when comparing file specifications.

    $is_case_tolerant = File::Spec->case_tolerant();

=item file_name_is_absolute

Takes as its argument a path, and returns true if it is an absolute path.

    $is_absolute = File::Spec->file_name_is_absolute( $path );

This does not consult the local filesystem on Unix, Win32, OS/2, or
Mac OS (Classic).  It does consult the working environment for VMS
(see L<File::Spec::VMS/file_name_is_absolute>).

=item path

Takes no argument.  Returns the environment variable C<PATH> (or the local
platform's equivalent) as a list.

    @PATH = File::Spec->path();

=item join

join is the same as catfile.

=item splitpath

Splits a path in to volume, directory, and filename portions. On systems
with no concept of volume, returns '' for volume. 

    ($volume,$directories,$file) = File::Spec->splitpath( $path );
    ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );

For systems with no syntax differentiating filenames from directories, 
assumes that the last file is a path unless C<$no_file> is true or a
trailing separator or F</.> or F</..> is present. On Unix, this means that C<$no_file>
true makes this return ( '', $path, '' ).

The directory portion may or may not be returned with a trailing '/'.

The results can be passed to L</catpath()> to get back a path equivalent to
(usually identical to) the original path.

=item splitdir

The opposite of L</catdir()>.

    @dirs = File::Spec->splitdir( $directories );

C<$directories> must be only the directory portion of the path on systems 
that have the concept of a volume or that have path syntax that differentiates
files from directories.

Unlike just splitting the directories on the separator, empty
directory names (C<''>) can be returned, because these are significant
on some OSes.

=item catpath()

Takes volume, directory and file portions and returns an entire path. Under
Unix, C<$volume> is ignored, and directory and file are concatenated.  A '/' is
inserted if need be.  On other OSes, C<$volume> is significant.

    $full_path = File::Spec->catpath( $volume, $directory, $file );

=item abs2rel

Takes a destination path and an optional base path returns a relative path
from the base path to the destination path:

    $rel_path = File::Spec->abs2rel( $path ) ;
    $rel_path = File::Spec->abs2rel( $path, $base ) ;

If C<$base> is not present or '', then L<cwd()|Cwd> is used. If C<$base> is
relative, then it is converted to absolute form using
L</rel2abs()>. This means that it is taken to be relative to
L<cwd()|Cwd>.

On systems with the concept of volume, if C<$path> and C<$base> appear to be
on two different volumes, we will not attempt to resolve the two
paths, and we will instead simply return C<$path>.  Note that previous
versions of this module ignored the volume of C<$base>, which resulted in
garbage results part of the time.

On systems that have a grammar that indicates filenames, this ignores the 
C<$base> filename as well. Otherwise all path components are assumed to be
directories.

If C<$path> is relative, it is converted to absolute form using L</rel2abs()>.
This means that it is taken to be relative to L<cwd()|Cwd>.

No checks against the filesystem are made.  On VMS, there is
interaction with the working environment, as logicals and
macros are expanded.

Based on code written by Shigio Yamaguchi.

=item rel2abs()

Converts a relative path to an absolute path. 

    $abs_path = File::Spec->rel2abs( $path ) ;
    $abs_path = File::Spec->rel2abs( $path, $base ) ;

If C<$base> is not present or '', then L<cwd()|Cwd> is used. If C<$base> is relative,
then it is converted to absolute form using L</rel2abs()>. This means that it
is taken to be relative to L<cwd()|Cwd>.

On systems with the concept of volume, if C<$path> and C<$base> appear to be
on two different volumes, we will not attempt to resolve the two
paths, and we will instead simply return C<$path>.  Note that previous
versions of this module ignored the volume of C<$base>, which resulted in
garbage results part of the time.

On systems that have a grammar that indicates filenames, this ignores the 
C<$base> filename as well. Otherwise all path components are assumed to be
directories.

If C<$path> is absolute, it is cleaned up and returned using L</canonpath()>.

No checks against the filesystem are made.  On VMS, there is
interaction with the working environment, as logicals and
macros are expanded.

Based on code written by Shigio Yamaguchi.

=back

For further information, please see L<File::Spec::Unix>,
L<File::Spec::Mac>, L<File::Spec::OS2>, L<File::Spec::Win32>, or
L<File::Spec::VMS>.

=head1 SEE ALSO

L<File::Spec::Unix>, L<File::Spec::Mac>, L<File::Spec::OS2>,
L<File::Spec::Win32>, L<File::Spec::VMS>, L<File::Spec::Functions>,
L<ExtUtils::MakeMaker>

=head1 AUTHOR

Currently maintained by Ken Williams C<< <KWILLIAMS@cpan.org> >>.

The vast majority of the code was written by
Kenneth Albanowski C<< <kjahds@kjahds.com> >>,
Andy Dougherty C<< <doughera@lafayette.edu> >>,
Andreas KE<ouml>nig C<< <A.Koenig@franz.ww.TU-Berlin.DE> >>,
Tim Bunce C<< <Tim.Bunce@ig.co.uk> >>.
VMS support by Charles Bailey C<< <bailey@newman.upenn.edu> >>.
OS/2 support by Ilya Zakharevich C<< <ilya@math.ohio-state.edu> >>.
Mac support by Paul Schinder C<< <schinder@pobox.com> >>, and
Thomas Wegner C<< <wegner_thomas@yahoo.com> >>.
abs2rel() and rel2abs() written by Shigio Yamaguchi C<< <shigio@tamacom.com> >>,
modified by Barrie Slaymaker C<< <barries@slaysys.com> >>.
splitpath(), splitdir(), catpath() and catdir() by Barrie Slaymaker.

=head1 COPYRIGHT

Copyright (c) 2004 by the Perl 5 Porters.  All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

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