Amend RFC 517: Add material on std::fs

Author: aturon

text/0517-io-os-reform.md

@@ -53,7 +53,11 @@ follow-up PRs against this RFC.
         * [core::io] (stub)
         * [The std::io facade] (stub)
         * [std::env] (stub)
-        * [std::fs] (stub)
+        * [std::fs]
+            * [Free functions]
+            * [Files]
+            * [File kinds]
+            * [File permissions]
         * [std::net] (stub)
         * [std::process] (stub)
         * [std::os]
@@ -708,7 +712,129 @@ throughout IO, we can go on to explore the modules in detail.
 ### `std::fs`
 [std::fs]: #stdfs
 
-> To be added in a follow-up PR.
+The `fs` module will provide most of the functionality it does today,
+but with a stronger cross-platform orientation.
+
+Note that all path-consuming functions will now take an
+`AsPath`-bounded parameter for ergonomic reasons (this will allow
+passing in Rust strings and literals directly, for example).
+
+#### Free functions
+[Free functions]: #free-functions
+
+**Files**:
+
+* `copy`. Take `AsPath` bound.
+* `rename`. Take `AsPath` bound.
+* `remove_file` (renamed from `unlink`). Take `AsPath` bound.
+
+* `file_attr` (renamed from `stat`). Take `AsPath` bound. Yield a new
+  struct, `FileAttr`, with no public fields, but `size`, `kind` and
+  `perm` accessors. The various `os::platform` modules will offer
+  extension methods on this structure.
+
+* `set_perm` (renamed from `chmod`). Take `AsPath` bound, and a
+  `FilePermissions` value. The `FilePermissions` type will be revamped
+  as a struct with private implementation; see below.
+
+**Directories**:
+
+* `make_dir` (renamed from `mkdir`). Take `AsPath` bound.
+* `make_dir_all` (renamed from `mkdir_recursive`). Take `AsPath` bound.
+* `read_dir` (renamed from `readdir`). Take `AsPath` bound. Yield a
+  newtypes iterator, which yields a new type `DirEntry` which has an
+  accessor for `Path`, but will eventually provide other information
+  as well (possibly via platform-specific extensions).
+* `remove_dir` (renamed from `rmdir`). Take `AsPath` bound.
+* `remove_dir_all` (renamed from `rmdir_recursive`). Take
+  `AsPath` bound.
+* `walk_dir`. Take `AsPath` bound. Yield an iterator over `IoResult<DirEntry>`.
+
+**Links**:
+
+* `hard_link` (renamed from `link`). Take `AsPath` bound.
+* `sym_link` (renamed from `symlink`). Take `AsPath` bound.
+* `read_link` (renamed form `readlink`). Take `AsPath` bound.
+
+#### Files
+[Files]: #files
+
+The `File` type will largely stay as it is today, except that it will
+use the `AsPath` bound everywhere.
+
+The `stat` method will be renamed to `attr`, yield a `FileAttr`, and
+take `&self`.
+
+The `fsync` method will be renamed to `flush`, and `datasync` will be
+renamed to `flush_data`. (Although the latter is not available on
+Windows, it can be considered an optimization for `flush` and on
+Windows behave identically to `flush`, just as it does on some Unix
+filesystems.)
+
+The `path` method wil remain `#[unstable]`, as we do not yet want to
+commit to its API.
+
+The `open_mode` function will take an `OpenOptions` struct, which will
+encompass today's `FileMode` and `FileAccess` and support a
+builder-style API.
+
+#### File kinds
+[File kinds]: #file-kinds
+
+The `FileType` module will be renamed to `FileKind`, and the
+underlying `enum` will be hidden (to allow for platform differences
+and growth). It will expose at least `is_file` and `is_dir`; the other
+methods need to be audited for compatibility across
+platforms. Platform-specific kinds will be relegated to extension
+traits in `std::os::platform`.
+
+#### File permissions
+[File permissions]: #file-permissions
+
+The permission models on Unix and Windows vary greatly -- even between
+different filesystems within the same OS. Rather than offer an API
+that has no meaning on some platforms, we will initially provide a
+very limited `FilePermissions` structure in `std::fs`, and then rich
+extension traits in `std::os::unix` and `std::os::windows`. Over time,
+if clear cross-platform patterns emerge for richer permissions, we can
+grow the `FilePermissions` structure.
+
+On the Unix side, the constructors and accessors for `FilePermissions`
+will resemble the flags we have today; details are left to the implementation.
+
+On the Windows side, initially there will be no extensions, as Windows
+has a very complex permissions model that will take some time to build
+out.
+
+For `std::fs` itself, `FilePermissions` will provide constructors and
+accessors for "world readable" -- and that is all. At the moment, that
+is all that is known to be compatible across the platforms that Rust
+supports.
+
+#### `PathExt`
+[PathExt]: #pathext
+
+This trait will essentially remain stay as it is (renamed from
+`PathExtensions`), following the same changes made to `fs` free functions.
+
+#### Items to move to `os::platform`
+
+* `change_file_times` will move to `os::unix` and remain `#[unstable]`
+  *for now* (cf `SetFileTime` on Windows). Eventually we will add back
+  a cross-platform function, when we have grown a notion of time in
+  `std` and have a good compatibility story across all platforms.
+
+* `lstat` will move to `os::unix` and remain `#[unstable]` *for now*
+  since it is not yet implemented for Windows.
+
+* `chown` will move to `os::unix` (it currently does *nothing* on
+  Windows), and eventually `os::windows` will grow support for
+  Windows's permission model. If at some point a reasonable
+  intersection is found, we will re-introduce a cross-platform
+  function in `std::fs`.
+
+* In general, offer all of the `stat` fields as an extension trait on
+  `FileAttr` (e.g. `os::unix::FileAttrExt`).
 
 ### `std::net`
 [std::net]: #stdnet