File::Spec 0.82 beta

Message-Id: <200006281535.LAA21095@jester.slaysys.com>

p4raw-id: //depot/perl@6283

4 files changed, 41 insertions, 87 deletions

diff --git a/lib/File/Spec.pm b/lib/File/Spec.pm
index ed26d76a56..40503c467f 100644
--- a/lib/File/Spec.pm
+++ b/lib/File/Spec.pm
@@ -3,7 +3,7 @@ package File::Spec;
 use strict;
 use vars qw(@ISA $VERSION);
 
-$VERSION = '0.81';
+$VERSION = 0.82 ;
 
 my %module = (MacOS   => 'Mac',
 	      MSWin32 => 'Win32',
diff --git a/lib/File/Spec/Mac.pm b/lib/File/Spec/Mac.pm
index 5315d9220f..4d365cbb09 100644
--- a/lib/File/Spec/Mac.pm
+++ b/lib/File/Spec/Mac.pm
@@ -4,7 +4,7 @@ use strict;
 use vars qw(@ISA $VERSION);
 require File::Spec::Unix;
 
-$VERSION = '1.1';
+$VERSION = '1.2';
 
 @ISA = qw(File::Spec::Unix);
 
@@ -192,12 +192,16 @@ folder named "HD" in the current working directory on a drive named "HD"),
 relative wins.  Use ":" in the appropriate place in the path if you want to
 distinguish unambiguously.
 
+As a special case, the file name '' is always considered to be absolute.
+
 =cut
 
 sub file_name_is_absolute {
     my ($self,$file) = @_;
     if ($file =~ /:/) {
 	return ($file !~ m/^:/s);
+    } elsif ( $file eq '' ) {
+        return 1 ;
     } else {
 	return (! -e ":$file");
     }
@@ -307,6 +311,12 @@ sub catpath {
 
 =item abs2rel
 
+See L<File::Spec::Unix/abs2rel> for general documentation.
+
+Unlike C<File::Spec::Unix->abs2rel()>, this function will make
+checks against the local filesystem if necessary.  See
+L</file_name_is_absolute> for details.
+
 =cut
 
 sub abs2rel {
@@ -344,27 +354,11 @@ sub abs2rel {
 
 =item rel2abs
 
-Converts a relative path to an absolute path. 
-
-    $abs_path = File::Spec->rel2abs( $destination ) ;
-    $abs_path = File::Spec->rel2abs( $destination, $base ) ;
-
-If $base is not present or '', then L<cwd()> is used. If $base is relative, 
-then it is converted to absolute form using L</rel2abs()>. This means that it
-is taken to be relative to L<cwd()>.
-
-On systems with the concept of a volume, this assumes that both paths 
-are on the $base volume, and ignores the $destination 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</canonpath()>.
-
-Based on code written by Shigio Yamaguchi.
+See L<File::Spec::Unix/rel2abs> for general documentation.
 
-No checks against the filesystem are made. 
+Unlike C<File::Spec::Unix->rel2abs()>, this function will make
+checks against the local filesystem if necessary.  See
+L</file_name_is_absolute> for details.
 
 =cut
 
diff --git a/lib/File/Spec/Unix.pm b/lib/File/Spec/Unix.pm
index 6ca26d74ce..36036f3aae 100644
--- a/lib/File/Spec/Unix.pm
+++ b/lib/File/Spec/Unix.pm
@@ -3,7 +3,7 @@ package File::Spec::Unix;
 use strict;
 use vars qw($VERSION);
 
-$VERSION = '1.1';
+$VERSION = '1.2';
 
 use Cwd;
 
@@ -165,7 +165,12 @@ sub case_tolerant {
 
 =item file_name_is_absolute
 
-Takes as argument a path and returns true, if it is an absolute path.
+Takes as argument a path and returns true if it is an absolute path.
+
+This does not consult the local filesystem on Unix, Win32, or OS/2.  It
+does sometimes on MacOS (see L<File::Spec::MacOS/file_name_is_absolute>).
+It does consult the working environment for VMS (see
+L<File::Spec::VMS/file_name_is_absolute>).
 
 =cut
 
@@ -311,8 +316,8 @@ sub catpath {
 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( $destination ) ;
-    $rel_path = File::Spec->abs2rel( $destination, $base ) ;
+    $rel_path = File::Spec->abs2rel( $path ) ;
+    $rel_path = File::Spec->abs2rel( $path, $base ) ;
 
 If $base is not present or '', then L<cwd()> is used. If $base is relative, 
 then it is converted to absolute form using L</rel2abs()>. This means that it
@@ -328,9 +333,13 @@ directories.
 If $path is relative, it is converted to absolute form using L</rel2abs()>.
 This means that it is taken to be relative to L<cwd()>.
 
-Based on code written by Shigio Yamaguchi.
+No checks against the filesystem are made on most systems.  On MacOS,
+the filesystem may be consulted (see
+L<File::Spec::MacOS/file_name_is_absolute>).  On VMS, there is
+interaction with the working environment, as logicals and
+macros are expanded.
 
-No checks against the filesystem are made. 
+Based on code written by Shigio Yamaguchi.
 
 =cut
 
@@ -388,15 +397,15 @@ sub abs2rel {
 
 Converts a relative path to an absolute path. 
 
-    $abs_path = File::Spec->rel2abs( $destination ) ;
-    $abs_path = File::Spec->rel2abs( $destination, $base ) ;
+    $abs_path = File::Spec->rel2abs( $path ) ;
+    $abs_path = File::Spec->rel2abs( $path, $base ) ;
 
 If $base is not present or '', then L<cwd()> is used. If $base is relative, 
 then it is converted to absolute form using L</rel2abs()>. This means that it
 is taken to be relative to L<cwd()>.
 
 On systems with the concept of a volume, this assumes that both paths 
-are on the $base volume, and ignores the $destination volume. 
+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
@@ -404,9 +413,13 @@ directories.
 
 If $path is absolute, it is cleaned up and returned using L</canonpath()>.
 
-Based on code written by Shigio Yamaguchi.
+No checks against the filesystem are made on most systems.  On MacOS,
+the filesystem may be consulted (see
+L<File::Spec::MacOS/file_name_is_absolute>).  On VMS, there is
+interaction with the working environment, as logicals and
+macros are expanded.
 
-No checks against the filesystem are made. 
+Based on code written by Shigio Yamaguchi.
 
 =cut
 
diff --git a/lib/File/Spec/Win32.pm b/lib/File/Spec/Win32.pm
index b8fe37bbdb..8510d1ff36 100644
--- a/lib/File/Spec/Win32.pm
+++ b/lib/File/Spec/Win32.pm
@@ -5,7 +5,7 @@ use Cwd;
 use vars qw(@ISA $VERSION);
 require File::Spec::Unix;
 
-$VERSION = '1.1';
+$VERSION = '1.2';
 
 @ISA = qw(File::Spec::Unix);
 
@@ -242,34 +242,6 @@ sub catpath {
 }
 
 
-=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( $destination ) ;
-    $rel_path = File::Spec->abs2rel( $destination, $base ) ;
-
-If $base is not present or '', then L</cwd()> is used. If $base is relative, 
-then it is converted to absolute form using L</rel2abs()>. This means that it
-is taken to be relative to L<cwd()>.
-
-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</rel2abs()>.
-This means that it is taken to be relative to L</cwd()>.
-
-Based on code written by Shigio Yamaguchi.
-
-No checks against the filesystem are made. 
-
-=cut
-
 sub abs2rel {
     my($self,$path,$base) = @_;
 
@@ -339,31 +311,6 @@ sub abs2rel {
     ) ;
 }
 
-=item rel2abs
-
-Converts a relative path to an absolute path. 
-
-    $abs_path = File::Spec->rel2abs( $destination ) ;
-    $abs_path = File::Spec->rel2abs( $destination, $base ) ;
-
-If $base is not present or '', then L<cwd()> is used. If $base is relative, 
-then it is converted to absolute form using L</rel2abs()>. This means that it
-is taken to be relative to L</cwd()>.
-
-Assumes that both paths are on the $base volume, and ignores the 
-$destination 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</canonpath()>.
-
-Based on code written by Shigio Yamaguchi.
-
-No checks against the filesystem are made. 
-
-=cut
 
 sub rel2abs($;$;) {
     my ($self,$path,$base ) = @_;