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