[m-rev.] for review: library changes for `mmc --make' on Windows

[Fergus Henderson]

On 23-Jun-2003, Simon Taylor <stayl at cs.mu.OZ.AU> wrote:
> 	% dir__split_name(PathName, DirName, BaseName)
> 	% Split a filename into a directory part and a filename part.
> 	% Fails for root directories and filenames not containing
> 	% directory information.
> 	% Trailing slashes are removed from PathName before splitting.
> :- pred dir__split_name(string, string, string).
> :- mode dir__split_name(in, out, out) is semidet.
> 
> 	% dir__dirname(PathName) = DirName
> 	% Extract the directory part of the given filename.
> 	% Fails for root directories.
> 	% Returns "." for filenames not containing directory information.
> 	% Trailing slashes are removed from PathName before splitting.
> :- func dir__dirname(string) = string is semidet.

The documentation for these two should be more explicit about if/when
DirName will contain a trailing slash.

Also, the documentation for dir__make_path_name/2 (a.k.a. '/'/2)
should be more explicit about what happens if the first argument
does / does not contain a trailing slash (or, for that matter,
what happens if the second argument contains slashes).

If dir__dirname("foo/bar") returns "foo/" (note trailing slash),
then presumably dir__dirname("./bar") returns "./",
so shouldn't dir__dirname("bar") return "./" too, rather than "."?

> 	% dir__basename(PathName) = BaseName
> 	% Extract the filename part of the given filename.
> 	% Fails for root directories.
> 	% Trailing slashes are removed from PathName before splitting.
> :- func dir__basename(string) = string is semidet.
> 
> > I think the documentation for the dir foldl preds should say something
> > about order.  For the recursive versions, it's worth specifying that
> > parents are processed before their children.  For children, perhaps
> > state that there are no order guarantees.  I'm tempted to specify that
> > it's the same order as given by the underlying platform's
> > directory-reading function.  (This has useful properties for many
> > filesystems, in some cases even lexical ordering.)
> 
> I'd rather not give any guarantees about ordering -- this is meant
> to be a high level interface.

In that case, the documentation should explicitly state that the ordering
is unspecified.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------