feat(fs): add vim.fs.dir()

This function is modeled after the path.dir() function from Penlight and
the luafilesystem module.

2 files changed, 27 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index bf30700fc0..5274b829b5 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2160,6 +2160,20 @@ basename({file})                                           *vim.fs.basename()*
                 Return: ~
                     (string) Basename of {file}
 
+dir({path})                                                     *vim.fs.dir()*
+                Return an iterator over the files and directories located in
+                {path}
+
+                Parameters: ~
+                    {path}  (string) An absolute or relative path to the
+                            directory to iterate over
+
+                Return: ~
+                    Iterator over files and directories in {path}. Each
+                    iteration yields two values: name and type. Each "name" is
+                    the basename of the file or directory relative to {path}.
+                    Type is one of "file" or "directory".
+
 dirname({file})                                             *vim.fs.dirname()*
                 Return the parent directory of the given file or directory
 
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 29ce394a38..c28b06536b 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -48,4 +48,17 @@ function M.basename(file)
   return vim.fn.fnamemodify(file, ':t')
 end
 
+--- Return an iterator over the files and directories located in {path}
+---
+---@param path (string) An absolute or relative path to the directory to iterate
+---            over
+---@return Iterator over files and directories in {path}. Each iteration yields
+---        two values: name and type. Each "name" is the basename of the file or
+---        directory relative to {path}. Type is one of "file" or "directory".
+function M.dir(path)
+  return function(fs)
+    return vim.loop.fs_scandir_next(fs)
+  end, vim.loop.fs_scandir(path)
+end
+
 return M