File and Metadata should document reasons to prefer *not* to use `is_file()`

[kentfredric]

As per rust-lang/rust-clippy#4503, there's a bit of a trap you can fall into if you use is_file() as a predictor for "can I probably open and read bytes from this thing".

You generally don't want to assert is_file() for user specified paths, especially if they come from command line arguments, where they might be Unix FIFO File Descriptors.

If for example you were implementing cat in rust, using is_file() instead of !is_dir() would prevent you from reading block devices, character devices, pipes, and more:

           S_IFSOCK   0140000   socket
           S_IFLNK    0120000   symbolic link
           S_IFREG    0100000   regular file
           S_IFBLK    0060000   block device
           S_IFDIR    0040000   directory
           S_IFCHR    0020000   character device
           S_IFIFO    0010000   FIFO

And this would break your ability to be composed nicely in Unix flows where patterns like:

diff <( prog_a ) <( prog_b )

Would become broken if diff was a rust program that ensured all its arguments were is_file()

[the8472]

This isn't specific to is_file(). When you build tools that recurse into directories you also may or may not want to skip symlinks. If you write archives you may need special handling for non-regular files and so on. CLI tools often also probe whether a stdout is a TTY or something else to adjust their behavior for interactive or non-interactive mode or to avoid breaking the console with binary data interpreted as escape sequences.

I think it would be better to add a more general warning to the top-level documentation that symlink/file/directory is not exhaustive and one has to take the platform-extensions into account if one wants to deal with arbitrary user-provided files or directory-trees.

[kentfredric]

This isn't specific to is_file(). When you build tools that recurse into directories you also may or may not want to skip symlinks. If you write archives you may need special handling for non-regular files and so on. CLI tools often also probe whether a stdout is a TTY or something else to adjust their behavior for interactive or non-interactive mode or to avoid breaking the console with binary data interpreted as escape sequences.

I think it would be better to add a more general warning to the top-level documentation that symlink/file/directory is not exhaustive and one has to take the platform-extensions into account if one wants to deal with arbitrary user-provided files or directory-trees.

Sure, as long as the documentation conveys "If you are using this for usecase X, then !is_dir() is probably more appropriate".

Just because the average novice programmer who first encounters the need to differentiate that a given thing is what they consider to be "a file", and they'll point is_file() at it, reducing their usefulness without realizing it.

( People have been making this mistake in many languages for a long time, and it would be nice if rust had some way to encourage better systems development in this regard, good docs and applicable lints would go far )