Commit 17bc1f62a51ad5fc44dc97acf6ddb33e6d00b0c4 | zig

author	Jonathan S <gereeter+code@gmail.com> 2019-11-22 15:40:46-06:00
committer	Andrew Kelley <andrew@ziglang.org> 2019-11-25 23:46:47-05:00
log	17bc1f62a51ad5fc44dc97acf6ddb33e6d00b0c4
tree	23da0acda6763db992cb729110761c756d5fa0f2
parent	f96d818770fa8264b7b87e55ef7e01ff5df44c77

Split `std.fs.Dir.openDir` into `openDirList` and `openDirTraverse` to clarify what directories can be iterated. Closes ziglang/zig#3741.

The Windows-inspired nomenclature of "List" and "Traverse" was chosen over POSIX-style "Read" and "Path" (from `O_PATH`) for clarity. Using "Path" makes it look like the function is manipulating strings, and the generic "Read" ending isn't useful when there is no generic read method. Even in implementation details, `read` is never used.

Actual exploitation of the difference between the two functions will come in a later commit.

1 files changed, 56 insertions(+), 14 deletions(-)

lib
- std
  - fs.zig

lib/std/fs.zig+56-14

 @@ -657,8 +657,8 @@ pub const Dir = struct {
         }
     }
-    /// Returns an open handle to the current working directory.
+    /// Returns an handle to the current working directory that is open for traversal.
-    /// Closing the returned `Dir` is checked illegal behavior.
+    /// Closing the returned `Dir` is checked illegal behavior. Iterating over the result is illegal behavior.
     /// On POSIX targets, this function is comptime-callable.
     pub fn cwd() Dir {
         if (builtin.os == .windows) {
 @@ -683,14 +683,14 @@ pub const Dir = struct {
         DeviceBusy,
     } || os.UnexpectedError;
-    /// Call `close` to free the directory handle.
+    /// Deprecated; call `Dir.cwd().openDirList` directly.
     pub fn open(dir_path: []const u8) OpenError!Dir {
-        return cwd().openDir(dir_path);
+        return cwd().openDirList(dir_path);
     }
-    /// Same as `open` except the parameter is null-terminated.
+    /// Deprecated; call `Dir.cwd().openDirListC` directly.
     pub fn openC(dir_path_c: [*:0]const u8) OpenError!Dir {
-        return cwd().openDirC(dir_path_c);
+        return cwd().openDirListC(dir_path_c);
     }
     pub fn close(self: *Dir) void {
 @@ -775,22 +775,57 @@ pub const Dir = struct {
         }
     }
-    /// Call `close` on the result when done.
+    /// Deprecated; call `openDirList` directly.
     pub fn openDir(self: Dir, sub_path: []const u8) OpenError!Dir {
+        return self.openDirList(sub_path);
+    }
+    /// Deprecated; call `openDirListC` directly.
+    pub fn openDirC(self: Dir, sub_path_c: [*:0]const u8) OpenError!Dir {
+        return self.openDirListC(sub_path_c);
+    }
+    /// Opens a directory at the given path with the ability to access subpaths
+    /// of the result. Calling `iterate` on the result is illegal behavior; to
+    /// list the contents of a directory, open it with `openDirList`.
+    ///
+    /// Call `close` on the result when done.
+    pub fn openDirTraverse(self: Dir, sub_path: []const u8) OpenError!Dir {
         if (builtin.os == .windows) {
             const sub_path_w = try os.windows.sliceToPrefixedFileW(sub_path);
-            return self.openDirW(&sub_path_w);
+            return self.openDirTraverseW(&sub_path_w);
         }
         const sub_path_c = try os.toPosixPath(sub_path);
-        return self.openDirC(&sub_path_c);
+        return self.openDirTraverseC(&sub_path_c);
     }
-    /// Same as `openDir` except the parameter is null-terminated.
+    /// Opens a directory at the given path with the ability to access subpaths and list contents
-    pub fn openDirC(self: Dir, sub_path_c: [*:0]const u8) OpenError!Dir {
+    /// of the result. If the ability to list contents is unneeded, `openDirTraverse` acts the
+    /// same and may be more efficient.
+    ///
+    /// Call `close` on the result when done.
+    pub fn openDirList(self: Dir, sub_path: []const u8) OpenError!Dir {
+        if (builtin.os == .windows) {
+            const sub_path_w = try os.windows.sliceToPrefixedFileW(sub_path);
+            return self.openDirListW(&sub_path_w);
+        }
+        const sub_path_c = try os.toPosixPath(sub_path);
+        return self.openDirListC(&sub_path_c);
+    }
+    /// Same as `openDirTraverse` except the parameter is null-terminated.
+    pub fn openDirTraverseC(self: Dir, sub_path_c: [*:0]const u8) OpenError!Dir {
+        // TODO: use O_PATH where supported
+        return self.openDirListC(sub_path_c);
+    }
+    /// Same as `openDirList` except the parameter is null-terminated.
+    pub fn openDirListC(self: Dir, sub_path_c: [*:0]const u8) OpenError!Dir {
         if (builtin.os == .windows) {
             const sub_path_w = try os.windows.cStrToPrefixedFileW(sub_path_c);
-            return self.openDirW(&sub_path_w);
+            return self.openDirListW(&sub_path_w);
         }
         const flags = os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC;
 @@ -804,9 +839,16 @@ pub const Dir = struct {
         return Dir{ .fd = fd };
     }
-    /// Same as `openDir` except the path parameter is UTF16LE, NT-prefixed.
+    /// Same as `openDirTraverse` except the path parameter is UTF16LE, NT-prefixed.
+    /// This function is Windows-only.
+    pub fn openDirTraverseW(self: Dir, sub_path_w: [*:0]const u16) OpenError!Dir {
+        // TODO: open without FILE_LIST_DIRECTORY
+        return self.openDirListW(sub_path_w);
+    }
+    /// Same as `openDirList` except the path parameter is UTF16LE, NT-prefixed.
     /// This function is Windows-only.
-    pub fn openDirW(self: Dir, sub_path_w: [*:0]const u16) OpenError!Dir {
+    pub fn openDirListW(self: Dir, sub_path_w: [*:0]const u16) OpenError!Dir {
         const w = os.windows;
         var result = Dir{