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