On 4/08/2015 04:31, Niall Douglas wrote:
On 3 Aug 2015 at 16:38, Gavin Lambert wrote:
There is a single page "cheat sheet" at https://boostgsoc13.github.io/boost.afio/doc/html/afio/overview.html.
It would be nice if this included hyperlinks for the local types. I have no idea what a directory_entry looks like.
Fixed. Each operation on the cheat sheet now lists what types are related to it.
Nice, thanks.
(And even after manually navigating around the docs until I found https://boostgsoc13.github.io/boost.afio/doc/html/afio/reference/classes/dir..., I still have no idea what those fields actually *mean*. Only because you mentioned it below did I also find https://boostgsoc13.github.io/boost.afio/doc/html/afio/reference/structs/sta..., which is more descriptive. Although I later went back and noticed I overlooked fetch_lstat on directory_entry. Another case where hyperlinks would have been nice.)
Fixed. Each reference page now links to related types too.
They still seem to be missing on the function reference pages (I checked https://boostgsoc13.github.io/boost.afio/doc/html/afio/reference/functions/e...), which is probably where they'd be the most useful. I'm used to the style of the Boost.Asio docs (eg. http://www.boost.org/doc/libs/1_58_0/doc/html/boost_asio/reference/async_rea...), where all the types are linked directly in the method description. (Of course, mostly they're templates, but still...)
I would prefer to not report something as a symlink when target() won't work with it. So you now have an additional stat_t flag called st_reparse_point which is always the FILE_ATTRIBUTE_REPARSE_POINT flag.
I guess that depends on usage cases -- if it's most common to write code like if (type() == symlink_file) { do something with target(); } then you have a point. Although code that has sufficient error checking should be able to cope with the idea of a symlink that has an unreadable target. But it seems odd to me to claim that a file is *not* a symlink just because you're told that it's a type of symlink that you don't know how to read. Having said that, I don't know how common custom symlinks are in the wild, or if they even exist at all.
AFIO is a bit caught here too actually. If you're enumerating a directory you have no easy way of disambiguating between a symlink to a directory and a symlink to a file. You basically have to try opening it as a directory, and if it errors out you then open it as a file.
Windows does supply what kind of symlink it is without additional syscalls, but POSIX does not. You'd have to do two syscalls per entry to disambiguate which is very costly for something so niche.
Perhaps rather than just having symlink_file, Filesystem should have symlink_file, symlink_directory, and symlink_entry? POSIX would return the latter (indicating that it's unknown whether it's a file or directory) while Windows would return one of the first two. This would still allow code to be written in a reasonably platform-independent manner. Another option might be for stat_t to have a field that contains the OS-native flags, so that on Windows the DIRECTORY flag could be examined directly. This might also allow for other esoteric attributes (COMPRESSED, ENCRYPTED, NOT_CONTENT_INDEXED, etc) to be inspected/set as desired, although that's probably more useful in Filesystem rather than AFIO. Although I think this is uglier than the above for the enumeration case.