commit b41e066aa124b5feb428877c7a35776ce4d3035c
parent cb247e06f0ba19ca55252de0aebe249ed4c3635f
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sun, 30 Mar 2025 13:29:36 -0700
docs: lsp config/commands #33122
fix #33075
Diffstat:
10 files changed, 237 insertions(+), 176 deletions(-)
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
@@ -3492,40 +3492,39 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
empty. The end-of-buffer region is hidden by setting
`eob` flag of 'fillchars' to a space char, and clearing
the |hl-EndOfBuffer| region in 'winhighlight'.
- • border: Style of (optional) window border. This can either
- be a string or an array. The string values are the same as
- those described in 'winborder'. If it is an array, it
- should have a length of eight or any divisor of eight. The
- array will specify the eight chars building up the border
- in a clockwise fashion starting with the top-left corner.
- As an example, the double box style could be specified as: >
- [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
+ • border: (`string|string[]`) (defaults to 'winborder'
+ option) Window border. The string form accepts the same
+ values as the 'winborder' option. The array form must have
+ a length of eight or any divisor of eight, specifying the
+ chars that form the border in a clockwise fashion starting
+ from the top-left corner. For example, the double-box
+ style can be specified as: >
+ [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
<
- If the number of chars are less than eight, they will be
- repeated. Thus an ASCII border could be specified as >
- [ "/", "-", \"\\\\\", "|" ],
+ If fewer than eight chars are given, they will be
+ repeated. An ASCII border could be specified as: >
+ [ "/", "-", \"\\\\\", "|" ],
<
- or all chars the same as >
- [ "x" ].
+ Or one char for all sides: >
+ [ "x" ].
<
- An empty string can be used to turn off a specific border,
- for instance, >
- [ "", "", "", ">", "", "", "", "<" ]
+ Empty string can be used to hide a specific border. This
+ example will show only vertical borders, not horizontal: >
+ [ "", "", "", ">", "", "", "", "<" ]
<
- will only make vertical borders but not horizontal ones.
- By default, `FloatBorder` highlight is used, which links
- to `WinSeparator` when not defined. It could also be
- specified by character: >
- [ ["+", "MyCorner"], ["x", "MyBorder"] ].
+ By default, |hl-FloatBorder| highlight is used, which
+ links to |hl-WinSeparator| when not defined. Each border
+ side can specify an optional highlight: >
+ [ ["+", "MyCorner"], ["x", "MyBorder"] ].
<
- • title: Title (optional) in window border, string or list.
+ • title: (optional) Title in window border, string or list.
List should consist of `[text, highlight]` tuples. If
string, or a tuple lacks a highlight, the default
highlight group is `FloatTitle`.
• title_pos: Title position. Must be set with `title`
option. Value can be one of "left", "center", or "right".
Default is `"left"`.
- • footer: Footer (optional) in window border, string or
+ • footer: (optional) Footer in window border, string or
list. List should consist of `[text, highlight]` tuples.
If string, or a tuple lacks a highlight, the default
highlight group is `FloatFooter`.
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
@@ -651,10 +651,11 @@ When completion is active you can use CTRL-E to stop it and go back to the
originally typed text. The CTRL-E will not be inserted.
*complete_CTRL-Y*
-When the popup menu is displayed you can use CTRL-Y to stop completion and
-accept the currently selected entry. The CTRL-Y is not inserted. Typing a
-space, Enter, or some other unprintable character will leave completion mode
-and insert that typed character.
+When the popup menu is displayed, CTRL-Y stops completion and accepts the
+currently selected entry. Typing a space, Enter, or some other unprintable
+character will leave completion mode and insert that typed character. If you
+want to use <Enter> to accept a completion item, use this mapping: >vim
+ inoremap <expr> <cr> pumvisible() ? '<c-y>' : '<cr>'
When the popup menu is displayed there are a few more special keys, see
|popupmenu-keys|.
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
@@ -76,6 +76,7 @@ listed below, if (1) the language server supports the functionality and (2)
the options are empty or were set by the builtin runtime (ftplugin) files. The
options are not restored when the LSP client is stopped or detached.
+BUFFER-LOCAL DEFAULTS
- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger
completion.
- 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like
@@ -87,8 +88,9 @@ options are not restored when the LSP client is stopped or detached.
- |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or
a custom keymap for `K` exists.
+GLOBAL DEFAULTS
*grr* *gra* *grn* *gri* *i_CTRL-S*
-Some keymaps are created unconditionally when Nvim starts:
+These GLOBAL keymaps are created unconditionally when Nvim starts:
- "grn" is mapped in Normal mode to |vim.lsp.buf.rename()|
- "gra" is mapped in Normal and Visual mode to |vim.lsp.buf.code_action()|
- "grr" is mapped in Normal mode to |vim.lsp.buf.references()|
@@ -96,12 +98,11 @@ Some keymaps are created unconditionally when Nvim starts:
- "gO" is mapped in Normal mode to |vim.lsp.buf.document_symbol()|
- CTRL-S is mapped in Insert mode to |vim.lsp.buf.signature_help()|
-If not wanted, these keymaps can be removed at any time using
-|vim.keymap.del()| or |:unmap| (see also |gr-default|).
+You can remove GLOBAL keymaps at any time using |vim.keymap.del()| or
+|:unmap|. See also |gr-default|.
*lsp-defaults-disable*
-To override or delete any of the above defaults, set or unset the options on
-|LspAttach|: >lua
+To remove or override BUFFER-LOCAL defaults, define a |LspAttach| handler: >lua
vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args)
@@ -812,61 +813,90 @@ client_is_stopped({client_id}) *vim.lsp.client_is_stopped()*
(`boolean`) stopped true if client is stopped, false otherwise.
commands *vim.lsp.commands*
- Registry for client side commands. This is an extension point for plugins
- to handle custom commands which are not part of the core language server
- protocol specification.
-
- The registry is a table where the key is a unique command name, and the
- value is a function which is called if any LSP action (code action, code
- lenses, ...) triggers the command.
-
- If an LSP response contains a command for which no matching entry is
- available in this registry, the command will be executed via the LSP
- server using `workspace/executeCommand`.
-
- The first argument to the function will be the `Command`: Command title:
- String command: String arguments?: any[]
+ Registry (a table) for client-side handlers, for custom server-commands
+ that are not in the LSP specification.
+
+ If an LSP response contains a command which is not found in
+ `vim.lsp.commands`, the command will be executed via the LSP server using
+ `workspace/executeCommand`.
+
+ Each key in the table is a unique command name, and each value is a
+ function which is called when an LSP action (code action, code lenses,
+ …) triggers the command.
+ • Argument 1 is the `Command`: >
+ Command
+ title: String
+ command: String
+ arguments?: any[]
+<
+ • Argument 2 is the |lsp-handler| `ctx`.
- The second argument is the `ctx` of |lsp-handler|
+ Example: >lua
+ vim.lsp.commands['java.action.generateToStringPrompt'] = function(_, ctx)
+ require("jdtls.async").run(function()
+ local _, result = request(ctx.bufnr, 'java/checkToStringStatus', ctx.params)
+ local fields = ui.pick_many(result.fields, 'Include item in toString?', function(x)
+ return string.format('%s: %s', x.name, x.type)
+ end)
+ local _, edit = request(ctx.bufnr, 'java/generateToString', { context = ctx.params; fields = fields; })
+ vim.lsp.util.apply_workspace_edit(edit, offset_encoding)
+ end)
+ end
+<
config({name}, {cfg}) *vim.lsp.config()*
- Update the configuration for an LSP client.
-
- Use name '*' to set default configuration for all clients.
+ Sets the default configuration for an LSP client (or all clients if the
+ special name "*" is used).
- Can also be table-assigned to redefine the configuration for a client.
+ Can also be accessed by table-indexing (`vim.lsp.config[…]`) to get the
+ resolved config, or redefine the config (instead of "merging" with the
+ config chain).
Examples:
- • Add a root marker for all clients: >lua
- vim.lsp.config('*', {
- root_markers = { '.git' },
- })
+ • Add root markers for ALL clients: >lua
+ vim.lsp.config('*', {
+ root_markers = { '.git', '.hg' },
+ })
<
- • Add additional capabilities to all clients: >lua
- vim.lsp.config('*', {
- capabilities = {
- textDocument = {
- semanticTokens = {
- multilineTokenSupport = true,
- }
- }
+ • Add capabilities to ALL clients: >lua
+ vim.lsp.config('*', {
+ capabilities = {
+ textDocument = {
+ semanticTokens = {
+ multilineTokenSupport = true,
}
- })
+ }
+ }
+ })
<
- • (Re-)define the configuration for clangd: >lua
- vim.lsp.config.clangd = {
- cmd = {
- 'clangd',
- '--clang-tidy',
- '--background-index',
- '--offset-encoding=utf-8',
- },
- root_markers = { '.clangd', 'compile_commands.json' },
- filetypes = { 'c', 'cpp' },
+ • Add root markers and capabilities for "clangd": >lua
+ vim.lsp.config('clangd', {
+ root_markers = { '.clang-format', 'compile_commands.json' },
+ capabilities = {
+ textDocument = {
+ completion = {
+ completionItem = {
+ snippetSupport = true,
+ }
+ }
}
+ }
+ })
+<
+ • (Re-)define the "clangd" configuration (overrides the resolved chain): >lua
+ vim.lsp.config.clangd = {
+ cmd = {
+ 'clangd',
+ '--clang-tidy',
+ '--background-index',
+ '--offset-encoding=utf-8',
+ },
+ root_markers = { '.clangd', 'compile_commands.json' },
+ filetypes = { 'c', 'cpp' },
+ }
<
- • Get configuration for luals: >lua
- local cfg = vim.lsp.config.luals
+ • Get the resolved configuration for "luals": >lua
+ local cfg = vim.lsp.config.luals
<
Parameters: ~
diff --git a/runtime/doc/news-0.10.txt b/runtime/doc/news-0.10.txt
@@ -213,7 +213,7 @@ The following new features were added.
• By default, the swapfile "ATTENTION" |E325| dialog is skipped if the
swapfile is owned by a running Nvim process, instead of prompting. If you
always want the swapfile dialog, delete the default SwapExists handler:
- `autocmd! nvim_swapfile`. |default-autocmds|
+ `autocmd! nvim.swapfile`. |default-autocmds|
• Navigating the |jumplist| with CTRL+O, CTRL+I behaves more intuitively
when deleting buffers, and avoids "invalid buffer" cases. #25461
• |:fclose| command.
diff --git a/runtime/doc/news-0.11.txt b/runtime/doc/news-0.11.txt
@@ -56,6 +56,9 @@ EDITOR
it moves to another help buffer.
• Bells from a |terminal| buffer are now silent by default, unless 'belloff'
option doesn't contain "term" or "all".
+• Renamed autocmd group `nvim_swapfile` to `nvim.swapfile`. |default-autocmds|
+ If you always want the swapfile dialog, delete the `nvim.swapfile` group:
+ `autocmd! nvim.swapfile`.
EVENTS
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
@@ -124,7 +124,7 @@ EVENTS
LSP
-• |vim.lsp.Config| gained `workspace_required`.
+• |vim.lsp.ClientConfig| gained `workspace_required`.
LUA
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
@@ -1796,41 +1796,40 @@ function vim.api.nvim_open_term(buffer, opts) end
--- region is hidden by setting `eob` flag of
--- 'fillchars' to a space char, and clearing the
--- `hl-EndOfBuffer` region in 'winhighlight'.
---- - border: Style of (optional) window border. This can either be a string
---- or an array. The string values are the same as those described in 'winborder'.
---- If it is an array, it should have a length of eight or any divisor of
---- eight. The array will specify the eight chars building up the border
---- in a clockwise fashion starting with the top-left corner. As an
---- example, the double box style could be specified as:
---- ```
---- [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
---- ```
---- If the number of chars are less than eight, they will be repeated. Thus
---- an ASCII border could be specified as
---- ```
---- [ "/", "-", \"\\\\\", "|" ],
---- ```
---- or all chars the same as
---- ```
---- [ "x" ].
---- ```
---- An empty string can be used to turn off a specific border, for instance,
+--- - border: (`string|string[]`) (defaults to 'winborder' option) Window border. The string form
+--- accepts the same values as the 'winborder' option. The array form must have a length of
+--- eight or any divisor of eight, specifying the chars that form the border in a clockwise
+--- fashion starting from the top-left corner. For example, the double-box style can be
+--- specified as:
--- ```
---- [ "", "", "", ">", "", "", "", "<" ]
+--- [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
--- ```
---- will only make vertical borders but not horizontal ones.
---- By default, `FloatBorder` highlight is used, which links to `WinSeparator`
---- when not defined. It could also be specified by character:
+--- If fewer than eight chars are given, they will be repeated. An ASCII border could be
+--- specified as:
--- ```
---- [ ["+", "MyCorner"], ["x", "MyBorder"] ].
+--- [ "/", "-", \"\\\\\", "|" ],
--- ```
---- - title: Title (optional) in window border, string or list.
+--- Or one char for all sides:
+--- ```
+--- [ "x" ].
+--- ```
+--- Empty string can be used to hide a specific border. This example will show only vertical
+--- borders, not horizontal:
+--- ```
+--- [ "", "", "", ">", "", "", "", "<" ]
+--- ```
+--- By default, `hl-FloatBorder` highlight is used, which links to `hl-WinSeparator` when not
+--- defined. Each border side can specify an optional highlight:
+--- ```
+--- [ ["+", "MyCorner"], ["x", "MyBorder"] ].
+--- ```
+--- - title: (optional) Title in window border, string or list.
--- List should consist of `[text, highlight]` tuples.
--- If string, or a tuple lacks a highlight, the default highlight group is `FloatTitle`.
--- - title_pos: Title position. Must be set with `title` option.
--- Value can be one of "left", "center", or "right".
--- Default is `"left"`.
---- - footer: Footer (optional) in window border, string or list.
+--- - footer: (optional) Footer in window border, string or list.
--- List should consist of `[text, highlight]` tuples.
--- If string, or a tuple lacks a highlight, the default highlight group is `FloatFooter`.
--- - footer_pos: Footer position. Must be set with `footer` option.
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
@@ -296,49 +296,64 @@ end
--- root_dir matches.
--- @field reuse_client? fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean
---- Update the configuration for an LSP client.
+--- Sets the default configuration for an LSP client (or _all_ clients if the special name "*" is
+--- used).
---
---- Use name '*' to set default configuration for all clients.
----
---- Can also be table-assigned to redefine the configuration for a client.
+--- Can also be accessed by table-indexing (`vim.lsp.config[…]`) to get the resolved config, or
+--- redefine the config (instead of "merging" with the config chain).
---
--- Examples:
---
---- - Add a root marker for all clients:
+--- - Add root markers for ALL clients:
+--- ```lua
+--- vim.lsp.config('*', {
+--- root_markers = { '.git', '.hg' },
+--- })
+--- ```
+--- - Add capabilities to ALL clients:
--- ```lua
---- vim.lsp.config('*', {
---- root_markers = { '.git' },
---- })
---- ```
---- - Add additional capabilities to all clients:
+--- vim.lsp.config('*', {
+--- capabilities = {
+--- textDocument = {
+--- semanticTokens = {
+--- multilineTokenSupport = true,
+--- }
+--- }
+--- }
+--- })
+--- ```
+--- - Add root markers and capabilities for "clangd":
--- ```lua
---- vim.lsp.config('*', {
---- capabilities = {
---- textDocument = {
---- semanticTokens = {
---- multilineTokenSupport = true,
---- }
---- }
---- }
---- })
---- ```
---- - (Re-)define the configuration for clangd:
+--- vim.lsp.config('clangd', {
+--- root_markers = { '.clang-format', 'compile_commands.json' },
+--- capabilities = {
+--- textDocument = {
+--- completion = {
+--- completionItem = {
+--- snippetSupport = true,
+--- }
+--- }
+--- }
+--- }
+--- })
+--- ```
+--- - (Re-)define the "clangd" configuration (overrides the resolved chain):
--- ```lua
---- vim.lsp.config.clangd = {
---- cmd = {
---- 'clangd',
---- '--clang-tidy',
---- '--background-index',
---- '--offset-encoding=utf-8',
---- },
---- root_markers = { '.clangd', 'compile_commands.json' },
---- filetypes = { 'c', 'cpp' },
---- }
---- ```
---- - Get configuration for luals:
+--- vim.lsp.config.clangd = {
+--- cmd = {
+--- 'clangd',
+--- '--clang-tidy',
+--- '--background-index',
+--- '--offset-encoding=utf-8',
+--- },
+--- root_markers = { '.clangd', 'compile_commands.json' },
+--- filetypes = { 'c', 'cpp' },
+--- }
+--- ```
+--- - Get the resolved configuration for "luals":
--- ```lua
---- local cfg = vim.lsp.config.luals
---- ```
+--- local cfg = vim.lsp.config.luals
+--- ```
---
--- @param name string
--- @param cfg vim.lsp.Config
@@ -1524,25 +1539,39 @@ function lsp.with(handler, override_config)
end
end
---- Registry for client side commands.
---- This is an extension point for plugins to handle custom commands which are
---- not part of the core language server protocol specification.
+--- Registry (a table) for client-side handlers, for custom server-commands that are not in the LSP
+--- specification.
---
---- The registry is a table where the key is a unique command name,
---- and the value is a function which is called if any LSP action
---- (code action, code lenses, ...) triggers the command.
+--- If an LSP response contains a command which is not found in `vim.lsp.commands`, the command will
+--- be executed via the LSP server using `workspace/executeCommand`.
---
---- If an LSP response contains a command for which no matching entry is
---- available in this registry, the command will be executed via the LSP server
---- using `workspace/executeCommand`.
+--- Each key in the table is a unique command name, and each value is a function which is called
+--- when an LSP action (code action, code lenses, …) triggers the command.
---
---- The first argument to the function will be the `Command`:
+--- - Argument 1 is the `Command`:
+--- ```
--- Command
--- title: String
--- command: String
--- arguments?: any[]
+--- ```
+--- - Argument 2 is the |lsp-handler| `ctx`.
+---
+--- Example:
+---
+--- ```lua
+--- vim.lsp.commands['java.action.generateToStringPrompt'] = function(_, ctx)
+--- require("jdtls.async").run(function()
+--- local _, result = request(ctx.bufnr, 'java/checkToStringStatus', ctx.params)
+--- local fields = ui.pick_many(result.fields, 'Include item in toString?', function(x)
+--- return string.format('%s: %s', x.name, x.type)
+--- end)
+--- local _, edit = request(ctx.bufnr, 'java/generateToString', { context = ctx.params; fields = fields; })
+--- vim.lsp.util.apply_workspace_edit(edit, offset_encoding)
+--- end)
+--- end
+--- ```
---
---- The second argument is the `ctx` of |lsp-handler|
--- @type table<string,function>
lsp.commands = setmetatable({}, {
__newindex = function(tbl, key, value)
diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua
@@ -76,6 +76,7 @@ local new_layout = {
['news.txt'] = true,
['news-0.9.txt'] = true,
['news-0.10.txt'] = true,
+ ['news-0.11.txt'] = true,
['nvim.txt'] = true,
['provider.txt'] = true,
['tui.txt'] = true,
diff --git a/src/nvim/api/win_config.c b/src/nvim/api/win_config.c
@@ -158,41 +158,40 @@
/// region is hidden by setting `eob` flag of
/// 'fillchars' to a space char, and clearing the
/// |hl-EndOfBuffer| region in 'winhighlight'.
-/// - border: Style of (optional) window border. This can either be a string
-/// or an array. The string values are the same as those described in 'winborder'.
-/// If it is an array, it should have a length of eight or any divisor of
-/// eight. The array will specify the eight chars building up the border
-/// in a clockwise fashion starting with the top-left corner. As an
-/// example, the double box style could be specified as:
-/// ```
-/// [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
-/// ```
-/// If the number of chars are less than eight, they will be repeated. Thus
-/// an ASCII border could be specified as
-/// ```
-/// [ "/", "-", \"\\\\\", "|" ],
-/// ```
-/// or all chars the same as
-/// ```
-/// [ "x" ].
-/// ```
-/// An empty string can be used to turn off a specific border, for instance,
+/// - border: (`string|string[]`) (defaults to 'winborder' option) Window border. The string form
+/// accepts the same values as the 'winborder' option. The array form must have a length of
+/// eight or any divisor of eight, specifying the chars that form the border in a clockwise
+/// fashion starting from the top-left corner. For example, the double-box style can be
+/// specified as:
/// ```
-/// [ "", "", "", ">", "", "", "", "<" ]
+/// [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ].
/// ```
-/// will only make vertical borders but not horizontal ones.
-/// By default, `FloatBorder` highlight is used, which links to `WinSeparator`
-/// when not defined. It could also be specified by character:
+/// If fewer than eight chars are given, they will be repeated. An ASCII border could be
+/// specified as:
/// ```
-/// [ ["+", "MyCorner"], ["x", "MyBorder"] ].
+/// [ "/", "-", \"\\\\\", "|" ],
/// ```
-/// - title: Title (optional) in window border, string or list.
+/// Or one char for all sides:
+/// ```
+/// [ "x" ].
+/// ```
+/// Empty string can be used to hide a specific border. This example will show only vertical
+/// borders, not horizontal:
+/// ```
+/// [ "", "", "", ">", "", "", "", "<" ]
+/// ```
+/// By default, |hl-FloatBorder| highlight is used, which links to |hl-WinSeparator| when not
+/// defined. Each border side can specify an optional highlight:
+/// ```
+/// [ ["+", "MyCorner"], ["x", "MyBorder"] ].
+/// ```
+/// - title: (optional) Title in window border, string or list.
/// List should consist of `[text, highlight]` tuples.
/// If string, or a tuple lacks a highlight, the default highlight group is `FloatTitle`.
/// - title_pos: Title position. Must be set with `title` option.
/// Value can be one of "left", "center", or "right".
/// Default is `"left"`.
-/// - footer: Footer (optional) in window border, string or list.
+/// - footer: (optional) Footer in window border, string or list.
/// List should consist of `[text, highlight]` tuples.
/// If string, or a tuple lacks a highlight, the default highlight group is `FloatFooter`.
/// - footer_pos: Footer position. Must be set with `footer` option.
