[Summary view] [Print] [Text view]

   1  package File::Spec;
   2  
   3  use strict;
   4  use vars qw(@ISA $VERSION);
   5  
   6  $VERSION = '3.2501';
   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  X<canonpath>
  87  
  88  No physical check on the filesystem, but a logical cleanup of a
  89  path.
  90  
  91      $cpath = File::Spec->canonpath( $path ) ;
  92  
  93  Note that this does *not* collapse F<x/../y> sections into F<y>.  This
  94  is by design.  If F</foo> on your system is a symlink to F</bar/baz>,
  95  then F</foo/../quux> is actually F</bar/quux>, not F</quux> as a naive
  96  F<../>-removal would give you.  If you want to do this kind of
  97  processing, you probably want C<Cwd>'s C<realpath()> function to
  98  actually traverse the filesystem cleaning up paths like this.
  99  
 100  =item catdir
 101  X<catdir>
 102  
 103  Concatenate two or more directory names to form a complete path ending
 104  with a directory. But remove the trailing slash from the resulting
 105  string, because it doesn't look good, isn't necessary and confuses
 106  OS/2. Of course, if this is the root directory, don't cut off the
 107  trailing slash :-)
 108  
 109      $path = File::Spec->catdir( @directories );
 110  
 111  =item catfile
 112  X<catfile>
 113  
 114  Concatenate one or more directory names and a filename to form a
 115  complete path ending with a filename
 116  
 117      $path = File::Spec->catfile( @directories, $filename );
 118  
 119  =item curdir
 120  X<curdir>
 121  
 122  Returns a string representation of the current directory.
 123  
 124      $curdir = File::Spec->curdir();
 125  
 126  =item devnull
 127  X<devnull>
 128  
 129  Returns a string representation of the null device.
 130  
 131      $devnull = File::Spec->devnull();
 132  
 133  =item rootdir
 134  X<rootdir>
 135  
 136  Returns a string representation of the root directory.
 137  
 138      $rootdir = File::Spec->rootdir();
 139  
 140  =item tmpdir
 141  X<tmpdir>
 142  
 143  Returns a string representation of the first writable directory from a
 144  list of possible temporary directories.  Returns the current directory
 145  if no writable temporary directories are found.  The list of directories
 146  checked 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
 152  X<updir>
 153  
 154  Returns a string representation of the parent directory.
 155  
 156      $updir = File::Spec->updir();
 157  
 158  =item no_upwards
 159  
 160  Given a list of file names, strip out those that refer to a parent
 161  directory. (Does not strip symlinks, only '.', '..', and equivalents.)
 162  
 163      @paths = File::Spec->no_upwards( @paths );
 164  
 165  =item case_tolerant
 166  
 167  Returns a true or false value indicating, respectively, that alphabetic
 168  case is not or is significant when comparing file specifications.
 169  
 170      $is_case_tolerant = File::Spec->case_tolerant();
 171  
 172  =item file_name_is_absolute
 173  
 174  Takes as its argument a path, and returns true if it is an absolute path.
 175  
 176      $is_absolute = File::Spec->file_name_is_absolute( $path );
 177  
 178  This does not consult the local filesystem on Unix, Win32, OS/2, or
 179  Mac OS (Classic).  It does consult the working environment for VMS
 180  (see L<File::Spec::VMS/file_name_is_absolute>).
 181  
 182  =item path
 183  X<path>
 184  
 185  Takes no argument.  Returns the environment variable C<PATH> (or the local
 186  platform's equivalent) as a list.
 187  
 188      @PATH = File::Spec->path();
 189  
 190  =item join
 191  X<join, path>
 192  
 193  join is the same as catfile.
 194  
 195  =item splitpath
 196  X<splitpath> X<split, path>
 197  
 198  Splits a path in to volume, directory, and filename portions. On systems
 199  with no concept of volume, returns '' for volume. 
 200  
 201      ($volume,$directories,$file) = File::Spec->splitpath( $path );
 202      ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file );
 203  
 204  For systems with no syntax differentiating filenames from directories, 
 205  assumes that the last file is a path unless C<$no_file> is true or a
 206  trailing separator or F</.> or F</..> is present. On Unix, this means that C<$no_file>
 207  true makes this return ( '', $path, '' ).
 208  
 209  The directory portion may or may not be returned with a trailing '/'.
 210  
 211  The results can be passed to L</catpath()> to get back a path equivalent to
 212  (usually identical to) the original path.
 213  
 214  =item splitdir
 215  X<splitdir> X<split, dir>
 216  
 217  The opposite of L</catdir()>.
 218  
 219      @dirs = File::Spec->splitdir( $directories );
 220  
 221  C<$directories> must be only the directory portion of the path on systems 
 222  that have the concept of a volume or that have path syntax that differentiates
 223  files from directories.
 224  
 225  Unlike just splitting the directories on the separator, empty
 226  directory names (C<''>) can be returned, because these are significant
 227  on some OSes.
 228  
 229  =item catpath()
 230  
 231  Takes volume, directory and file portions and returns an entire path. Under
 232  Unix, C<$volume> is ignored, and directory and file are concatenated.  A '/' is
 233  inserted if need be.  On other OSes, C<$volume> is significant.
 234  
 235      $full_path = File::Spec->catpath( $volume, $directory, $file );
 236  
 237  =item abs2rel
 238  X<abs2rel> X<absolute, path> X<relative, path>
 239  
 240  Takes a destination path and an optional base path returns a relative path
 241  from the base path to the destination path:
 242  
 243      $rel_path = File::Spec->abs2rel( $path ) ;
 244      $rel_path = File::Spec->abs2rel( $path, $base ) ;
 245  
 246  If C<$base> is not present or '', then L<Cwd::cwd()|Cwd> is used. If C<$base> is
 247  relative, then it is converted to absolute form using
 248  L</rel2abs()>. This means that it is taken to be relative to
 249  L<Cwd::cwd()|Cwd>.
 250  
 251  On systems with the concept of volume, if C<$path> and C<$base> appear to be
 252  on two different volumes, we will not attempt to resolve the two
 253  paths, and we will instead simply return C<$path>.  Note that previous
 254  versions of this module ignored the volume of C<$base>, which resulted in
 255  garbage results part of the time.
 256  
 257  On systems that have a grammar that indicates filenames, this ignores the 
 258  C<$base> filename as well. Otherwise all path components are assumed to be
 259  directories.
 260  
 261  If C<$path> is relative, it is converted to absolute form using L</rel2abs()>.
 262  This means that it is taken to be relative to L<Cwd::cwd()|Cwd>.
 263  
 264  No checks against the filesystem are made.  On VMS, there is
 265  interaction with the working environment, as logicals and
 266  macros are expanded.
 267  
 268  Based on code written by Shigio Yamaguchi.
 269  
 270  =item rel2abs()
 271  X<rel2abs> X<absolute, path> X<relative, path>
 272  
 273  Converts a relative path to an absolute path. 
 274  
 275      $abs_path = File::Spec->rel2abs( $path ) ;
 276      $abs_path = File::Spec->rel2abs( $path, $base ) ;
 277  
 278  If C<$base> is not present or '', then L<Cwd::cwd()|Cwd> is used. If C<$base> is relative,
 279  then it is converted to absolute form using L</rel2abs()>. This means that it
 280  is taken to be relative to L<Cwd::cwd()|Cwd>.
 281  
 282  On systems with the concept of volume, if C<$path> and C<$base> appear to be
 283  on two different volumes, we will not attempt to resolve the two
 284  paths, and we will instead simply return C<$path>.  Note that previous
 285  versions of this module ignored the volume of C<$base>, which resulted in
 286  garbage results part of the time.
 287  
 288  On systems that have a grammar that indicates filenames, this ignores the 
 289  C<$base> filename as well. Otherwise all path components are assumed to be
 290  directories.
 291  
 292  If C<$path> is absolute, it is cleaned up and returned using L</canonpath()>.
 293  
 294  No checks against the filesystem are made.  On VMS, there is
 295  interaction with the working environment, as logicals and
 296  macros are expanded.
 297  
 298  Based on code written by Shigio Yamaguchi.
 299  
 300  =back
 301  
 302  For further information, please see L<File::Spec::Unix>,
 303  L<File::Spec::Mac>, L<File::Spec::OS2>, L<File::Spec::Win32>, or
 304  L<File::Spec::VMS>.
 305  
 306  =head1 SEE ALSO
 307  
 308  L<File::Spec::Unix>, L<File::Spec::Mac>, L<File::Spec::OS2>,
 309  L<File::Spec::Win32>, L<File::Spec::VMS>, L<File::Spec::Functions>,
 310  L<ExtUtils::MakeMaker>
 311  
 312  =head1 AUTHOR
 313  
 314  Currently maintained by Ken Williams C<< <KWILLIAMS@cpan.org> >>.
 315  
 316  The vast majority of the code was written by
 317  Kenneth Albanowski C<< <kjahds@kjahds.com> >>,
 318  Andy Dougherty C<< <doughera@lafayette.edu> >>,
 319  Andreas KE<ouml>nig C<< <A.Koenig@franz.ww.TU-Berlin.DE> >>,
 320  Tim Bunce C<< <Tim.Bunce@ig.co.uk> >>.
 321  VMS support by Charles Bailey C<< <bailey@newman.upenn.edu> >>.
 322  OS/2 support by Ilya Zakharevich C<< <ilya@math.ohio-state.edu> >>.
 323  Mac support by Paul Schinder C<< <schinder@pobox.com> >>, and
 324  Thomas Wegner C<< <wegner_thomas@yahoo.com> >>.
 325  abs2rel() and rel2abs() written by Shigio Yamaguchi C<< <shigio@tamacom.com> >>,
 326  modified by Barrie Slaymaker C<< <barries@slaysys.com> >>.
 327  splitpath(), splitdir(), catpath() and catdir() by Barrie Slaymaker.
 328  
 329  =head1 COPYRIGHT
 330  
 331  Copyright (c) 2004 by the Perl 5 Porters.  All rights reserved.
 332  
 333  This program is free software; you can redistribute it and/or modify
 334  it under the same terms as Perl itself.
 335  
 336  =cut