lib/File/Spec.pm

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