Front page | perl.perl5.porters |
Postings from March 2000
[PATCH RC2] File::Spec::Unix::splitpath() doc.
From:
Barrie Slaymaker
Date:
March 16, 2000 10:56
Subject:
[PATCH RC2] File::Spec::Unix::splitpath() doc.
Message ID:
38D12E3C.CC9A0AB3@slaysys.com
Steven Knight wrote, in part:
>
> I've cc'ed Barrie Slaymaker on this reply, as he's taken over maintenance
> of File::Spec.
Not really--it's in the tender hands of perl5-porters. I'm just a
contributor to it. And the cause of Johan's confusion, apparently :-/
> On Thu, 16 Mar 2000, Johan Holmberg wrote:
>
> > I agree that a common interface for manipulation of
> > filenames/paths on different platforms is a good thing.
> >
> > But, I must say I'm a bit disappointed by File::Spec. The
> > documentation is rather poor, and the *sematics* of
> > the different functions are not very well described.
Very true & mea culpa, partly. If you can dig in and make them
better, patches may be sent to perl5-porters@perl.org [CCed]. If not,
even just sending questions or suggestioned documentation there. A really
good pass at the documentation including a tutorial section in Spec.pm's
POD would be a major improvement.
> > One example (from File::Spec::Unix):
> > >
> > > File::Spec->splitdir( "/a/b/c" );
> > >
> > > Yields:
> > >
> > > ( '', 'a', 'b', '', 'c', '' )
> > >
> >
> > This is wrong. When I try it I get:
> >
> > ( '', 'a', 'b', 'c' )
>
> You're correct, this example is wrong. I had the same confusion when
> I was trying to figure out how to use File::Spec, and almost decided to
> *not* use File::Spec because of this! I couldn't understand the example,
> and thought that maybe that meant I wasn't using an appropriate package...
Eeek--this was my bad from the getgo. Sorry about that.
> I already brought this to Barrie's attention, and believe he's fixed
> the documentation in the latest versions.
I should have... patch below.
> > Another example: If I execute the following:
> >
> > $path = "/a/b/c";
> > ($volume,$dirs,$name) = File::Spec->splitpath($path);
> >
> > @dirs1 = File::Spec->splitdir($dirs);
> > print "dirs1: ",join(", ", map("'$_'",@dirs1)),"\n";
> >
> > @dirs2 = File::Spec->splitdir(File::Spec->catdir(@dirs1));
> > print "dirs2: ",join(", ", map("'$_'",@dirs2)),"\n";
> >
> > I get this output:
> >
> > dirs1: '', 'a', 'b', ''
> > dirs2: '', 'a', 'b'
> >
> > Why are these different ?
catdir() calls canonpath() which removes the trailing '/' on Unix.
> > Why the trailing empty component in the first case ?
> > Why doesn't splitpath remove the trailing / on the directory component ?
I think these are the same question asked two ways.
splitpath() returns ( '', '/a/b/', 'c' ). The main reason for the trailing
'/' is not to throw information away. Even though the trailing '/' is not
necessary, it can be nice to have as a marker of dir-ness. OTOH, consistency
may be the better part of valor here, and having $dirs[-1] be the last name
is compelling.
> > To me this seems very weird.
> > Without information about the intended sematics, I'm almost
> > totally lost ...
> >
> > I ask you about this because I got the impression from the cons-list
> > that you "liked" File::Spec. Maybe I should direct my questions
> > elsewere, but I'm also interested in your view about these things.
>
> I agree with you that File::Spec needs some better documentation about
> its semantics--that would probably help clear up a lot of confusion,
> and would have saved time when I started trying to use.
>
> I've adopted File::Spec largely because that's very clearly the direction
> that Perl is heading--if you read through the perl5-porters mailing
> list, everyone is recommending that file name manipulation be done
> using File::Spec. It's still young, and needs work
It's not that young, it grew out of some older code in Make::Maker.
But it's seeing wider use now and feeping creaturism, for which I
must take some of the blame :-).
>
> I've found Barrie to be extremely helpful and cooperative,
Rats, gotta work harder on being unresponsive. Thanks :-).
> so if you are
> able to contribute something (documentation fixes, etc.), I'm sure he'd
> be receptive.
More importantly, perl5-porters would be very receptive.
- Barrie
---------------------------8<-------------------------
--- perl-5.6.0-RC2/lib/File/Spec/Unix.pm Thu Mar 2 21:54:21 2000
+++ File-Spec/lib/File/Spec/Unix.pm Thu Mar 16 13:49:27 2000
@@ -242,11 +242,13 @@
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, leading empty and
-trailing directory entries can be returned, because these are significant
-on some OSs. So,
+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).
- File::Spec->splitdir( "/a/b/c" );
+On Unix,
+
+ File::Spec->splitdir( "/a/b//c/" );
Yields:
-
[PATCH RC2] File::Spec::Unix::splitpath() doc.
by Barrie Slaymaker