kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-19 10:45:16 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs(lua): clarify fs.find() documentation #24394

Browse Source
This commit is contained in:
futsuuu 2023-07-20 01:55:35 +09:00 committed by GitHub
parent 30a5c28c87
commit 86ce3878d6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 55 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
runtime/doc/lua.txt
View File

@ -2729,16 +2729,16 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
Lua module: vim.fs *vim.fs*
vim.fs.basename({file}) *vim.fs.basename()*
Return the basename of the given file or directory
Return the basename of the given path
Parameters: ~
• {file} (string) File or directory
• {file} (string) Path
Return: ~
(string|nil) Basename of {file}
vim.fs.dir({path}, {opts}) *vim.fs.dir()*
Return an iterator over the files and directories located in {path}
Return an iterator over the items located in {path}
Parameters: ~
• {path} (string) An absolute or relative path to the directory to
@ -2751,30 +2751,32 @@ vim.fs.dir({path}, {opts}) *vim.fs.dir()*
current directory. Only useful when depth > 1
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".
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: "file", "directory", "link",
"fifo", "socket", "char", "block", "unknown".
vim.fs.dirname({file}) *vim.fs.dirname()*
Return the parent directory of the given file or directory
Return the parent directory of the given path
Parameters: ~
• {file} (string) File or directory
• {file} (string) Path
Return: ~
(string|nil) Parent directory of {file}
vim.fs.find({names}, {opts}) *vim.fs.find()*
Find files or directories in the given path.
Find files or directories (or other items as specified by `opts.type`) in
the given path.
Finds any files or directories given in {names} starting from {path}. If
{upward} is "true" then the search traverses upward through parent
directories; otherwise, the search traverses downward. Note that downward
searches are recursive and may search through many directories! If {stop}
is non-nil, then the search stops when the directory given in {stop} is
reached. The search terminates when {limit} (default 1) matches are found.
The search can be narrowed to find only files or only directories by
specifying {type} to be "file" or "directory", respectively.
Finds items given in {names} starting from {path}. If {upward} is "true"
then the search traverses upward through parent directories; otherwise,
the search traverses downward. Note that downward searches are recursive
and may search through many directories! If {stop} is non-nil, then the
search stops when the directory given in {stop} is reached. The search
terminates when {limit} (default 1) matches are found. You can set {type}
to "file", "directory", "link", "socket", "char", "block", or "fifo" to
narrow the search to find only that type.
Examples: >lua
@ -2799,14 +2801,13 @@ vim.fs.find({names}, {opts}) *vim.fs.find()*
Parameters: ~
• {names} (string|table|fun(name: string, path: string): boolean) Names
of the files and directories to find. Must be base names,
paths and globs are not supported when {names} is a string or
a table. If {names} is a function, it is called for each
traversed file and directory with args:
of the items to find. Must be base names, paths and globs are
not supported when {names} is a string or a table. If {names}
is a function, it is called for each traversed item with
args:
• name: base name of the current item
• path: full path of the current item The function should
return `true` if the given file or directory is considered
a match.
return `true` if the given item is considered a match.
• {opts} (table) Optional keyword arguments:
• path (string): Path to begin searching from. If omitted,
the |current-directory| is used.
@ -2815,16 +2816,14 @@ vim.fs.find({names}, {opts}) *vim.fs.find()*
directories (recursively).
• stop (string): Stop searching when this directory is
reached. The directory itself is not searched.
• type (string): Find only files ("file") or directories
("directory"). If omitted, both files and directories that
match {names} are included.
• type (string): Find only items of the given type. If
omitted, all items that match {names} are included.
• limit (number, default 1): Stop the search after finding
this many matches. Use `math.huge` to place no limit on the
number of matches.
Return: ~
(table) Normalized paths |vim.fs.normalize()| of all matching files or
directories
(table) Normalized paths |vim.fs.normalize()| of all matching items
vim.fs.joinpath({...}) *vim.fs.joinpath()*
Concatenate directories and/or file paths into a single path with
@ -2864,7 +2863,7 @@ vim.fs.normalize({path}, {opts}) *vim.fs.normalize()*
(string) Normalized path
vim.fs.parents({start}) *vim.fs.parents()*
Iterate over all the parents of the given file or directory.
Iterate over all the parents of the given path.
Example: >lua
@ -2882,7 +2881,7 @@ vim.fs.parents({start}) *vim.fs.parents()*
<
Parameters: ~
• {start} (string) Initial file or directory.
• {start} (string) Initial path.
Return: ~
(function) Iterator

54
runtime/lua/vim/fs.lua
View File

@ -2,7 +2,7 @@ local M = {}
local iswin = vim.uv.os_uname().sysname == 'Windows_NT'
--- Iterate over all the parents of the given file or directory.
--- Iterate over all the parents of the given path.
---
--- Example:
--- <pre>lua
@ -19,7 +19,7 @@ local iswin = vim.uv.os_uname().sysname == 'Windows_NT'
--- end
--- </pre>
---
---@param start (string) Initial file or directory.
---@param start (string) Initial path.
---@return function Iterator
function M.parents(start)
return function(_, dir)
@ -34,9 +34,9 @@ function M.parents(start)
start
end
--- Return the parent directory of the given file or directory
--- Return the parent directory of the given path
---
---@param file (string) File or directory
---@param file (string) Path
---@return string|nil Parent directory of {file}
function M.dirname(file)
if file == nil then
@ -57,9 +57,9 @@ function M.dirname(file)
return (dir:gsub('\\', '/'))
end
--- Return the basename of the given file or directory
--- Return the basename of the given path
---
---@param file string File or directory
---@param file string Path
---@return string|nil Basename of {file}
function M.basename(file)
if file == nil then
@ -83,7 +83,7 @@ end
---@alias Iterator fun(): string?, string?
--- Return an iterator over the files and directories located in {path}
--- Return an iterator over the items located in {path}
---
---@param path (string) An absolute or relative path to the directory to iterate
--- over. The path is first normalized |vim.fs.normalize()|.
@ -93,9 +93,10 @@ end
--- to control traversal. Return false to stop searching the current directory.
--- Only useful when depth > 1
---
---@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".
---@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:
--- "file", "directory", "link", "fifo", "socket", "char", "block", "unknown".
function M.dir(path, opts)
opts = opts or {}
@ -142,16 +143,16 @@ function M.dir(path, opts)
end)
end
--- Find files or directories in the given path.
--- Find files or directories (or other items as specified by `opts.type`) in the given path.
---
--- Finds any files or directories given in {names} starting from {path}. If
--- {upward} is "true" then the search traverses upward through parent
--- directories; otherwise, the search traverses downward. Note that downward
--- searches are recursive and may search through many directories! If {stop}
--- is non-nil, then the search stops when the directory given in {stop} is
--- reached. The search terminates when {limit} (default 1) matches are found.
--- The search can be narrowed to find only files or only directories by
--- specifying {type} to be "file" or "directory", respectively.
--- Finds items given in {names} starting from {path}. If {upward} is "true"
--- then the search traverses upward through parent directories; otherwise,
--- the search traverses downward. Note that downward searches are recursive
--- and may search through many directories! If {stop} is non-nil, then the
--- search stops when the directory given in {stop} is reached. The search
--- terminates when {limit} (default 1) matches are found. You can set {type}
--- to "file", "directory", "link", "socket", "char", "block", or "fifo"
--- to narrow the search to find only that type.
---
--- Examples:
--- <pre>lua
@ -174,13 +175,12 @@ end
--- end, {limit = math.huge, type = 'file'})
--- </pre>
---
---@param names (string|table|fun(name: string, path: string): boolean) Names of the files
--- and directories to find.
---@param names (string|table|fun(name: string, path: string): boolean) Names of the items to find.
--- Must be base names, paths and globs are not supported when {names} is a string or a table.
--- If {names} is a function, it is called for each traversed file and directory with args:
--- If {names} is a function, it is called for each traversed item with args:
--- - name: base name of the current item
--- - path: full path of the current item
--- The function should return `true` if the given file or directory is considered a match.
--- The function should return `true` if the given item is considered a match.
---
---@param opts (table) Optional keyword arguments:
--- - path (string): Path to begin searching from. If
@ -191,14 +191,12 @@ end
--- (recursively).
--- - stop (string): Stop searching when this directory is
--- reached. The directory itself is not searched.
--- - type (string): Find only files ("file") or
--- directories ("directory"). If omitted, both
--- files and directories that match {names} are
--- included.
--- - type (string): Find only items of the given type.
--- If omitted, all items that match {names} are included.
--- - limit (number, default 1): Stop the search after
--- finding this many matches. Use `math.huge` to
--- place no limit on the number of matches.
---@return (table) Normalized paths |vim.fs.normalize()| of all matching files or directories
---@return (table) Normalized paths |vim.fs.normalize()| of all matching items
function M.find(names, opts)
opts = opts or {}
vim.validate({