commit 496691f985a1aacd9a0977c558ff4ce6980e13c8
parent e74753a221f82b2c7bade8c079683c19252484fe
Author: phanium <91544758+phanen@users.noreply.github.com>
Date: Tue, 17 Jun 2025 22:14:25 +0800
docs: vim.fs.dir.Opts type #34546
Follow the pattern of vim.fs.find.Opts
Diffstat:
2 files changed, 26 insertions(+), 13 deletions(-)
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -2995,11 +2995,13 @@ vim.fs.dir({path}, {opts}) *vim.fs.dir()*
iterate over. The path is first normalized
|vim.fs.normalize()|.
• {opts} (`table?`) Optional keyword arguments:
- • depth: integer|nil How deep the traverse (default 1)
- • skip: (fun(dir_name: string): boolean)|nil Predicate to
+ • {depth}? (`integer`, default: `1`) How deep the traverse.
+ • {skip}? (`fun(dir_name: string): boolean`) Predicate to
control traversal. Return false to stop searching the
- current directory. Only useful when depth > 1
- • follow: boolean|nil Follow symbolic links. (default: false)
+ current directory. Only useful when depth > 1 Return an
+ iterator over the items located in {path}
+ • {follow}? (`boolean`, default: `false`) Follow symbolic
+ links.
Return: ~
(`Iterator`) over items in {path}. Each iteration yields two values:
@@ -3061,7 +3063,7 @@ vim.fs.find({names}, {opts}) *vim.fs.find()*
The function should return `true` if the given item is
considered a match.
- • {opts} (`table`) Optional keyword arguments:
+ • {opts} (`table?`) Optional keyword arguments:
• {path}? (`string`) Path to begin searching from. If
omitted, the |current-directory| is used.
• {upward}? (`boolean`, default: `false`) Search upward
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
@@ -124,6 +124,23 @@ function M.joinpath(...)
return (path:gsub('//+', '/'))
end
+--- @class vim.fs.dir.Opts
+--- @inlinedoc
+---
+--- How deep the traverse.
+--- (default: `1`)
+--- @field depth? integer
+---
+--- Predicate to control traversal.
+--- Return false to stop searching the current directory.
+--- Only useful when depth > 1
+--- Return an iterator over the items located in {path}
+--- @field skip? (fun(dir_name: string): boolean)
+---
+--- Follow symbolic links.
+--- (default: `false`)
+--- @field follow? boolean
+
---@alias Iterator fun(): string?, string?
--- Return an iterator over the items located in {path}
@@ -131,13 +148,7 @@ end
---@since 10
---@param path (string) An absolute or relative path to the directory to iterate
--- over. The path is first normalized |vim.fs.normalize()|.
---- @param opts table|nil Optional keyword arguments:
---- - depth: integer|nil How deep the traverse (default 1)
---- - skip: (fun(dir_name: string): boolean)|nil Predicate
---- to control traversal. Return false to stop searching the current directory.
---- Only useful when depth > 1
---- - follow: boolean|nil Follow symbolic links. (default: false)
----
+---@param opts? vim.fs.dir.Opts Optional keyword arguments:
---@return Iterator over items in {path}. Each iteration yields two values: "name" and "type".
--- "name" is the basename of the item relative to {path}.
--- "type" is one of the following:
@@ -256,7 +267,7 @@ end
---
--- The function should return `true` if the given item is considered a match.
---
----@param opts vim.fs.find.Opts Optional keyword arguments:
+---@param opts? vim.fs.find.Opts Optional keyword arguments:
---@return (string[]) # Normalized paths |vim.fs.normalize()| of all matching items
function M.find(names, opts)
opts = opts or {}
