Commit 760127a7608f671daa60668a3c60a18058adff13 | zig

author	Ryan Liptak <squeek502@hotmail.com> 2025-09-24 16:17:51-07:00
committer	Ryan Liptak <squeek502@hotmail.com> 2025-10-03 16:29:08-07:00
log	760127a7608f671daa60668a3c60a18058adff13
tree	aac4a7ba0c391b6862c120389831ce61d05fc94d
parent	07c3f9ef8e0a5a557dce70322334b0d1b49fe154

Add SelectiveWalker/walkSelectively and implement Walker in terms of it

This is a breaking change, since the fields of Walker have changed. The function APIs are unchanged, though.

2 files changed, 168 insertions(+), 55 deletions(-)

lib
- std
  - fs
    Dir.zig
    test.zig

lib/std/fs/Dir.zig+107-55

 @@ -663,35 +663,17 @@ fn iterateImpl(self: Dir, first_iter_start_value: bool) Iterator {
     }
 }
-pub const Walker = struct {
+pub const SelectiveWalker = struct {
-    stack: std.ArrayListUnmanaged(StackItem),
+    stack: std.ArrayListUnmanaged(Walker.StackItem),
     name_buffer: std.ArrayListUnmanaged(u8),
     allocator: Allocator,
-    pub const Entry = struct {
-        /// The containing directory. This can be used to operate directly on `basename`
-        /// rather than `path`, avoiding `error.NameTooLong` for deeply nested paths.
-        /// The directory remains open until `next` or `deinit` is called.
-        dir: Dir,
-        basename: [:0]const u8,
-        path: [:0]const u8,
-        kind: Dir.Entry.Kind,
-    };
-    const StackItem = struct {
-        iter: Dir.Iterator,
-        dirname_len: usize,
-    };
     /// After each call to this function, and on deinit(), the memory returned
     /// from this function becomes invalid. A copy must be made in order to keep
     /// a reference to the path.
-    pub fn next(self: *Walker) !?Walker.Entry {
+    pub fn next(self: *SelectiveWalker) !?Walker.Entry {
-        const gpa = self.allocator;
+        while (self.stack.items.len > 0) {
-        while (self.stack.items.len != 0) {
+            const top = &self.stack.items[self.stack.items.len - 1];
-            // `top` and `containing` become invalid after appending to `self.stack`
-            var top = &self.stack.items[self.stack.items.len - 1];
-            var containing = top;
             var dirname_len = top.dirname_len;
             if (top.iter.next() catch |err| {
                 // If we get an error, then we want the user to be able to continue
 @@ -703,36 +685,22 @@ pub const Walker = struct {
                     item.iter.dir.close();
                 }
                 return err;
-            }) |base| {
+            }) |entry| {
                 self.name_buffer.shrinkRetainingCapacity(dirname_len);
                 if (self.name_buffer.items.len != 0) {
-                    try self.name_buffer.append(gpa, fs.path.sep);
+                    try self.name_buffer.append(self.allocator, fs.path.sep);
                     dirname_len += 1;
                 }
-                try self.name_buffer.ensureUnusedCapacity(gpa, base.name.len + 1);
+                try self.name_buffer.ensureUnusedCapacity(self.allocator, entry.name.len + 1);
-                self.name_buffer.appendSliceAssumeCapacity(base.name);
+                self.name_buffer.appendSliceAssumeCapacity(entry.name);
                 self.name_buffer.appendAssumeCapacity(0);
-                if (base.kind == .directory) {
+                const walker_entry: Walker.Entry = .{
-                    var new_dir = top.iter.dir.openDir(base.name, .{ .iterate = true }) catch |err| switch (err) {
+                    .dir = top.iter.dir,
-                        error.NameTooLong => unreachable, // no path sep in base.name
-                        else => |e| return e,
-                    };
-                    {
-                        errdefer new_dir.close();
-                        try self.stack.append(gpa, .{
-                            .iter = new_dir.iterateAssumeFirstIteration(),
-                            .dirname_len = self.name_buffer.items.len - 1,
-                        });
-                        top = &self.stack.items[self.stack.items.len - 1];
-                        containing = &self.stack.items[self.stack.items.len - 2];
-                    }
-                }
-                return .{
-                    .dir = containing.iter.dir,
                     .basename = self.name_buffer.items[dirname_len .. self.name_buffer.items.len - 1 :0],
                     .path = self.name_buffer.items[0 .. self.name_buffer.items.len - 1 :0],
-                    .kind = base.kind,
+                    .kind = entry.kind,
                 };
+                return walker_entry;
             } else {
                 var item = self.stack.pop().?;
                 if (self.stack.items.len != 0) {
 @@ -743,20 +711,44 @@ pub const Walker = struct {
         return null;
     }
-    pub fn deinit(self: *Walker) void {
+    /// Traverses into the directory, continuing walking one level down.
-        const gpa = self.allocator;
+    pub fn enter(self: *SelectiveWalker, entry: Walker.Entry) !void {
-        // Close any remaining directories except the initial one (which is always at index 0)
+        if (entry.kind != .directory) {
-        if (self.stack.items.len > 1) {
+            @branchHint(.cold);
-            for (self.stack.items[1..]) |*item| {
+            return;
-                item.iter.dir.close();
+        }
+        var new_dir = entry.dir.openDir(entry.basename, .{ .iterate = true }) catch |err| {
+            switch (err) {
+                error.NameTooLong => unreachable,
+                else => |e| return e,
             }
+        };
+        errdefer new_dir.close();
+        try self.stack.append(self.allocator, .{
+            .iter = new_dir.iterateAssumeFirstIteration(),
+            .dirname_len = self.name_buffer.items.len - 1,
+        });
+    }
+    pub fn deinit(self: *SelectiveWalker) void {
+        self.name_buffer.deinit(self.allocator);
+        self.stack.deinit(self.allocator);
+    }
+    /// Leaves the current directory, continuing walking one level up.
+    pub fn leave(self: *SelectiveWalker) void {
+        var item = self.stack.pop().?;
+        if (self.stack.items.len != 0) {
+            @branchHint(.likely);
+            item.iter.dir.close();
         }
-        self.stack.deinit(gpa);
-        self.name_buffer.deinit(gpa);
     }
 };
-/// Recursively iterates over a directory.
+/// Recursively iterates over a directory, but requires the user to
+/// opt-in to recursing into each directory entry.
 ///
 /// `self` must have been opened with `OpenOptions{.iterate = true}`.
 ///
 @@ -765,7 +757,9 @@ pub const Walker = struct {
 /// The order of returned file system entries is undefined.
 ///
 /// `self` will not be closed after walking it.
-pub fn walk(self: Dir, allocator: Allocator) Allocator.Error!Walker {
+///
+/// See also `walk`.
+pub fn walkSelectively(self: Dir, allocator: Allocator) !SelectiveWalker {
     var stack: std.ArrayListUnmanaged(Walker.StackItem) = .empty;
     try stack.append(allocator, .{
 @@ -780,6 +774,64 @@ pub fn walk(self: Dir, allocator: Allocator) Allocator.Error!Walker {
     };
 }
+pub const Walker = struct {
+    inner: SelectiveWalker,
+    pub const Entry = struct {
+        /// The containing directory. This can be used to operate directly on `basename`
+        /// rather than `path`, avoiding `error.NameTooLong` for deeply nested paths.
+        /// The directory remains open until `next` or `deinit` is called.
+        dir: Dir,
+        basename: [:0]const u8,
+        path: [:0]const u8,
+        kind: Dir.Entry.Kind,
+    };
+    const StackItem = struct {
+        iter: Dir.Iterator,
+        dirname_len: usize,
+    };
+    /// After each call to this function, and on deinit(), the memory returned
+    /// from this function becomes invalid. A copy must be made in order to keep
+    /// a reference to the path.
+    pub fn next(self: *Walker) !?Walker.Entry {
+        const entry = try self.inner.next();
+        if (entry != null and entry.?.kind == .directory) {
+            try self.inner.enter(entry.?);
+        }
+        return entry;
+    }
+    pub fn deinit(self: *Walker) void {
+        self.inner.deinit();
+    }
+    /// Leaves the current directory, continuing walking one level up.
+    /// If the current entry is a directory entry, then the "current directory"
+    /// is the directory pertaining to the current entry.
+    pub fn leave(self: *Walker) void {
+        self.inner.leave();
+    }
+};
+/// Recursively iterates over a directory.
+///
+/// `self` must have been opened with `OpenOptions{.iterate = true}`.
+///
+/// `Walker.deinit` releases allocated memory and directory handles.
+///
+/// The order of returned file system entries is undefined.
+///
+/// `self` will not be closed after walking it.
+///
+/// See also `walkSelectively`.
+pub fn walk(self: Dir, allocator: Allocator) Allocator.Error!Walker {
+    return .{
+        .inner = try walkSelectively(self, allocator),
+    };
+}
 pub const OpenError = error{
     FileNotFound,
     NotDir,

lib/std/fs/test.zig+61

...	@@ -1810,6 +1810,67 @@ test "walker" {	...	@@ -1810,6 +1810,67 @@ test "walker" {
1810	try testing.expectEqual(expected_paths.kvs.len, num_walked);	1810	try testing.expectEqual(expected_paths.kvs.len, num_walked);
1811	}	1811	}
1812		1812
		1813	test "selective walker, skip entries that start with ." {
		1814	var tmp = tmpDir(.{ .iterate = true });
		1815	defer tmp.cleanup();
		1816
		1817	const paths_to_create: []const []const u8 = &.{
		1818	"dir1/foo/.git/ignored",
		1819	".hidden/bar",
		1820	"a/b/c",
		1821	"a/baz",
		1822	};
		1823
		1824	// iteration order of walker is undefined, so need lookup maps to check against
		1825
		1826	const expected_paths = std.StaticStringMap(void).initComptime(.{
		1827	.{"dir1"},
		1828	.{"dir1" ++ fs.path.sep_str ++ "foo"},
		1829	.{"a"},
		1830	.{"a" ++ fs.path.sep_str ++ "b"},
		1831	.{"a" ++ fs.path.sep_str ++ "b" ++ fs.path.sep_str ++ "c"},
		1832	.{"a" ++ fs.path.sep_str ++ "baz"},
		1833	});
		1834
		1835	const expected_basenames = std.StaticStringMap(void).initComptime(.{
		1836	.{"dir1"},
		1837	.{"foo"},
		1838	.{"a"},
		1839	.{"b"},
		1840	.{"c"},
		1841	.{"baz"},
		1842	});
		1843
		1844	for (paths_to_create) \|path\| {
		1845	try tmp.dir.makePath(path);
		1846	}
		1847
		1848	var walker = try tmp.dir.walkSelectively(testing.allocator);
		1849	defer walker.deinit();
		1850
		1851	var num_walked: usize = 0;
		1852	while (try walker.next()) \|entry\| {
		1853	if (entry.basename[0] == '.') continue;
		1854	if (entry.kind == .directory) {
		1855	try walker.enter(entry);
		1856	}
		1857
		1858	testing.expect(expected_basenames.has(entry.basename)) catch \|err\| {
		1859	std.debug.print("found unexpected basename: {f}\n", .{std.ascii.hexEscape(entry.basename, .lower)});
		1860	return err;
		1861	};
		1862	testing.expect(expected_paths.has(entry.path)) catch \|err\| {
		1863	std.debug.print("found unexpected path: {f}\n", .{std.ascii.hexEscape(entry.path, .lower)});
		1864	return err;
		1865	};
		1866	// make sure that the entry.dir is the containing dir
		1867	var entry_dir = try entry.dir.openDir(entry.basename, .{});
		1868	defer entry_dir.close();
		1869	num_walked += 1;
		1870	}
		1871	try testing.expectEqual(expected_paths.kvs.len, num_walked);
		1872	}
		1873
1813	test "walker without fully iterating" {	1874	test "walker without fully iterating" {
1814	var tmp = tmpDir(.{ .iterate = true });	1875	var tmp = tmpDir(.{ .iterate = true });
1815	defer tmp.cleanup();	1876	defer tmp.cleanup();