Re: [boost] [Filesystem] Native Pathname Format

From: Edward Diener (eldiener_at_[hidden])
Date: 2007-09-01 21:23:53

Beman Dawes wrote:
> Edward Diener wrote:
>> I can not determine from the Filesystem documentation, nor the reference
>> documentation which comes with it, what is the acceptable syntax for the
>> native pathname format. It appears one must start the native pathname
>> format with //: in order for it to be recognized,
> 
> The explicit //: form is not needed for POSIX, Windows, and most other 
> operating systems since their native syntax will implicitly be 
> recognized. The explicit //: form is only needed if you are dealing with 
> an operating system where a slash is a valid part of a name, rather than 
> a separator.

Thanks for this information. Can what you say above not be documented as 
part of the documentation for boost::filesystem ?

> 
>> but I can not tell
>> from what appears to me to be very confusing documentation whether this
>> is so for the Boost Fileystem implementation. This would mean, let's say
>> under Windows, that "c:\afile" would not be recognized but that
>> "//:c:\afile" would be recognized, as far as I can make out from the
>> documentation. It sure is confusing IMO.
> 
> I think you meant "c:\\afile".

No I meant what I wrote because the documentation implied that a prefix 
escape sequence of "//:" was needed in order to specify a native 
pathname format and I was not attempting to treat my pathnames mentioned 
above as C/C++ string literals where an escaping \ had to be used for an 
actual backslash.

> On Windows, "c:\\afile" will be 
> recognized correctly. AFAIK, there are no cases for either Windows or 
> POSIX-like operating systems where the Boost implementation will fail to 
> implicitly recognize the native format.

OK, but it would be nice if the documentation actually said the above 
somewhere.

> 
>> Can anybody clarify how this works for Filesystem and/or where there is
>> a clear explanation of how it works in the documentation ?
> 
> I assume you have read 
> http://www.boost.org/libs/filesystem/doc/tr2_proposal.html#Pathname-formats
> 
> If so, and you still have questions, please post them here.

The confusing part of the documentation resides at that link. I quote:

"All basic_path string or sequence arguments that describe a path shall 
accept the portable pathname format, and shall accept the native format 
if explicitly identified by a native format escape sequence prefix of 
slash slash colon.

     [Note: slash slash colon was chosen as the escape sequence because 
a leading slash slash  is already implementation-defined by POSIX, colon 
is prohibited in a Windows filename, and on any system a single slash 
can be used when a filename beginning with a colon is desired. These 
factors eliminate the chance of collision with a real filename. -- end note]

Implementations are encouraged to implicitly recognize the native 
pathname format if it can be lexically identified. An implementation 
shall document whether or not the native pathname format is implicitly 
recognized."

In the first paragraph above it tells me I need "a native format escape 
sequence prefix of slash slash colon" for a native format.

In the second paragraph it tells me why slash slash colon was chosen.

In the third paragraph, second sentence, it tells me that an 
"implementation shall document whether or not the native pathname format 
is implicitly recognized." I assume boost::filesystem is such an 
implementation. Where in the boost::filesystem docs does it tell me that 
  the native pathname format for Windows ( or any specific OS ) is 
implicitly recognized and therefore does not require a prefixed slash 
slash colon to denote it ?

This last question is the crux of my problem in understanding how the 
native pathname format works under boost::filesystem. While you have 
told me how it actually works above, so now I know, I think you need to 
say in the documentation, loud and clear, the same thing, else it is 
confusing to anyone trying to understand the actual way the native 
pathname format works for boost::filesystem.

If it is said in the documentation, loud and clear, I apologize in advance.

Thanks !

Eddie