lib/File/Spec.pm

   1 package File::Spec;
   2
   3 use strict;
   4 use vars qw(@ISA $VERSION);
   5
   6 $VERSION = '3.01';
   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 =cut