From: Ronald J. Kimball Date: Wed, 22 Aug 2001 17:09:04 +0000 (-0400) Subject: Documentation in File::Spec (was Re: minor File::Spec X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ae1c33a12ee494201f28544af6904511e08ac3db;p=p5sagit%2Fp5-mst-13.2.git Documentation in File::Spec (was Re: minor File::Spec questions) Message-Id: <20010822170904.A76069@linguist.thayer.dartmouth.edu> p4raw-id: //depot/perl@11728 --- diff --git a/lib/File/Spec.pm b/lib/File/Spec.pm index 35707cc..19475c0 100644 --- a/lib/File/Spec.pm +++ b/lib/File/Spec.pm @@ -16,6 +16,7 @@ require "File/Spec/$module.pm"; @ISA = ("File::Spec::$module"); 1; + __END__ =head1 NAME @@ -70,24 +71,221 @@ 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 ) ; + +=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 "" if no writable +temporary directories are found. The list of directories checked +depends on the platform; e.g. File::Spec::Unix checks $ENV{TMPDIR} 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, or OS/2. It +does sometimes on MacOS (see L). +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 undef 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 (e.g. MacOS). + +=item catpath + +Takes volume, directory and file portions and returns an entire path. Under +Unix, $volume is ignored, and directory and file are catenated. 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 most systems. On MacOS, +the filesystem may be consulted (see +L). 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 most systems. On MacOS, +the filesystem may be consulted (see +L). 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 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 ->. abs2rel() and rel2abs() written by -Shigio Yamaguchi >, modified by Barrie Slaymaker ->. splitpath(), splitdir(), catpath() and catdir() +Kenneth Albanowski , Andy Dougherty +, Andreas KEnig +, Tim Bunce . 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.