lib/File/Spec.pm

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