X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FFile%2FSpec.pm;h=c43576b5fa95ddfc7c84f38fe9757eddc7d51aa1;hb=f93bb41e64f81800210e18ffedb5ed633e362495;hp=9de9a8036f561898c91c1cb9ec50c14b1663b96a;hpb=cbc7acb08556fe93b6145fc8865b65a348dd7935;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/File/Spec.pm b/lib/File/Spec.pm index 9de9a80..c43576b 100644 --- a/lib/File/Spec.pm +++ b/lib/File/Spec.pm @@ -3,18 +3,25 @@ package File::Spec; use strict; use vars qw(@ISA $VERSION); -$VERSION = '0.6'; +$VERSION = '0.86'; my %module = (MacOS => 'Mac', MSWin32 => 'Win32', os2 => 'OS2', - VMS => 'VMS'); + VMS => 'VMS', + epoc => 'Epoc', + NetWare => 'Win32', # Yes, File::Spec::Win32 works on NetWare. + 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 @@ -23,11 +30,15 @@ File::Spec - portably perform operations on file names =head1 SYNOPSIS -C + use File::Spec; -C<$x=File::Spec-Ecatfile('a','b','c');> + $x=File::Spec->catfile('a', 'b', 'c'); -which returns 'a/b/c' under Unix. +which returns 'a/b/c' under Unix. Or: + + use File::Spec::Functions; + + $x = catfile('a', 'b', 'c'); =head1 DESCRIPTION @@ -49,34 +60,235 @@ OS specific routines is available in a separate module, including: File::Spec::VMS The module appropriate for the current OS is automatically loaded by -File::Spec. Since some modules (like VMS) make use of OS specific -facilities, it may not be possible to load all modules under all operating -systems. +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'); - + but rather as class methods: File::Spec->catfile('a','b'); -For a reference of available functions, please consult L, -which contains the entire set, and inherited by the modules for other -platforms. For further information, please see L, -L, L, or L. +For simple uses, L provides convenient functional +forms of these methods. + +=head1 METHODS + +=over 2 + +=item canonpath + +No physical check on the filesystem, but a logical cleanup of a +path. + + $cpath = File::Spec->canonpath( $path ) ; + +=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 +OS2. 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 $ENV{TMPDIR} +(unless taint is on) and /tmp. + + $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 +is not or is significant when comparing file specifications. + + $is_case_tolerant = File::Spec->case_tolerant(); + +=item file_name_is_absolute + +Takes as 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 PATH as an array. + + @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 $no_file is true or a +trailing separator or /. or /.. is present. On Unix this means that $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 ); + +$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 OSs. + +=item catpath() + +Takes volume, directory and file portions and returns an entire path. Under +Unix, $volume is ignored, and directory and file are concatenated. A '/' is +inserted if need be. On other OSs, $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 $base is not present or '', then L is used. If $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 a volume, this assumes that both paths +are on the $destination volume, and ignores the $base volume. + +On systems that have a grammar that indicates filenames, this ignores the +$base filename as well. Otherwise all path components are assumed to be +directories. + +If $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 $base is not present or '', then L is used. If $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 a volume, this assumes that both paths +are on the $base volume, and ignores the $path volume. + +On systems that have a grammar that indicates filenames, this ignores the +$base filename as well. Otherwise all path components are assumed to be +directories. + +If $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, ExtUtils::MakeMaker +L, L, L, +L, L, L, +L =head1 AUTHORS -Kenneth Albanowski >, Andy Dougherty ->, Andreas KEnig ->, Tim Bunce >. VMS -support by Charles Bailey >. OS/2 support by -Ilya Zakharevich >. Mac support by Paul Schinder ->. +Kenneth Albanowski , Andy Dougherty +, Andreas KEnig +, Tim Bunce . +OS/2 support by Ilya Zakharevich . +Mac support by Paul Schinder , and Thomas Wegner +. abs2rel() and rel2abs() written by Shigio +Yamaguchi , modified by Barrie Slaymaker +. splitpath(), splitdir(), catpath() and +catdir() by Barrie Slaymaker. + +=cut