1package File::Spec; 2 3use strict; 4use vars qw(@ISA $VERSION); 5 6$VERSION = '0.87'; 7 8my %module = (MacOS => 'Mac', 9 MSWin32 => 'Win32', 10 os2 => 'OS2', 11 VMS => 'VMS', 12 epoc => 'Epoc', 13 NetWare => 'Win32', # Yes, File::Spec::Win32 works on NetWare. 14 dos => 'OS2', # Yes, File::Spec::OS2 works on DJGPP. 15 cygwin => 'Cygwin'); 16 17 18my $module = $module{$^O} || 'Unix'; 19 20require "File/Spec/$module.pm"; 21@ISA = ("File::Spec::$module"); 22 231; 24 25__END__ 26 27=head1 NAME 28 29File::Spec - portably perform operations on file names 30 31=head1 SYNOPSIS 32 33 use File::Spec; 34 35 $x=File::Spec->catfile('a', 'b', 'c'); 36 37which returns 'a/b/c' under Unix. Or: 38 39 use File::Spec::Functions; 40 41 $x = catfile('a', 'b', 'c'); 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 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. 66 67Since File::Spec is object oriented, subroutines should not be called directly, 68as in: 69 70 File::Spec::catfile('a','b'); 71 72but rather as class methods: 73 74 File::Spec->catfile('a','b'); 75 76For simple uses, L<File::Spec::Functions> provides convenient functional 77forms of these methods. 78 79=head1 METHODS 80 81=over 2 82 83=item canonpath 84 85No physical check on the filesystem, but a logical cleanup of a 86path. 87 88 $cpath = File::Spec->canonpath( $path ) ; 89 90=item catdir 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 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. 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 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>). 164 165=item path 166 167Takes no argument, returns the environment variable PATH (or the local 168platform's equivalent) as a list. 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 179with no concept of volume, returns '' for volume. 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 206on some OSs. 207 208=item catpath() 209 210Takes volume, directory and file portions and returns an entire path. Under 211Unix, $volume is ignored, and directory and file are concatenated. A '/' is 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 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 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. 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()>. 240This means that it is taken to be relative to L<cwd()|Cwd>. 241 242No checks against the filesystem are made. On VMS, there is 243interaction with the working environment, as logicals and 244macros are expanded. 245 246Based on code written by Shigio Yamaguchi. 247 248=item rel2abs() 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 255If $base is not present or '', then L<cwd()|Cwd> is used. If $base is relative, 256then it is converted to absolute form using L</rel2abs()>. This means that it 257is taken to be relative to L<cwd()|Cwd>. 258 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. 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 271No checks against the filesystem are made. On VMS, there is 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>. 282 283=head1 SEE ALSO 284 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> 288 289=head1 AUTHORS 290 291Kenneth Albanowski <kjahds@kjahds.com>, Andy Dougherty 292<doughera@lafayette.edu>, Andreas KE<ouml>nig 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. 301 302=cut 303