diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 8d60d2c868..d649fa5812 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -441,6 +441,7 @@ Use existing common {verb} names (actions) if possible: - get: Gets things. Two variants (overloads): 1. `get(id: int): T` returns one item. 2. `get(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()`. diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 60fd5af088..e8a2e3f823 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -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 -- 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| +- `d` shows diagnostic at cursor in a floating window. |CTRL-W_d-default| + ============================================================================== HANDLERS *diagnostic-handlers* diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index eca5cc194f..e83e5b199a 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -715,7 +715,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. @@ -1308,7 +1310,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 diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index a0260f2710..f2722583ba 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1466,20 +1466,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"' } }) @@ -1487,22 +1488,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| @@ -3154,7 +3153,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' }) @@ -3179,21 +3178,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 diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua index e795c66969..735e746a70 100644 --- a/runtime/lua/vim/_editor.lua +++ b/runtime/lua/vim/_editor.lua @@ -399,22 +399,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"' } }) @@ -422,22 +423,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) diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index 496d37af31..8bb4c7ca91 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -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) diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index e1f97c7787..8261accb14 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -275,6 +275,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 diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua index 2f70d2f1db..52e34039d5 100644 --- a/runtime/lua/vim/lsp/client.lua +++ b/runtime/lua/vim/lsp/client.lua @@ -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`. diff --git a/src/nvim/ex_cmds_defs.h b/src/nvim/ex_cmds_defs.h index 9dc922b0d9..bae53fb10f 100644 --- a/src/nvim/ex_cmds_defs.h +++ b/src/nvim/ex_cmds_defs.h @@ -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 diff --git a/test/functional/treesitter/parser_spec.lua b/test/functional/treesitter/parser_spec.lua index b348f77b38..a161f63147 100644 --- a/test/functional/treesitter/parser_spec.lua +++ b/test/functional/treesitter/parser_spec.lua @@ -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; { 2, 29, 2, 66 }, -- READ_STRING_OK(x, y) (char *)read_string((x), (size_t)(y)) }, get_ranges()) end) - it('should list all directives', function() + it('lists all directives', function() local res_list = exec_lua(function() local query = vim.treesitter.query @@ -862,7 +862,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 = { @@ -912,7 +912,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; ]]) @@ -930,7 +930,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; ]]) @@ -950,7 +950,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; ]]) @@ -1206,7 +1206,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 = {} @@ -1349,7 +1349,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)'))