mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-06 03:18:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(lua): add clarifications for fs.find() and fs.normalize() (#21132)

Browse Source 
Co-Authored-By: Gregory Anders <8965202+gpanders@users.noreply.github.com>
Co-Authored-By: zeertzjq <zeertzjq@outlook.com>
This commit is contained in:
AzerAfram
2022-11-23 15:40:07 -08:00
committed by GitHub
parent b26cf45fec
commit ddea80ebd6
2 changed files with 28 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
runtime/doc/lua.txt
View File

@@ -2286,11 +2286,12 @@ find({names}, {opts}) *vim.fs.find()*
Parameters: ~ Parameters: ~
• {names} (string|table|fun(name: string): boolean) Names of the files • {names} (string|table|fun(name: string): boolean) Names of the files
and directories to find. Must be base names, paths and globs and directories to find. Must be base names, paths and globs
are not supported. If a function it is called per file and are not supported. The function is called per file and
dir within the traversed directories to test if they match. directory within the traversed directories to test if they
match {names}.
• {opts} (table) Optional keyword arguments: • {opts} (table) Optional keyword arguments:
• path (string): Path to begin searching from. If omitted, • path (string): Path to begin searching from. If omitted,
the current working directory is used. the |current-directory| is used.
• upward (boolean, default false): If true, search upward • upward (boolean, default false): If true, search upward
through parent directories. Otherwise, search through child through parent directories. Otherwise, search through child
directories (recursively). directories (recursively).
@@ -2298,13 +2299,14 @@ find({names}, {opts}) *vim.fs.find()*
reached. The directory itself is not searched. reached. The directory itself is not searched.
• type (string): Find only files ("file") or directories • type (string): Find only files ("file") or directories
("directory"). If omitted, both files and directories that ("directory"). If omitted, both files and directories that
match {name} are included. match {names} are included.
• limit (number, default 1): Stop the search after finding • limit (number, default 1): Stop the search after finding
this many matches. Use `math.huge` to place no limit on the this many matches. Use `math.huge` to place no limit on the
number of matches. number of matches.
Return: ~ Return: ~
(table) The paths of all matching files or directories (table) The normalized paths |vim.fs.normalize()| of all matching
files or directories
normalize({path}) *vim.fs.normalize()* normalize({path}) *vim.fs.normalize()*
Normalize a path to a standard format. A tilde (~) character at the Normalize a path to a standard format. A tilde (~) character at the
@@ -2312,7 +2314,7 @@ normalize({path}) *vim.fs.normalize()*
backslash (\) characters are converted to forward slashes (/). Environment backslash (\) characters are converted to forward slashes (/). Environment
variables are also expanded. variables are also expanded.
Example: > Examples: >
vim.fs.normalize('C:\Users\jdoe') vim.fs.normalize('C:\Users\jdoe')
=> 'C:/Users/jdoe' => 'C:/Users/jdoe'

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

@@ -79,11 +79,12 @@ end
---@param names (string|table|fun(name: string): boolean) Names of the files ---@param names (string|table|fun(name: string): boolean) Names of the files
--- and directories to find. --- and directories to find.
--- Must be base names, paths and globs are not supported. --- Must be base names, paths and globs are not supported.
--- If a function it is called per file and dir within the --- The function is called per file and directory within the
--- traversed directories to test if they match. --- traversed directories to test if they match {names}.
---
---@param opts (table) Optional keyword arguments: ---@param opts (table) Optional keyword arguments:
--- - path (string): Path to begin searching from. If --- - path (string): Path to begin searching from. If
--- omitted, the current working directory is used. --- omitted, the |current-directory| is used.
--- - upward (boolean, default false): If true, search --- - upward (boolean, default false): If true, search
--- upward through parent directories. Otherwise, --- upward through parent directories. Otherwise,
--- search through child directories --- search through child directories
@@ -92,12 +93,13 @@ end
--- reached. The directory itself is not searched. --- reached. The directory itself is not searched.
--- - type (string): Find only files ("file") or --- - type (string): Find only files ("file") or
--- directories ("directory"). If omitted, both --- directories ("directory"). If omitted, both
--- files and directories that match {name} are --- files and directories that match {names} are
--- included. --- included.
--- - limit (number, default 1): Stop the search after --- - limit (number, default 1): Stop the search after
--- finding this many matches. Use `math.huge` to --- finding this many matches. Use `math.huge` to
--- place no limit on the number of matches. --- place no limit on the number of matches.
---@return (table) The paths of all matching files or directories ---
---@return (table) The normalized paths |vim.fs.normalize()| of all matching files or directories
function M.find(names, opts) function M.find(names, opts)
opts = opts or {} opts = opts or {}
vim.validate({ vim.validate({
@@ -211,7 +213,7 @@ end
--- backslash (\\) characters are converted to forward slashes (/). Environment --- backslash (\\) characters are converted to forward slashes (/). Environment
--- variables are also expanded. --- variables are also expanded.
--- ---
--- Example: --- Examples:
--- <pre> --- <pre>
--- vim.fs.normalize('C:\\Users\\jdoe') --- vim.fs.normalize('C:\\Users\\jdoe')
--- => 'C:/Users/jdoe' --- => 'C:/Users/jdoe'