X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FFile%2FSpec.pm;h=9aac374c138a5001d1cfbae7cff74aa01e508f40;hb=23bb49fa8c98c39adab74ba793fe7dad073789c2;hp=40503c467fe736db4b949947c81240feafa77b9c;hpb=4b19af017623bfa3bb72bb164598a517f586e0d3;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/File/Spec.pm b/lib/File/Spec.pm index 40503c4..9aac374 100644 --- a/lib/File/Spec.pm +++ b/lib/File/Spec.pm @@ -3,18 +3,27 @@ package File::Spec; use strict; use vars qw(@ISA $VERSION); -$VERSION = 0.82 ; +$VERSION = '3.17'; +$VERSION = eval $VERSION; my %module = (MacOS => 'Mac', MSWin32 => 'Win32', os2 => 'OS2', - VMS => 'VMS'); + VMS => 'VMS', + epoc => 'Epoc', + NetWare => 'Win32', # Yes, File::Spec::Win32 works on NetWare. + symbian => 'Win32', # Yes, File::Spec::Win32 works on symbian. + dos => 'OS2', # Yes, File::Spec::OS2 works on DJGPP. + cygwin => 'Cygwin'); + my $module = $module{$^O} || 'Unix'; + require "File/Spec/$module.pm"; @ISA = ("File::Spec::$module"); 1; + __END__ =head1 NAME @@ -57,7 +66,7 @@ File::Spec. Since some modules (like VMS) make use of facilities available only under that OS, it may not be possible to load all modules under all operating systems. -Since File::Spec is object oriented, subroutines should not called directly, +Since File::Spec is object oriented, subroutines should not be called directly, as in: File::Spec::catfile('a','b'); @@ -69,24 +78,245 @@ but rather as class methods: For simple uses, L provides convenient functional forms of these methods. -For a list of available methods, please consult L, -which contains the entire set, and which is inherited by the modules for -other platforms. For further information, please see L, -L, L, or L. +=head1 METHODS + +=over 2 + +=item canonpath + +No physical check on the filesystem, but a logical cleanup of a +path. + + $cpath = File::Spec->canonpath( $path ) ; + +Note that this does *not* collapse F sections into F. This +is by design. If F on your system is a symlink to F, +then F is actually F, not F as a naive +F<../>-removal would give you. If you want to do this kind of +processing, you probably want C's C function to +actually traverse the filesystem cleaning up paths like this. + +=item catdir + +Concatenate two or more directory names to form a complete path ending +with a directory. But remove the trailing slash from the resulting +string, because it doesn't look good, isn't necessary and confuses +OS/2. Of course, if this is the root directory, don't cut off the +trailing slash :-) + + $path = File::Spec->catdir( @directories ); + +=item catfile + +Concatenate one or more directory names and a filename to form a +complete path ending with a filename + + $path = File::Spec->catfile( @directories, $filename ); + +=item curdir + +Returns a string representation of the current directory. + + $curdir = File::Spec->curdir(); + +=item devnull + +Returns a string representation of the null device. + + $devnull = File::Spec->devnull(); + +=item rootdir + +Returns a string representation of the root directory. + + $rootdir = File::Spec->rootdir(); + +=item tmpdir + +Returns a string representation of the first writable directory from a +list of possible temporary directories. Returns the current directory +if no writable temporary directories are found. The list of directories +checked depends on the platform; e.g. File::Spec::Unix checks C<$ENV{TMPDIR}> +(unless taint is on) and F. + + $tmpdir = File::Spec->tmpdir(); + +=item updir + +Returns a string representation of the parent directory. + + $updir = File::Spec->updir(); + +=item no_upwards + +Given a list of file names, strip out those that refer to a parent +directory. (Does not strip symlinks, only '.', '..', and equivalents.) + + @paths = File::Spec->no_upwards( @paths ); + +=item case_tolerant + +Returns a true or false value indicating, respectively, that alphabetic +case is not or is significant when comparing file specifications. + + $is_case_tolerant = File::Spec->case_tolerant(); + +=item file_name_is_absolute + +Takes as its argument a path, and returns true if it is an absolute path. + + $is_absolute = File::Spec->file_name_is_absolute( $path ); + +This does not consult the local filesystem on Unix, Win32, OS/2, or +Mac OS (Classic). It does consult the working environment for VMS +(see L). + +=item path + +Takes no argument. Returns the environment variable C (or the local +platform's equivalent) as a list. + + @PATH = File::Spec->path(); + +=item join + +join is the same as catfile. + +=item splitpath + +Splits a path in to volume, directory, and filename portions. On systems +with no concept of volume, returns '' for volume. + + ($volume,$directories,$file) = File::Spec->splitpath( $path ); + ($volume,$directories,$file) = File::Spec->splitpath( $path, $no_file ); + +For systems with no syntax differentiating filenames from directories, +assumes that the last file is a path unless C<$no_file> is true or a +trailing separator or F or F is present. On Unix, this means that C<$no_file> +true makes this return ( '', $path, '' ). + +The directory portion may or may not be returned with a trailing '/'. + +The results can be passed to L to get back a path equivalent to +(usually identical to) the original path. + +=item splitdir + +The opposite of L. + + @dirs = File::Spec->splitdir( $directories ); + +C<$directories> must be only the directory portion of the path on systems +that have the concept of a volume or that have path syntax that differentiates +files from directories. + +Unlike just splitting the directories on the separator, empty +directory names (C<''>) can be returned, because these are significant +on some OSes. + +=item catpath() + +Takes volume, directory and file portions and returns an entire path. Under +Unix, C<$volume> is ignored, and directory and file are concatenated. A '/' is +inserted if need be. On other OSes, C<$volume> is significant. + + $full_path = File::Spec->catpath( $volume, $directory, $file ); + +=item abs2rel + +Takes a destination path and an optional base path returns a relative path +from the base path to the destination path: + + $rel_path = File::Spec->abs2rel( $path ) ; + $rel_path = File::Spec->abs2rel( $path, $base ) ; + +If C<$base> is not present or '', then L is used. If C<$base> is +relative, then it is converted to absolute form using +L. This means that it is taken to be relative to +L. + +On systems with the concept of volume, if C<$path> and C<$base> appear to be +on two different volumes, we will not attempt to resolve the two +paths, and we will instead simply return C<$path>. Note that previous +versions of this module ignored the volume of C<$base>, which resulted in +garbage results part of the time. + +On systems that have a grammar that indicates filenames, this ignores the +C<$base> filename as well. Otherwise all path components are assumed to be +directories. + +If C<$path> is relative, it is converted to absolute form using L. +This means that it is taken to be relative to L. + +No checks against the filesystem are made. On VMS, there is +interaction with the working environment, as logicals and +macros are expanded. + +Based on code written by Shigio Yamaguchi. + +=item rel2abs() + +Converts a relative path to an absolute path. + + $abs_path = File::Spec->rel2abs( $path ) ; + $abs_path = File::Spec->rel2abs( $path, $base ) ; + +If C<$base> is not present or '', then L is used. If C<$base> is relative, +then it is converted to absolute form using L. This means that it +is taken to be relative to L. + +On systems with the concept of volume, if C<$path> and C<$base> appear to be +on two different volumes, we will not attempt to resolve the two +paths, and we will instead simply return C<$path>. Note that previous +versions of this module ignored the volume of C<$base>, which resulted in +garbage results part of the time. + +On systems that have a grammar that indicates filenames, this ignores the +C<$base> filename as well. Otherwise all path components are assumed to be +directories. + +If C<$path> is absolute, it is cleaned up and returned using L. + +No checks against the filesystem are made. On VMS, there is +interaction with the working environment, as logicals and +macros are expanded. + +Based on code written by Shigio Yamaguchi. + +=back + +For further information, please see L, +L, L, L, or +L. =head1 SEE ALSO -File::Spec::Unix, File::Spec::Mac, File::Spec::OS2, File::Spec::Win32, -File::Spec::VMS, File::Spec::Functions, ExtUtils::MakeMaker +L, L, L, +L, L, L, +L + +=head1 AUTHOR + +Currently maintained by Ken Williams C<< >>. + +The vast majority of the code was written by +Kenneth Albanowski C<< >>, +Andy Dougherty C<< >>, +Andreas KEnig C<< >>, +Tim Bunce C<< >>. +VMS support by Charles Bailey C<< >>. +OS/2 support by Ilya Zakharevich C<< >>. +Mac support by Paul Schinder C<< >>, and +Thomas Wegner C<< >>. +abs2rel() and rel2abs() written by Shigio Yamaguchi C<< >>, +modified by Barrie Slaymaker C<< >>. +splitpath(), splitdir(), catpath() and catdir() by Barrie Slaymaker. + +=head1 COPYRIGHT + +Copyright (c) 2004 by the Perl 5 Porters. All rights reserved. -=head1 AUTHORS +This program is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. -Kenneth Albanowski >, Andy Dougherty ->, Andreas KEnig ->, Tim Bunce >. VMS -support by Charles Bailey >. OS/2 support by -Ilya Zakharevich >. Mac support by Paul Schinder ->. abs2rel() and rel2abs() written by -Shigio Yamaguchi >, modified by Barrie Slaymaker ->. splitpath(), splitdir(), catpath() and catdir() -by Barrie Slaymaker. +=cut