RE: [boost] filesystem/directory example [was: ... header redux]

From: Stewart, Robert (stewart_at_[hidden])
Date: 2002-04-09 13:13:06

From: Beman Dawes [mailto:bdawes_at_[hidden]]
> 
> Notice the find_file function:
> 
> //  find_file  ------------------------------------------//
> //  given a directory to recursively search
> 
>    bool find_file( const string & dir_path, const string & name,
>      string & path_found, const string & ignore_dir_named="" )

In my experience, output parameters such as path_found, are better put first
in the argument list, so they are grouped -- should there be more than one
-- and so they are always in an expected position.  I tried putting them
last, but that interfered with default arguments.  Putting them first also
associates them with the return value of the function (in a manner of
speaking, anyway).

(I'm mentioning this so that you consider it for find_file() but also any
other functions you may write for the library.)

>    {
>      for ( fs::directory_iterator itr( dir_path );
>            itr != end_itr; ++itr )
>        if ( fs::is_directory( itr->path() )
>          && itr->name() != ignore_dir_named )
>        {
>          if ( find_file( itr->path(), name, path_found ) )
>             return true;
>        }
>        else if ( itr->name() == name )
>        {
>          path_found = itr->path();
>          return true;
>        }
>      return false;
>    }
> 
> This is a convenience function we never envisioned when we 
> were talking 
> about remove, copy, etc.  But it was so easy to write (and then later 
> hack by adding the argument ignore_dir_named so the code could be 
> reused.)

Looking at this code, I find myself a bit confused by the terminology you
have selected.  I was troubled when I read your list (on the filesystem
design page you posted), but didn't quite know what was wrong.  Here are the
terms I use:

drive/volume/share, etc. - system-specific names for some logical unit of
storage in which a filesystem can be managed

directory - a filesystem entry that groups other directories or files

file - an ordinary file, such as a text file, or, if supported by the
filesystem, a directory, printer, terminal, etc.

path - a filesystem location, which is a possibly empty set of directories,
and which may include drive/volume/share, but does not include a filename

filename - a file's name, including any suffix/extension

basename - a filename minus suffix/extension, if any

suffix/extension - the portion of a filename following the final "." if any

pathname - a path plus a filename

relative path[name] - a composed set of one or more directory, without [a
filename or] a drive, volume, share, etc., and without a leading directory
separator

absolute path[name] - a composed set of one or more directory, [without a
filename,] starting with a directory separator, optionally including a
drive, volume, share, etc.

That list doesn't include a special name for a composed set of directories,
without a filename or information on the drive, volume, share, etc., which
is probably useful.

I think that's a pretty standard set of terms, at least for those from a
Unix/Posix/DOS background.  The names you've created confuse me because
you've created different names that overlap some of the concepts I've listed
above.  The names chosen for these concepts, indeed the concepts represented
in the filesystem library, are important.  At the moment, they are a little
strange to me.

Let me explain my concerns with your set of names.  You distinguish between
a directory path and a file path, and those include filename.  Both of those
are pathnames to me.  If you think the distinction is really important, I
suggest that they be called "dirpathname" and "filepathname," though I'd
just call them directory pathname and file pathname, when the distinction
was important.  You use "name" rather than "filename" which is more common.
I don't see that "dirname" is important; I'd just use "directory name."
Your "filename" is more restrictive than mine, and so leads to confusion.
You define "path," but don't indicate whether it includes drive, volume,
share, etc. information.  That distinction is important.

You don't include the terms "basename," "suffix," "extension," "drive,"
"share," or "volume," and rightly so, since they would apply to the pathname
manipulation portion of the library.

So, I think the terms you should define are: file, directory, path,
filename, pathname, relative, and absolute.

> Now you could say boost/filesystem/directory.hpp should contain a 
> generalized version of such a function.  You could also say "Look how 
> simple find_file() is! Maybe it shows we don't need the generalized 
> copy() and replace() functions at all!"

I agree with Jan and what you're implying here: we should concentrate on the
core functionality first.  However, to know that we've got it right, we need
to implement various convenience functions.  Once we have the convenience
functions, we can package them appropriately and submit them separately.
This also leads to two separate submissions to the standard committee: core
filesystem library and high level, convenience filesystem library.  If only
the core is standardized, we're still better off.

Rob
Susquehanna International Group, LLP
http://www.sig.com

IMPORTANT:The information contained in this email and/or its attachments is
confidential. If you are not the intended recipient, please notify the
sender immediately by reply and immediately delete this message and all its
attachments.  Any review, use, reproduction, disclosure or dissemination of
this message or any attachment by an unintended recipient is strictly
prohibited.  Neither this message nor any attachment is intended as or
should be construed as an offer, solicitation or recommendation to buy or
sell any security or other financial instrument.  Neither the sender, his or
her employer nor any of their respective affiliates makes any warranties as
to the completeness or accuracy of any of the information contained herein
or that this message or any of its attachments is free of viruses.