Re: [boost] [filesystem] Function name changes

From: Beman Dawes (bdawes_at_[hidden])
Date: 2008-07-03 14:29:12

David Abrahams wrote:
> Beman Dawes wrote:
>> All the changes mentioned below leave the current names in place as
>> synonyms, so will break no existing code.
>>
>> * Change is_regular() to is_regular_file().
>>
>> Dave Abrahams and several other people, including me, have found that
>> the name of the is_regular() function is too obscure. It was chosen over
>> is_regular_file() for brevity, but isn't holding up well with
>> experience. The status name is already "regular_file" and the term
>> "regular file" is used by the POSIX standard.
>>
>> * Change leaf() to base_name().
>> * Change branch() to base_path().
> 
> What does the latter do, again?  Oh, yeah, it returns the path to the
> directory containing the file indicated by the path object.
> 
> I'm sorry, but I don't like base_path() much.  We know it is going to
> return a path, so the "path" part of the name doesn't tell me much about
> what this function does.  The only thing left to go on is the meaning of
> "base."
> 
> Well I'm afraid we don't know what that is.  The (only) good reason to
> use base_name() is that there is precedent; it's not because it makes
> particularly "good sense." You yourself find it counterintuitive, IIUC.

That's correct. I'm only suggesting it because of the precedent.

>  If "base" _did_ make any sense, I would guess that base_path() was the
> identity function.
> 
> How about parent_directory(), containing_directory(), container_path(),
> container(), or parent()?

The objection raised in the discussion to the names with "parent" is 
that the resulting path is only the parent path in the absence of 
symbolic links. Same objection would apply to your other suggestions. 
Maybe that isn't all that strong an argument; parent_path() is quite 
clear to me and fits into the overall naming scheme. The impact of 
symlinks may just be a quirk we can live with.

parent_directory() or parent() always look to me like they refer to one 
level up only.

>> In the long thread '[filesystem] "leaf"', several people found the
>> current names obscure or invoking the wrong metaphor. Many alternative
>> names were discussed, with an eye to making the names more obvious,
>> conforming to names such as "basename" used in other programming
>> languages, and/or using names already in use by the STL.  Not breaking
>> existing code was also a major concern, given that "basename" is already
>> used in Boost.Filesystem.
>>
>> The mental model for the new names is that for a path, p:
>>
>>    p == p.base_path() / p.base_name()
>>
>> Thus if p == "foo/bar/boo.txt", p.base_path() == "foo/bar", and
>> p.base_name() == "boo.txt".
>>
>> * Change basename() to base_name_prefix().
>> * Change to extension() to base_name_extension().
>>
>> This change is to avoid confusion with base_name().
> 
> Works for me.
> 
>> The mental model for the new name is that for a path, p:
>>
>>    p.base_name() == base_name_prefix(p) + base_name_extension(p)
>>
>> Thus if p == "foo/bar/boo.txt", base_name_prefix(p) == "boo", and
>> base_name_extension(p) == ".txt".
>>
>> Comments?
> 
> I worry a bit about the chance of silent misbehavior due to
> basename/base_name spelling errors, and about what happens when both
> names make it into the same codebase.

I don't like that either, but (1) there doesn't seem much choice if 
"base*" is to be the new name, and (2) the problem doesn't last 
indefinitely since the deprecated form of the names would go away in say 
one year.

--Beman