X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FFile%2FSpec.pm;h=28379abf7649c80433681779b40cb7314446b269;hb=1158ce344e6265a869b839cb74dfea1138fd2130;hp=0f90a45b6262dade354232ab02dd7359aaf250c8;hpb=2586ba89304e7acdb4f9d621c694129dc14f6c8f;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/File/Spec.pm b/lib/File/Spec.pm index 0f90a45..28379ab 100644 --- a/lib/File/Spec.pm +++ b/lib/File/Spec.pm @@ -1,17 +1,24 @@ package File::Spec; use strict; -our(@ISA, $VERSION); +use vars qw(@ISA $VERSION); -$VERSION = 0.83 ; +$VERSION = '3.24'; +$VERSION = eval $VERSION; my %module = (MacOS => 'Mac', MSWin32 => 'Win32', os2 => 'OS2', VMS => 'VMS', - epoc => 'Epoc'); + 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"); @@ -75,24 +82,34 @@ forms of these methods. =over 2 -=item canonpath() +=item canonpath +X No physical check on the filesystem, but a logical cleanup of a path. $cpath = File::Spec->canonpath( $path ) ; -=item catdir() +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 +X 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 +OS/2. Of course, if this is the root directory, don't cut off the trailing slash :-) $path = File::Spec->catdir( @directories ); =item catfile +X Concatenate one or more directory names and a filename to form a complete path ending with a filename @@ -100,34 +117,39 @@ complete path ending with a filename $path = File::Spec->catfile( @directories, $filename ); =item curdir +X Returns a string representation of the current directory. $curdir = File::Spec->curdir(); =item devnull +X Returns a string representation of the null device. $devnull = File::Spec->devnull(); =item rootdir +X Returns a string representation of the root directory. $rootdir = File::Spec->rootdir(); =item tmpdir +X 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. +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 +X Returns a string representation of the parent directory. @@ -143,13 +165,13 @@ directory. (Does not strip symlinks, only '.', '..', and equivalents.) =item case_tolerant Returns a true or false value indicating, respectively, that alphabetic -is not or is significant when comparing file specifications. +case 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. +Takes as its argument a path, and returns true if it is an absolute path. $is_absolute = File::Spec->file_name_is_absolute( $path ); @@ -158,26 +180,30 @@ Mac OS (Classic). It does consult the working environment for VMS (see L). =item path +X -Takes no argument, returns the environment variable PATH as an array. +Takes no argument. Returns the environment variable C (or the local +platform's equivalent) as a list. @PATH = File::Spec->path(); =item join +X join is the same as catfile. =item splitpath +X X Splits a path in to volume, directory, and filename portions. On systems -with no concept of volume, returns undef for volume. +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 +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 '/'. @@ -186,28 +212,30 @@ The results can be passed to L to get back a path equivalent to (usually identical to) the original path. =item splitdir +X X The opposite of L. @dirs = File::Spec->splitdir( $directories ); -$directories must be only the directory portion of the path on systems +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 OSs. +on some OSes. =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. +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 +X X X Takes a destination path and an optional base path returns a relative path from the base path to the destination path: @@ -215,19 +243,23 @@ 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. +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 a volume, this assumes that both paths -are on the $destination volume, and ignores the $base volume. +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 -$base filename as well. Otherwise all path components are assumed to be +C<$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. +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 @@ -236,24 +268,28 @@ macros are expanded. Based on code written by Shigio Yamaguchi. =item rel2abs() +X X X 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, +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. +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 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 -$base filename as well. Otherwise all path components are assumed to be +C<$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. +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 @@ -273,15 +309,28 @@ L, L, L, L, L, L, L -=head1 AUTHORS - -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. +=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. + +This program is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +=cut