Spec.pm revision 1.1
1package File::Spec; 2 3use strict; 4use vars qw(@ISA $VERSION); 5 6$VERSION = '3.48'; 7$VERSION =~ tr/_//; 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. 169Cygwin and Win32 accept an optional drive argument. 170 171 $is_case_tolerant = File::Spec->case_tolerant(); 172 173=item file_name_is_absolute 174 175Takes as its argument a path, and returns true if it is an absolute path. 176 177 $is_absolute = File::Spec->file_name_is_absolute( $path ); 178 179This does not consult the local filesystem on Unix, Win32, OS/2, or 180Mac OS (Classic). It does consult the working environment for VMS 181(see L<File::Spec::VMS/file_name_is_absolute>). 182 183=item path 184X<path> 185 186Takes no argument. Returns the environment variable C<PATH> (or the local 187platform's equivalent) as a list. 188 189 @PATH = File::Spec->path(); 190 191=item join 192X<join, path> 193 194join is the same as catfile. 195 196=item splitpath 197X<splitpath> X<split, path> 198 199Splits a path in to volume, directory, and filename portions. On systems 200with no concept of volume, returns '' for volume. 201 202 ($volume,$directories,$file) = 203 File::Spec->splitpath( $path ); 204 ($volume,$directories,$file) = 205 File::Spec->splitpath( $path, $no_file ); 206 207For systems with no syntax differentiating filenames from directories, 208assumes that the last file is a path unless C<$no_file> is true or a 209trailing separator or F</.> or F</..> is present. On Unix, this means that C<$no_file> 210true makes this return ( '', $path, '' ). 211 212The directory portion may or may not be returned with a trailing '/'. 213 214The results can be passed to L</catpath()> to get back a path equivalent to 215(usually identical to) the original path. 216 217=item splitdir 218X<splitdir> X<split, dir> 219 220The opposite of L</catdir>. 221 222 @dirs = File::Spec->splitdir( $directories ); 223 224C<$directories> must be only the directory portion of the path on systems 225that have the concept of a volume or that have path syntax that differentiates 226files from directories. 227 228Unlike just splitting the directories on the separator, empty 229directory names (C<''>) can be returned, because these are significant 230on some OSes. 231 232=item catpath() 233 234Takes volume, directory and file portions and returns an entire path. Under 235Unix, C<$volume> is ignored, and directory and file are concatenated. A '/' is 236inserted if need be. On other OSes, C<$volume> is significant. 237 238 $full_path = File::Spec->catpath( $volume, $directory, $file ); 239 240=item abs2rel 241X<abs2rel> X<absolute, path> X<relative, path> 242 243Takes a destination path and an optional base path returns a relative path 244from the base path to the destination path: 245 246 $rel_path = File::Spec->abs2rel( $path ) ; 247 $rel_path = File::Spec->abs2rel( $path, $base ) ; 248 249If C<$base> is not present or '', then L<Cwd::cwd()|Cwd> is used. If C<$base> is 250relative, then it is converted to absolute form using 251L</rel2abs()>. This means that it is taken to be relative to 252L<Cwd::cwd()|Cwd>. 253 254On systems with the concept of volume, if C<$path> and C<$base> appear to be 255on two different volumes, we will not attempt to resolve the two 256paths, and we will instead simply return C<$path>. Note that previous 257versions of this module ignored the volume of C<$base>, which resulted in 258garbage results part of the time. 259 260On systems that have a grammar that indicates filenames, this ignores the 261C<$base> filename as well. Otherwise all path components are assumed to be 262directories. 263 264If C<$path> is relative, it is converted to absolute form using L</rel2abs()>. 265This means that it is taken to be relative to L<Cwd::cwd()|Cwd>. 266 267No checks against the filesystem are made. On VMS, there is 268interaction with the working environment, as logicals and 269macros are expanded. 270 271Based on code written by Shigio Yamaguchi. 272 273=item rel2abs() 274X<rel2abs> X<absolute, path> X<relative, path> 275 276Converts a relative path to an absolute path. 277 278 $abs_path = File::Spec->rel2abs( $path ) ; 279 $abs_path = File::Spec->rel2abs( $path, $base ) ; 280 281If C<$base> is not present or '', then L<Cwd::cwd()|Cwd> is used. If C<$base> is relative, 282then it is converted to absolute form using L</rel2abs()>. This means that it 283is taken to be relative to L<Cwd::cwd()|Cwd>. 284 285On systems with the concept of volume, if C<$path> and C<$base> appear to be 286on two different volumes, we will not attempt to resolve the two 287paths, and we will instead simply return C<$path>. Note that previous 288versions of this module ignored the volume of C<$base>, which resulted in 289garbage results part of the time. 290 291On systems that have a grammar that indicates filenames, this ignores the 292C<$base> filename as well. Otherwise all path components are assumed to be 293directories. 294 295If C<$path> is absolute, it is cleaned up and returned using L</canonpath>. 296 297No checks against the filesystem are made. On VMS, there is 298interaction with the working environment, as logicals and 299macros are expanded. 300 301Based on code written by Shigio Yamaguchi. 302 303=back 304 305For further information, please see L<File::Spec::Unix>, 306L<File::Spec::Mac>, L<File::Spec::OS2>, L<File::Spec::Win32>, or 307L<File::Spec::VMS>. 308 309=head1 SEE ALSO 310 311L<File::Spec::Unix>, L<File::Spec::Mac>, L<File::Spec::OS2>, 312L<File::Spec::Win32>, L<File::Spec::VMS>, L<File::Spec::Functions>, 313L<ExtUtils::MakeMaker> 314 315=head1 AUTHOR 316 317Currently maintained by Ken Williams C<< <KWILLIAMS@cpan.org> >>. 318 319The vast majority of the code was written by 320Kenneth Albanowski C<< <kjahds@kjahds.com> >>, 321Andy Dougherty C<< <doughera@lafayette.edu> >>, 322Andreas KE<ouml>nig C<< <A.Koenig@franz.ww.TU-Berlin.DE> >>, 323Tim Bunce C<< <Tim.Bunce@ig.co.uk> >>. 324VMS support by Charles Bailey C<< <bailey@newman.upenn.edu> >>. 325OS/2 support by Ilya Zakharevich C<< <ilya@math.ohio-state.edu> >>. 326Mac support by Paul Schinder C<< <schinder@pobox.com> >>, and 327Thomas Wegner C<< <wegner_thomas@yahoo.com> >>. 328abs2rel() and rel2abs() written by Shigio Yamaguchi C<< <shigio@tamacom.com> >>, 329modified by Barrie Slaymaker C<< <barries@slaysys.com> >>. 330splitpath(), splitdir(), catpath() and catdir() by Barrie Slaymaker. 331 332=head1 COPYRIGHT 333 334Copyright (c) 2004-2013 by the Perl 5 Porters. All rights reserved. 335 336This program is free software; you can redistribute it and/or modify 337it under the same terms as Perl itself. 338 339=cut 340