GitHub/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim synced 2025-07-15 16:51:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: vim.fs., diagnostics, lsp #34402

Browse Source
This commit is contained in:
Justin M. Keyes
2025-06-13 07:49:21 -07:00
committed by GitHub
parent 1d5b3b5b4c
commit 8001276bd0
10 changed files with 94 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
runtime/doc/develop.txt
View File

@ -441,6 +441,7 @@ Use existing common {verb} names (actions) if possible:
- get: Gets things. Two variants (overloads):
1. `get<T>(id: int): T` returns one item.
2. `get<T>(filter: dict): T[]` returns a list.
- has: Checks for the presence of an item, feature, etc.
- inspect: Presents a high-level, often interactive, view
- is_enabled: Checks if functionality is enabled.
- open: Opens something (a buffer, window, …)
@ -452,6 +453,7 @@ Use existing common {verb} names (actions) if possible:
- try_{verb}: Best-effort operation, failure returns null or error obj
Do NOT use these deprecated verbs:
- contains: Prefer "has".
- disable: Prefer `enable(enable: boolean)`.
- exit: Prefer "cancel" (or "stop" if appropriate).
- is_disabled: Prefer `is_enabled()`.

23
runtime/doc/diagnostic.txt
View File

@ -38,19 +38,6 @@ optionally supplied). A good rule of thumb is that if a method is meant to
modify the diagnostics for a buffer (e.g. |vim.diagnostic.set()|) then it
requires a namespace.
==============================================================================
DEFAULTS *diagnostic-defaults*
These diagnostic keymaps are created unconditionally when Nvim starts:
- |]d| is mapped in Normal mode to jump the next diagnostic in the current
buffer
- |[d| is mapped in Normal and Visual mode to jump to the previous diagnostic
in th current buffer
- |]D| is mapped in Normal mode to jump to the last diagnostic in the current buffer
- |[D| is mapped in Normal mode to jump to the first diagnostic in the current
buffer
- <C-w>d is mapped in normal mode to show diagnostic under cursor.
*vim.diagnostic.severity* *diagnostic-severity*
The "severity" key in a diagnostic is one of the values defined in
`vim.diagnostic.severity`:
@ -82,6 +69,16 @@ Functions that take a severity as an optional parameter (e.g.
<
This form allows users to filter for specific severities
==============================================================================
DEFAULTS *diagnostic-defaults*
These diagnostic keymaps are created unconditionally when Nvim starts:
- `]d` jumps to the next diagnostic in the buffer. |]d-default|
- `[d` jumps to the previous diagnostic in the buffer. |[d-default|
- `]D` jumps to the last diagnostic in the buffer. |]D-default|
- `[D` jumps to the first diagnostic in the buffer. |[D-default|
- `<C-w>d` shows diagnostic at cursor in a floating window. |CTRL-W_d-default|
==============================================================================
HANDLERS *diagnostic-handlers*

6
runtime/doc/lsp.txt
View File

@ -717,7 +717,9 @@ Lua module: vim.lsp *lsp-core*
Fields: ~
• {cmd}? (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
See `cmd` in |vim.lsp.ClientConfig|.
See `cmd` in |vim.lsp.ClientConfig|. See also
`reuse_client` to dynamically decide (per-buffer)
when `cmd` should be re-invoked.
• {filetypes}? (`string[]`) Filetypes the client will attach to, if
activated by `vim.lsp.enable()`. If not provided, the
client will attach to all filetypes.
@ -1358,7 +1360,7 @@ Lua module: vim.lsp.client *lsp-client*
|vim.empty_dict()|, else it will be encoded
as an array.
• {cmd} (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
command string[] that launches the language
Command `string[]` that launches the language
server (treated as in |jobstart()|, must be
absolute or on `$PATH`, shell constructs like
"~" are not expanded), or function that creates

58
runtime/doc/lua.txt
View File

@ -1468,20 +1468,21 @@ Lua module: vim *lua-vim*
vim.cmd({command}) *vim.cmd()*
Executes Vimscript (|Ex-commands|).
Note that `vim.cmd` can be indexed with a command name to return a
callable function to the command.
Can be indexed with a command name to get a function, thus you can write
`vim.cmd.echo(…)` instead of `vim.cmd{cmd='echo',…}`.
Example: >lua
Examples: >lua
-- Single command:
vim.cmd('echo 42')
-- Multiline script:
vim.cmd([[
augroup My_group
augroup my.group
autocmd!
autocmd FileType c setlocal cindent
augroup END
]])
-- Ex command :echo "foo"
-- Note string literals need to be double quoted.
-- Ex command :echo "foo". Note: string literals must be double-quoted.
vim.cmd('echo "foo"')
vim.cmd { cmd = 'echo', args = { '"foo"' } }
vim.cmd.echo({ args = { '"foo"' } })
@ -1489,22 +1490,20 @@ vim.cmd({command}) *vim.cmd()*
-- Ex command :write! myfile.txt
vim.cmd('write! myfile.txt')
vim.cmd { cmd = 'write', args = { "myfile.txt" }, bang = true }
vim.cmd.write { args = { "myfile.txt" }, bang = true }
vim.cmd.write { "myfile.txt", bang = true }
vim.cmd { cmd = 'write', args = { 'myfile.txt' }, bang = true }
vim.cmd.write { args = { 'myfile.txt' }, bang = true }
vim.cmd.write { 'myfile.txt', bang = true }
-- Ex command :colorscheme blue
vim.cmd('colorscheme blue')
vim.cmd.colorscheme('blue')
-- Ex command :vertical resize +2
vim.cmd.resize({ '+2', mods = { vertical = true } })
<
Parameters: ~
• {command} (`string|table`) Command(s) to execute. If a string,
executes multiple lines of Vimscript at once. In this case,
it is an alias to |nvim_exec2()|, where `opts.output` is
set to false. Thus it works identical to |:source|. If a
table, executes a single command. In this case, it is an
alias to |nvim_cmd()| where `opts` is empty.
• {command} (`string|table`) Command(s) to execute.
• The string form supports multiline Vimscript (alias to
|nvim_exec2()|, behaves like |:source|).
• The table form executes a single command (alias to
|nvim_cmd()|).
See also: ~
• |ex-cmd-index|
@ -3203,7 +3202,7 @@ vim.fs.root({source}, {marker}) *vim.fs.root()*
If the buffer is unnamed (has no backing file) or has a non-empty
'buftype' then the search begins from Nvim's |current-directory|.
Example: >lua
Examples: >lua
-- Find the root of a Python project, starting from file 'main.py'
vim.fs.root(vim.fs.joinpath(vim.env.PWD, 'main.py'), {'pyproject.toml', 'setup.py' })
@ -3228,21 +3227,12 @@ vim.fs.root({source}, {marker}) *vim.fs.root()*
file path (absolute or relative to the |current-directory|)
to begin the search from.
• {marker} (`(string|string[]|fun(name: string, path: string): boolean)[]|string|fun(name: string, path: string): boolean`)
A marker or a list of markers. A marker has one of three
types: string, a list of strings or a function. The
parameter also accepts a list of markers, each of which is
any of those three types. If a marker is a function, it is
called for each evaluated item and should return true if
{name} and {path} are a match. If a list of markers is
passed, each marker in the list is evaluated in order and
the first marker which is matched returns the parent
directory that it found. This allows listing markers with
priority. E.g. - in the following list, a parent directory
containing either 'a' or 'b' is searched for. If neither is
found, then 'c' is searched for. So, 'c' has lower priority
than 'a' and 'b' which have equal priority. >lua
marker = { { 'a', 'b' }, 'c' }
<
Filename, function, or list thereof, that decides how to
find the root. To indicate "equal priority", specify items
in a nested list `{ { 'a.txt', 'b.lua' }, … }`. A function
item must return true if `name` and `path` are a match. Each
item (which may itself be a nested list) is evaluated
in-order against all ancestors, until a match is found.
Return: ~
(`string?`) Directory path containing one of the given markers, or nil

32
runtime/lua/vim/_editor.lua
View File

@ -400,22 +400,23 @@ local VIM_CMD_ARG_MAX = 20
--- Executes Vimscript (|Ex-commands|).
---
--- Note that `vim.cmd` can be indexed with a command name to return a callable function to the
--- command.
--- Can be indexed with a command name to get a function, thus you can write `vim.cmd.echo(…)`
--- instead of `vim.cmd{cmd='echo',…}`.
---
--- Example:
--- Examples:
---
--- ```lua
--- -- Single command:
--- vim.cmd('echo 42')
--- -- Multiline script:
--- vim.cmd([[
--- augroup My_group
--- augroup my.group
--- autocmd!
--- autocmd FileType c setlocal cindent
--- augroup END
--- ]])
---
--- -- Ex command :echo "foo"
--- -- Note string literals need to be double quoted.
--- -- Ex command :echo "foo". Note: string literals must be double-quoted.
--- vim.cmd('echo "foo"')
--- vim.cmd { cmd = 'echo', args = { '"foo"' } }
--- vim.cmd.echo({ args = { '"foo"' } })
@ -423,22 +424,19 @@ local VIM_CMD_ARG_MAX = 20
---
--- -- Ex command :write! myfile.txt
--- vim.cmd('write! myfile.txt')
--- vim.cmd { cmd = 'write', args = { "myfile.txt" }, bang = true }
--- vim.cmd.write { args = { "myfile.txt" }, bang = true }
--- vim.cmd.write { "myfile.txt", bang = true }
--- vim.cmd { cmd = 'write', args = { 'myfile.txt' }, bang = true }
--- vim.cmd.write { args = { 'myfile.txt' }, bang = true }
--- vim.cmd.write { 'myfile.txt', bang = true }
---
--- -- Ex command :colorscheme blue
--- vim.cmd('colorscheme blue')
--- vim.cmd.colorscheme('blue')
--- -- Ex command :vertical resize +2
--- vim.cmd.resize({ '+2', mods = { vertical = true } })
--- ```
---
---@diagnostic disable-next-line: undefined-doc-param
---@param command string|table Command(s) to execute.
--- If a string, executes multiple lines of Vimscript at once. In this
--- case, it is an alias to |nvim_exec2()|, where `opts.output` is set
--- to false. Thus it works identical to |:source|.
--- If a table, executes a single command. In this case, it is an alias
--- to |nvim_cmd()| where `opts` is empty.
--- - The string form supports multiline Vimscript (alias to |nvim_exec2()|, behaves
--- like |:source|).
--- - The table form executes a single command (alias to |nvim_cmd()|).
---@see |ex-cmd-index|
vim.cmd = setmetatable({}, {
__call = function(_, command)

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

@ -375,7 +375,7 @@ end
--- If the buffer is unnamed (has no backing file) or has a non-empty 'buftype' then the search
--- begins from Nvim's |current-directory|.
---
--- Example:
--- Examples:
---
--- ```lua
--- -- Find the root of a Python project, starting from file 'main.py'
@ -397,20 +397,12 @@ end
--- @since 12
--- @param source integer|string Buffer number (0 for current buffer) or file path (absolute or
--- relative to the |current-directory|) to begin the search from.
--- @param marker (string|string[]|fun(name: string, path: string): boolean)[]|string|fun(name: string, path: string): boolean A marker or a list of markers.
--- A marker has one of three types: string, a list of strings or a function. The
--- parameter also accepts a list of markers, each of which is any of those three
--- types. If a marker is a function, it is called for each evaluated item and
--- should return true if {name} and {path} are a match. If a list of markers is
--- passed, each marker in the list is evaluated in order and the first marker
--- which is matched returns the parent directory that it found. This allows
--- listing markers with priority. E.g. - in the following list, a parent directory
--- containing either 'a' or 'b' is searched for. If neither is found, then 'c' is
--- searched for. So, 'c' has lower priority than 'a' and 'b' which have equal
--- priority.
--- ```lua
--- marker = { { 'a', 'b' }, 'c' }
--- ```
--- @param marker (string|string[]|fun(name: string, path: string): boolean)[]|string|fun(name: string, path: string): boolean
--- Filename, function, or list thereof, that decides how to find the root. To
--- indicate "equal priority", specify items in a nested list `{ { 'a.txt', 'b.lua' }, … }`.
--- A function item must return true if `name` and `path` are a match. Each item
--- (which may itself be a nested list) is evaluated in-order against all ancestors,
--- until a match is found.
--- @return string? # Directory path containing one of the given markers, or nil if no directory was
--- found.
function M.root(source, marker)

1
runtime/lua/vim/lsp.lua
View File

@ -272,6 +272,7 @@ end
--- @class vim.lsp.Config : vim.lsp.ClientConfig
---
--- See `cmd` in [vim.lsp.ClientConfig].
--- See also `reuse_client` to dynamically decide (per-buffer) when `cmd` should be re-invoked.
--- @field cmd? string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient
---
--- Filetypes the client will attach to, if activated by `vim.lsp.enable()`. If not provided, the

11
runtime/lua/vim/lsp/client.lua
View File

@ -43,13 +43,12 @@ local validate = vim.validate
--- array.
--- @field capabilities? lsp.ClientCapabilities
---
--- command string[] that launches the language
--- server (treated as in |jobstart()|, must be absolute or on `$PATH`, shell constructs like
--- "~" are not expanded), or function that creates an RPC client. Function receives
--- a `dispatchers` table and returns a table with member functions `request`, `notify`,
--- `is_closing` and `terminate`.
--- Command `string[]` that launches the language server (treated as in |jobstart()|, must be
--- absolute or on `$PATH`, shell constructs like "~" are not expanded), or function that creates an
--- RPC client. Function receives a `dispatchers` table and returns a table with member functions
--- `request`, `notify`, `is_closing` and `terminate`.
--- See |vim.lsp.rpc.request()|, |vim.lsp.rpc.notify()|.
--- For TCP there is a builtin RPC client factory: |vim.lsp.rpc.connect()|
--- For TCP there is a builtin RPC client factory: |vim.lsp.rpc.connect()|
--- @field cmd string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient
---
--- Directory to launch the `cmd` process. Not related to `root_dir`.

5
src/nvim/ex_cmds_defs.h
View File

@ -31,9 +31,8 @@
//
// All keys not described in the above table are reserved for future use.
//
// 2. Add a "case: CMD_xxx" in the big switch in ex_docmd.c.
// 3. Add an entry in the index for Ex commands at ":help ex-cmd-index".
// 4. Add documentation in ../doc/xxx.txt. Add a tag for both the short and
// 2. Add an entry in the index for Ex commands at ":help ex-cmd-index".
// 3. Add documentation in ../doc/xxx.txt. Add a tag for both the short and
// long name of the command.
#define EX_RANGE 0x001u // allow a linespecs

48
test/functional/treesitter/parser_spec.lua
View File

@ -303,7 +303,7 @@ void ui_refresh(void)
}
}]]
it('allows to iterate over nodes children', function()
it('can iterate over nodes children', function()
insert(test_text)
local res = exec_lua(function()
@ -337,7 +337,7 @@ void ui_refresh(void)
exec_lua("vim.treesitter.get_parser(0, 'c')")
end)
it('allows to get a child by field', function()
it('can get a child by field', function()
insert(test_text)
local res = exec_lua(function()
@ -363,7 +363,7 @@ void ui_refresh(void)
assert(res_fail)
end)
it('supports getting text of multiline node', function()
it('can get text of multiline node', function()
insert(test_text)
local res = exec_lua(function()
local parser = vim.treesitter.get_parser(0, 'c')
@ -380,7 +380,7 @@ void ui_refresh(void)
eq('void', res2)
end)
it('supports getting text where start of node is one past EOF', function()
it('can get text where start of node is one past EOF', function()
local text = [[
def run
a = <<~E
@ -407,7 +407,7 @@ end]]
)
end)
it('supports getting empty text if node range is zero width', function()
it('can get empty text if node range is zero-width', function()
local text = [[
```lua
{}
@ -429,7 +429,7 @@ end]]
eq(true, result)
end)
it('allows to set simple ranges', function()
it('can set simple ranges', function()
insert(test_text)
local res = exec_lua(function()
@ -461,7 +461,7 @@ end]]
eq({ { { 0, 0, 0, 17, 1, 508 } } }, range_tbl)
end)
it('allows to set complex ranges', function()
it('can set complex ranges', function()
insert(test_text)
local res = exec_lua(function()
@ -495,7 +495,7 @@ end]]
}, res)
end)
it('allows to create string parsers', function()
it('can create string parsers', function()
local ret = exec_lua(function()
local parser = vim.treesitter.get_string_parser('int foo = 42;', 'c')
return { parser:parse()[1]:root():range() }
@ -513,7 +513,7 @@ end]]
eq({ 0, 0, 0, 13 }, ret)
end)
it('allows to run queries with string parsers', function()
it('can run queries with string parsers', function()
local txt = [[
int foo = 42;
int bar = 13;
@ -535,7 +535,7 @@ end]]
eq({ { 0, 10, 0, 13 } }, ret)
end)
describe('when creating a language tree', function()
describe('creating a language tree', function()
local function get_ranges()
return exec_lua(function()
local result = {}
@ -557,8 +557,8 @@ int x = INT_MAX;
]])
end)
describe('when parsing regions independently', function()
it('should inject a language', function()
describe('parsing regions independently', function()
it('injects a language', function()
exec_lua(function()
_G.parser = vim.treesitter.get_parser(0, 'c', {
injections = {
@ -596,7 +596,7 @@ int x = INT_MAX;
end)
describe('when parsing regions combined', function()
it('should inject a language', function()
it('injects a language', function()
exec_lua(function()
_G.parser = vim.treesitter.get_parser(0, 'c', {
injections = {
@ -777,7 +777,7 @@ int x = INT_MAX;
end)
describe('when using injection.self', function()
it('should inject the source language', function()
it('injects the source language', function()
exec_lua(function()
_G.parser = vim.treesitter.get_parser(0, 'c', {
injections = {
@ -815,7 +815,7 @@ int x = INT_MAX;
end)
describe('when using the offset directive', function()
it('should shift the range by the directive amount', function()
it('shifts the range by the directive amount', function()
exec_lua(function()
_G.parser = vim.treesitter.get_parser(0, 'c', {
injections = {
@ -838,7 +838,7 @@ int x = INT_MAX;
{ 5, 17, 5, 17 }, -- VALUE2 123
}, get_ranges())
end)
it('should apply offsets to quantified captures', function()
it('applies offsets to quantified captures', function()
local function get_ltree_ranges()
return exec_lua(function()
local result = {}
@ -870,7 +870,7 @@ int x = INT_MAX;
},
}, get_ltree_ranges())
end)
it('should list all directives', function()
it('lists all directives', function()
local res_list = exec_lua(function()
local query = vim.treesitter.query
@ -886,7 +886,7 @@ int x = INT_MAX;
end)
end)
it('properly clips nested injections #34098', function()
it('clips nested injections #34098', function()
insert([=[
```lua
vim.cmd([[
@ -923,7 +923,7 @@ int x = INT_MAX;
]])
end)
it('should return the correct language tree', function()
it('returns the correct language tree', function()
local result = exec_lua(function()
local parser = vim.treesitter.get_parser(0, 'c', {
injections = {
@ -973,7 +973,7 @@ print()
describe('when getting/setting match data', function()
describe('when setting for the whole match', function()
it('should set/get the data correctly', function()
it('sets/gets the data correctly', function()
insert([[
int x = 3;
]])
@ -991,7 +991,7 @@ print()
end)
describe('when setting a key on a capture', function()
it('it should create the nested table', function()
it('creates the nested table', function()
insert([[
int x = 3;
]])
@ -1011,7 +1011,7 @@ print()
eq('value', result)
end)
it('it should not overwrite the nested table', function()
it('does not overwrite the nested table', function()
insert([[
int x = 3;
]])
@ -1267,7 +1267,7 @@ print()
eq({ { { 1, 0, 21, 2, 0, 42 } } }, exec_lua('return parser2:children().lua:included_regions()'))
end)
it('parsers injections incrementally', function()
it('parses injections incrementally', function()
insert(dedent [[
>lua
local a = {}
@ -1410,7 +1410,7 @@ print()
end)
it(
'is valid excluding, invalid including children after a range parse that does not lead to parsing not parsed injections',
'is valid excluding, invalid including children after a range parse that does not lead to parsing non-parsed injections',
function()
exec_lua('vim.treesitter.get_parser():parse({2, 4})')
eq(true, exec_lua('return vim.treesitter.get_parser():is_valid(true)'))