GitHub/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim synced 2025-07-17 01:31:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: lsp, lua #33682

Browse Source 
- sort fields alphabetically.
- in the `vim.lsp.Client` docs, reference `vim.lsp.ClientConfig` instead
  of duplicating its docs.
- cleanup lots of redundant-yet-drifted field docs.
This commit is contained in:
Justin M. Keyes
2025-04-27 15:44:11 -07:00
parent 4296511087
commit 714622fb45
9 changed files with 275 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
runtime/doc/dev_vimpatch.txt
View File

@ -311,7 +311,7 @@ Nvim's filetype detection behavior matches Vim, but is implemented as part of
|vim.filetype| (see `$VIMRUNTIME/lua/vim/filetype.lua`). The logic is encoded in |vim.filetype| (see `$VIMRUNTIME/lua/vim/filetype.lua`). The logic is encoded in
three tables, listed in order of precedence (the first match is returned): three tables, listed in order of precedence (the first match is returned):
1. `filename` for literal full path or basename lookup; 1. `filename` for literal full path or basename lookup;
2. `pattern` for matching filenames or paths against |lua-patterns|, optimized 2. `pattern` for matching filenames or paths against |lua-pattern|s, optimized
for fast lookup; for fast lookup;
3. `extension` for literal extension lookup. 3. `extension` for literal extension lookup.

317
runtime/doc/lsp.txt
View File

@ -705,27 +705,25 @@ Lua module: vim.lsp *lsp-core*
• {cmd}? (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`) • {cmd}? (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
See `cmd` in |vim.lsp.ClientConfig|. See `cmd` in |vim.lsp.ClientConfig|.
• {filetypes}? (`string[]`) Filetypes the client will attach to, if • {filetypes}? (`string[]`) Filetypes the client will attach to, if
activated by `vim.lsp.enable()`. If not provided, activated by `vim.lsp.enable()`. If not provided, the
then the client will attach to all filetypes. client will attach to all filetypes.
• {root_markers}? (`string[]`) Directory markers (.e.g. '.git/') where • {reuse_client}? (`fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean`)
the LSP server will base its workspaceFolders, Predicate which decides if a client should be
rootUri, and rootPath on initialization. Unused if re-used. Used on all running clients. The default
`root_dir` is provided. implementation re-uses a client if name and root_dir
matches.
• {root_dir}? (`string|fun(bufnr: integer, on_dir:fun(root_dir?:string))`) • {root_dir}? (`string|fun(bufnr: integer, on_dir:fun(root_dir?:string))`)
*lsp-root_dir()* Directory where the LSP server will *lsp-root_dir()* Directory where the LSP server will
base its workspaceFolders, rootUri, and rootPath on base its workspaceFolders, rootUri, and rootPath on
initialization. The function form receives a buffer initialization. The function form receives a buffer
number and `on_dir` callback, which must be called to number and `on_dir` callback which it must call to
provide root_dir as a string. LSP will not be provide root_dir, or LSP will not be activated for
activated for the buffer unless `on_dir` is called; the buffer. Thus a `root_dir()` function can
thus a `root_dir()` function can dynamically decide dynamically decide per-buffer whether to activate (or
whether to activate (or skip) LSP per-buffer. See skip) LSP. See example at |vim.lsp.enable()|.
example at |vim.lsp.enable()|. • {root_markers}? (`string[]`) Directory markers (e.g. ".git/",
• {reuse_client}? (`fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean`) "package.json") used to decide `root_dir`. Unused if
Predicate used to decide if a client should be `root_dir` is provided.
re-used. Used on all running clients. The default
implementation re-uses a client if name and root_dir
matches.
buf_attach_client({bufnr}, {client_id}) *vim.lsp.buf_attach_client()* buf_attach_client({bufnr}, {client_id}) *vim.lsp.buf_attach_client()*
@ -1148,65 +1146,17 @@ Lua module: vim.lsp.client *lsp-client*
*vim.lsp.Client* *vim.lsp.Client*
Fields: ~ Fields: ~
• {id} (`integer`) The id allocated to the client.
• {name} (`string`) If a name is specified on creation,
that will be used. Otherwise it is just the
client id. This is used for logs and messages.
• {rpc} (`vim.lsp.rpc.PublicClient`) RPC client
object, for low level interaction with the
client. See |vim.lsp.rpc.start()|.
• {offset_encoding} (`string`) Called "position encoding" in LSP
spec, the encoding used for communicating with
the server. You can modify this in the
`config`'s `on_init` method before text is
sent to the server.
• {handlers} (`table<string,lsp.Handler>`) The handlers
used by the client as described in
|lsp-handler|.
• {requests} (`table<integer,{ type: string, bufnr: integer, method: string}?>`)
The current pending requests in flight to the
server. Entries are key-value pairs with the
key being the request id while the value is a
table with `type`, `bufnr`, and `method`
key-value pairs. `type` is either "pending"
for an active request, or "cancel" for a
cancel request. It will be "complete"
ephemerally while executing |LspRequest|
autocmds when replies are received from the
server.
• {config} (`vim.lsp.ClientConfig`) copy of the table
that was passed by the user to
|vim.lsp.start()|. See |vim.lsp.ClientConfig|.
• {server_capabilities} (`lsp.ServerCapabilities?`) Response from the
server sent on `initialize` describing the
server's capabilities.
• {server_info} (`lsp.ServerInfo?`) Response from the server
sent on `initialize` describing information
about the server.
• {progress} (`vim.lsp.Client.Progress`) A ring buffer
(|vim.ringbuf()|) containing progress messages
sent by the server. See
|vim.lsp.Client.Progress|.
• {initialized} (`true?`)
• {workspace_folders} (`lsp.WorkspaceFolder[]?`) The workspace
folders configured in the client when the
server starts. This property is only available
if the client supports workspace folders. It
can be `null` if the client supports workspace
folders but none are configured.
• {root_dir} (`string?`)
• {attached_buffers} (`table<integer,true>`) • {attached_buffers} (`table<integer,true>`)
• {capabilities} (`lsp.ClientCapabilities`) Capabilities
provided by the client (editor or tool), at
startup.
• {commands} (`table<string,fun(command: lsp.Command, ctx: table)>`) • {commands} (`table<string,fun(command: lsp.Command, ctx: table)>`)
Table of command name to function which is Client commands. See |vim.lsp.ClientConfig|.
called if any LSP action (code action, code • {config} (`vim.lsp.ClientConfig`) Copy of the config
lenses, ...) triggers the command. Client passed to |vim.lsp.start()|. See
commands take precedence over the global |vim.lsp.ClientConfig|.
command registry. • {dynamic_capabilities} (`lsp.DynamicCapabilities`) Capabilities
• {settings} (`lsp.LSPObject`) Map with language server provided at runtime (after startup).
specific settings. These are returned to the
language server if requested via
`workspace/configuration`. Keys are
case-sensitive.
• {flags} (`table`) A table with flags for the client. • {flags} (`table`) A table with flags for the client.
The current (experimental) flags are: The current (experimental) flags are:
• {allow_incremental_sync}? (`boolean`, • {allow_incremental_sync}? (`boolean`,
@ -1223,9 +1173,41 @@ Lua module: vim.lsp.client *lsp-client*
false, nvim exits immediately after sending false, nvim exits immediately after sending
the "shutdown" request to the server. the "shutdown" request to the server.
• {get_language_id} (`fun(bufnr: integer, filetype: string): string`) • {get_language_id} (`fun(bufnr: integer, filetype: string): string`)
• {capabilities} (`lsp.ClientCapabilities`) The capabilities See |vim.lsp.ClientConfig|.
provided by the client (editor or tool) • {handlers} (`table<string,lsp.Handler>`) See
• {dynamic_capabilities} (`lsp.DynamicCapabilities`) |vim.lsp.ClientConfig|.
• {id} (`integer`) The id allocated to the client.
• {initialized} (`true?`)
• {name} (`string`) See |vim.lsp.ClientConfig|.
• {offset_encoding} (`string`) See |vim.lsp.ClientConfig|.
• {progress} (`vim.lsp.Client.Progress`) A ring buffer
(|vim.ringbuf()|) containing progress messages
sent by the server. See
|vim.lsp.Client.Progress|.
• {requests} (`table<integer,{ type: string, bufnr: integer, method: string}?>`)
The current pending requests in flight to the
server. Entries are key-value pairs with the
key being the request id while the value is a
table with `type`, `bufnr`, and `method`
key-value pairs. `type` is either "pending"
for an active request, or "cancel" for a
cancel request. It will be "complete"
ephemerally while executing |LspRequest|
autocmds when replies are received from the
server.
• {root_dir} (`string?`) See |vim.lsp.ClientConfig|.
• {rpc} (`vim.lsp.rpc.PublicClient`) RPC client
object, for low level interaction with the
client. See |vim.lsp.rpc.start()|.
• {server_capabilities} (`lsp.ServerCapabilities?`) Response from the
server sent on `initialize` describing the
server's capabilities.
• {server_info} (`lsp.ServerInfo?`) Response from the server
sent on `initialize` describing server
information (e.g. version).
• {settings} (`lsp.LSPObject`) See |vim.lsp.ClientConfig|.
• {workspace_folders} (`lsp.WorkspaceFolder[]?`) See
|vim.lsp.ClientConfig|.
• {request} (`fun(self: vim.lsp.Client, method: string, params: table?, handler: lsp.Handler?, bufnr: integer?): boolean, integer?`) • {request} (`fun(self: vim.lsp.Client, method: string, params: table?, handler: lsp.Handler?, bufnr: integer?): boolean, integer?`)
See |Client:request()|. See |Client:request()|.
• {request_sync} (`fun(self: vim.lsp.Client, method: string, params: table, timeout_ms: integer?, bufnr: integer?): {err: lsp.ResponseError?, result:any}?, string?`) • {request_sync} (`fun(self: vim.lsp.Client, method: string, params: table, timeout_ms: integer?, bufnr: integer?): {err: lsp.ResponseError?, result:any}?, string?`)
@ -1255,6 +1237,23 @@ Lua module: vim.lsp.client *lsp-client*
*vim.lsp.ClientConfig* *vim.lsp.ClientConfig*
Fields: ~ Fields: ~
• {before_init}? (`fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)`)
Callback invoked before the LSP "initialize"
phase, where `params` contains the parameters
being sent to the server and `config` is the
config that was passed to |vim.lsp.start()|.
You can use this to modify parameters before
they are sent.
• {capabilities}? (`lsp.ClientCapabilities`) Map overriding the
default capabilities defined by
|vim.lsp.protocol.make_client_capabilities()|,
passed to the language server on
initialization. Hint: use
make_client_capabilities() and modify its
result.
• Note: To send an empty dictionary use
|vim.empty_dict()|, else it will be encoded
as an array.
• {cmd} (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`) • {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 server (treated as in |jobstart()|, must be
@ -1270,101 +1269,24 @@ Lua module: vim.lsp.client *lsp-client*
|vim.lsp.rpc.connect()| |vim.lsp.rpc.connect()|
• {cmd_cwd}? (`string`, default: cwd) Directory to launch • {cmd_cwd}? (`string`, default: cwd) Directory to launch
the `cmd` process. Not related to `root_dir`. the `cmd` process. Not related to `root_dir`.
• {cmd_env}? (`table`) Environment flags to pass to the LSP • {cmd_env}? (`table`) Environment variables passed to the
on spawn. Must be specified using a table. LSP process on spawn. Non-string values are
Non-string values are coerced to string. coerced to string. Example: >lua
Example: >lua { PORT = 8080; HOST = '0.0.0.0'; }
{ PORT = 8080; HOST = "0.0.0.0"; }
< <
• {commands}? (`table<string,fun(command: lsp.Command, ctx: table)>`)
Client commands. Map of command names to
user-defined functions. Commands passed to
`start()` take precedence over the global
command registry. Each key must be a unique
command name, and the value is a function which
is called if any LSP action (code action, code
lenses, …) triggers the command.
• {detached}? (`boolean`, default: true) Daemonize the server • {detached}? (`boolean`, default: true) Daemonize the server
process so that it runs in a separate process process so that it runs in a separate process
group from Nvim. Nvim will shutdown the process group from Nvim. Nvim will shutdown the process
on exit, but if Nvim fails to exit cleanly this on exit, but if Nvim fails to exit cleanly this
could leave behind orphaned server processes. could leave behind orphaned server processes.
• {workspace_folders}? (`lsp.WorkspaceFolder[]`) List of workspace
folders passed to the language server. For
backwards compatibility rootUri and rootPath
will be derived from the first workspace folder
in this list. See `workspaceFolders` in the LSP
spec.
• {workspace_required}? (`boolean`) (default false) Server requires a
workspace (no "single file" support). Note:
Without a workspace, cross-file features
(navigation, hover) may or may not work
depending on the language server, even if the
server doesn't require a workspace.
• {capabilities}? (`lsp.ClientCapabilities`) Map overriding the
default capabilities defined by
|vim.lsp.protocol.make_client_capabilities()|,
passed to the language server on
initialization. Hint: use
make_client_capabilities() and modify its
result.
• Note: To send an empty dictionary use
|vim.empty_dict()|, else it will be encoded
as an array.
• {handlers}? (`table<string,function>`) Map of language
server method names to |lsp-handler|
• {settings}? (`lsp.LSPObject`) Map with language server
specific settings. See the {settings} in
|vim.lsp.Client|.
• {commands}? (`table<string,fun(command: lsp.Command, ctx: table)>`)
Table that maps string of clientside commands
to user-defined functions. Commands passed to
`start()` take precedence over the global
command registry. Each key must be a unique
command name, and the value is a function which
is called if any LSP action (code action, code
lenses, ...) triggers the command.
• {init_options}? (`lsp.LSPObject`) Values to pass in the
initialization request as
`initializationOptions`. See `initialize` in
the LSP spec.
• {name}? (`string`, default: client-id) Name in log
messages.
• {get_language_id}? (`fun(bufnr: integer, filetype: string): string`)
Language ID as string. Defaults to the buffer
filetype.
• {offset_encoding}? (`'utf-8'|'utf-16'|'utf-32'`) Called "position
encoding" in LSP spec, the encoding that the
LSP server expects. Client does not verify this
is correct.
• {on_error}? (`fun(code: integer, err: string)`) Callback
invoked when the client operation throws an
error. `code` is a number describing the error.
Other arguments may be passed depending on the
error kind. See `vim.lsp.rpc.client_errors` for
possible errors. Use
`vim.lsp.rpc.client_errors[code]` to get
human-friendly name.
• {before_init}? (`fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)`)
Callback invoked before the LSP "initialize"
phase, where `params` contains the parameters
being sent to the server and `config` is the
config that was passed to |vim.lsp.start()|.
You can use this to modify parameters before
they are sent.
• {on_init}? (`elem_or_list<fun(client: vim.lsp.Client, init_result: lsp.InitializeResult)>`)
Callback invoked after LSP "initialize", where
`result` is a table of `capabilities` and
anything else the server may send. For example,
clangd sends `init_result.offsetEncoding` if
`capabilities.offsetEncoding` was sent to it.
You can only modify the
`client.offset_encoding` here before any
notifications are sent.
• {on_exit}? (`elem_or_list<fun(code: integer, signal: integer, client_id: integer)>`)
Callback invoked on client exit.
• code: exit code of the process
• signal: number describing the signal used to
terminate (if any)
• client_id: client handle
• {on_attach}? (`elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>`)
Callback invoked when client attaches to a
buffer.
• {trace}? (`'off'|'messages'|'verbose'`, default: "off")
Passed directly to the language server in the
initialize request. Invalid/empty values will
• {flags}? (`table`) A table with flags for the client. • {flags}? (`table`) A table with flags for the client.
The current (experimental) flags are: The current (experimental) flags are:
• {allow_incremental_sync}? (`boolean`, • {allow_incremental_sync}? (`boolean`,
@ -1380,9 +1302,72 @@ Lua module: vim.lsp.client *lsp-client*
request before sending kill -15. If set to request before sending kill -15. If set to
false, nvim exits immediately after sending false, nvim exits immediately after sending
the "shutdown" request to the server. the "shutdown" request to the server.
• {get_language_id}? (`fun(bufnr: integer, filetype: string): string`)
Language ID as string. Defaults to the buffer
filetype.
• {handlers}? (`table<string,function>`) Map of LSP method
names to |lsp-handler|s.
• {init_options}? (`lsp.LSPObject`) Values to pass in the
initialization request as
`initializationOptions`. See `initialize` in
the LSP spec.
• {name}? (`string`) (default: client-id) Name in logs
and user messages.
• {offset_encoding}? (`'utf-8'|'utf-16'|'utf-32'`) Called "position
encoding" in LSP spec. The encoding that the
LSP server expects, used for communication. Not
validated. Can be modified in `on_init` before
text is sent to the server.
• {on_attach}? (`elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>`)
Callback invoked when client attaches to a
buffer.
• {on_error}? (`fun(code: integer, err: string)`) Callback
invoked when the client operation throws an
error. `code` is a number describing the error.
Other arguments may be passed depending on the
error kind. See `vim.lsp.rpc.client_errors` for
possible errors. Use
`vim.lsp.rpc.client_errors[code]` to get
human-friendly name.
• {on_exit}? (`elem_or_list<fun(code: integer, signal: integer, client_id: integer)>`)
Callback invoked on client exit.
• code: exit code of the process
• signal: number describing the signal used to
terminate (if any)
• client_id: client handle
• {on_init}? (`elem_or_list<fun(client: vim.lsp.Client, init_result: lsp.InitializeResult)>`)
Callback invoked after LSP "initialize", where
`result` is a table of `capabilities` and
anything else the server may send. For example,
clangd sends `init_result.offsetEncoding` if
`capabilities.offsetEncoding` was sent to it.
You can only modify the
`client.offset_encoding` here before any
notifications are sent.
• {root_dir}? (`string`) Directory where the LSP server will • {root_dir}? (`string`) Directory where the LSP server will
base its workspaceFolders, rootUri, and base its workspaceFolders, rootUri, and
rootPath on initialization. rootPath on initialization.
• {settings}? (`lsp.LSPObject`) Map of language
server-specific settings, decided by the
client. Sent to the LS if requested via
`workspace/configuration`. Keys are
case-sensitive.
• {trace}? (`'off'|'messages'|'verbose'`, default: "off")
Passed directly to the language server in the
initialize request. Invalid/empty values will
• {workspace_folders}? (`lsp.WorkspaceFolder[]`) List of workspace
folders passed to the language server. For
backwards compatibility rootUri and rootPath
are derived from the first workspace folder in
this list. Can be `null` if the client supports
workspace folders but none are configured. See
`workspaceFolders` in LSP spec.
• {workspace_required}? (`boolean`) (default false) Server requires a
workspace (no "single file" support). Note:
Without a workspace, cross-file features
(navigation, hover) may or may not work
depending on the language server, even if the
server doesn't require a workspace.
Client:cancel_request({id}) *Client:cancel_request()* Client:cancel_request({id}) *Client:cancel_request()*

10
runtime/doc/lua.txt
View File

@ -171,7 +171,7 @@ added. But visually, this small bit of sugar gets reasonably close to a
*lua-regex* *lua-regex*
Lua intentionally does not support regular expressions, instead it has limited Lua intentionally does not support regular expressions, instead it has limited
|lua-patterns| which avoid the performance pitfalls of extended regex. Lua |lua-pattern|s which avoid the performance pitfalls of extended regex. Lua
scripts can also use Vim regex via |vim.regex()|. scripts can also use Vim regex via |vim.regex()|.
Examples: >lua Examples: >lua
@ -2022,7 +2022,7 @@ vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()*
See also: ~ See also: ~
• |string.gmatch()| • |string.gmatch()|
• |vim.split()| • |vim.split()|
• |lua-patterns| • |lua-pattern|s
• https://www.lua.org/pil/20.2.html • https://www.lua.org/pil/20.2.html
• http://lua-users.org/wiki/StringLibraryTutorial • http://lua-users.org/wiki/StringLibraryTutorial
@ -2115,7 +2115,7 @@ vim.list_slice({list}, {start}, {finish}) *vim.list_slice()*
(`any[]`) Copy of table sliced from start to finish (inclusive) (`any[]`) Copy of table sliced from start to finish (inclusive)
vim.pesc({s}) *vim.pesc()* vim.pesc({s}) *vim.pesc()*
Escapes magic chars in |lua-patterns|. Escapes magic chars in |lua-pattern|s.
Parameters: ~ Parameters: ~
• {s} (`string`) String to escape • {s} (`string`) String to escape
@ -2370,7 +2370,7 @@ vim.trim({s}) *vim.trim()*
(`string`) String with whitespace removed from its beginning and end (`string`) String with whitespace removed from its beginning and end
See also: ~ See also: ~
• |lua-patterns| • |lua-pattern|s
• https://www.lua.org/pil/20.2.html • https://www.lua.org/pil/20.2.html
*vim.validate()* *vim.validate()*
@ -2670,7 +2670,7 @@ vim.filetype.add({filetypes}) *vim.filetype.add()*
Filetype mappings can be added either by extension or by filename (either Filetype mappings can be added either by extension or by filename (either
the "tail" or the full file path). The full file path is checked first, the "tail" or the full file path). The full file path is checked first,
followed by the file name. If a match is not found using the filename, followed by the file name. If a match is not found using the filename,
then the filename is matched against the list of |lua-patterns| (sorted by then the filename is matched against the list of |lua-pattern|s (sorted by
priority) until a match is found. Lastly, if pattern matching does not priority) until a match is found. Lastly, if pattern matching does not
find a filetype, then the file extension is used. find a filetype, then the file extension is used.

2
runtime/doc/luaref.txt
View File

@ -4150,7 +4150,7 @@ string.upper({s}) *string.upper()*
locale. locale.
------------------------------------------------------------------------------ ------------------------------------------------------------------------------
5.4.1 Patterns *lua-pattern* *lua-patterns* 5.4.1 Patterns *lua-pattern*
A character class is used to represent a set of characters. The following A character class is used to represent a set of characters. The following
combinations are allowed in describing a character class: combinations are allowed in describing a character class:

2
runtime/doc/treesitter.txt
View File

@ -120,7 +120,7 @@ The following predicates are built in:
match. match.
`lua-match?` *treesitter-predicate-lua-match?* `lua-match?` *treesitter-predicate-lua-match?*
Match |lua-patterns| against the text corresponding to a node, Match |lua-pattern|s against the text corresponding to a node,
similar to `match?` similar to `match?`
`any-lua-match?` *treesitter-predicate-any-lua-match?* `any-lua-match?` *treesitter-predicate-any-lua-match?*

2
runtime/lua/vim/filetype.lua
View File

@ -2605,7 +2605,7 @@ end
--- Filetype mappings can be added either by extension or by filename (either --- Filetype mappings can be added either by extension or by filename (either
--- the "tail" or the full file path). The full file path is checked first, --- the "tail" or the full file path). The full file path is checked first,
--- followed by the file name. If a match is not found using the filename, then --- followed by the file name. If a match is not found using the filename, then
--- the filename is matched against the list of |lua-patterns| (sorted by priority) --- the filename is matched against the list of |lua-pattern|s (sorted by priority)
--- until a match is found. Lastly, if pattern matching does not find a --- until a match is found. Lastly, if pattern matching does not find a
--- filetype, then the file extension is used. --- filetype, then the file extension is used.
--- ---

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

@ -277,25 +277,24 @@ end
--- See `cmd` in [vim.lsp.ClientConfig]. --- See `cmd` in [vim.lsp.ClientConfig].
--- @field cmd? string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient --- @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()`. --- Filetypes the client will attach to, if activated by `vim.lsp.enable()`. If not provided, the
--- If not provided, then the client will attach to all filetypes. --- client will attach to all filetypes.
--- @field filetypes? string[] --- @field filetypes? string[]
--- ---
--- Directory markers (.e.g. '.git/') where the LSP server will base its workspaceFolders, rootUri, --- Predicate which decides if a client should be re-used. Used on all running clients. The default
--- and rootPath on initialization. Unused if `root_dir` is provided. --- implementation re-uses a client if name and root_dir matches.
--- @field root_markers? string[] --- @field reuse_client? fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean
--- ---
--- [lsp-root_dir()]() Directory where the LSP server will base its workspaceFolders, rootUri, and --- [lsp-root_dir()]() Directory where the LSP server will base its workspaceFolders, rootUri, and
--- rootPath on initialization. The function form receives a buffer number and `on_dir` callback, --- rootPath on initialization. The function form receives a buffer number and `on_dir` callback
--- which must be called to provide root_dir as a string. LSP will not be activated for the buffer --- which it must call to provide root_dir, or LSP will not be activated for the buffer. Thus
--- unless `on_dir` is called; thus a `root_dir()` function can dynamically decide whether to --- a `root_dir()` function can dynamically decide per-buffer whether to activate (or skip) LSP. See
--- activate (or skip) LSP per-buffer. See example at |vim.lsp.enable()|. --- example at |vim.lsp.enable()|.
--- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string)) --- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string))
--- ---
--- Predicate used to decide if a client should be re-used. Used on all --- Directory markers (e.g. ".git/", "package.json") used to decide `root_dir`. Unused if `root_dir`
--- running clients. The default implementation re-uses a client if name and --- is provided.
--- root_dir matches. --- @field root_markers? string[]
--- @field reuse_client? fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean
--- Update the configuration for an LSP client. --- Update the configuration for an LSP client.
--- ---

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

@ -30,6 +30,19 @@ local validate = vim.validate
--- @field exit_timeout integer|false --- @field exit_timeout integer|false
--- @class vim.lsp.ClientConfig --- @class vim.lsp.ClientConfig
---
--- Callback invoked before the LSP "initialize" phase, where `params` contains the parameters
--- being sent to the server and `config` is the config that was passed to |vim.lsp.start()|.
--- You can use this to modify parameters before they are sent.
--- @field before_init? fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)
---
--- Map overriding the default capabilities defined by |vim.lsp.protocol.make_client_capabilities()|,
--- passed to the language server on initialization. Hint: use make_client_capabilities() and modify
--- its result.
--- - Note: To send an empty dictionary use |vim.empty_dict()|, else it will be encoded as an
--- array.
--- @field capabilities? lsp.ClientCapabilities
---
--- 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 --- 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 --- "~" are not expanded), or function that creates an RPC client. Function receives
@ -43,125 +56,129 @@ local validate = vim.validate
--- (default: cwd) --- (default: cwd)
--- @field cmd_cwd? string --- @field cmd_cwd? string
--- ---
--- Environment flags to pass to the LSP on spawn. --- Environment variables passed to the LSP process on spawn. Non-string values are coerced to
--- Must be specified using a table. --- string.
--- Non-string values are coerced to string.
--- Example: --- Example:
--- ```lua --- ```lua
--- { PORT = 8080; HOST = "0.0.0.0"; } --- { PORT = 8080; HOST = '0.0.0.0'; }
--- ``` --- ```
--- @field cmd_env? table --- @field cmd_env? table
--- ---
--- Client commands. Map of command names to user-defined functions. Commands passed to `start()`
--- take precedence over the global command registry. Each key must be a unique command name, and
--- the value is a function which is called if any LSP action (code action, code lenses, …) triggers
--- the command.
--- @field commands? table<string,fun(command: lsp.Command, ctx: table)>
---
--- Daemonize the server process so that it runs in a separate process group from Nvim. --- Daemonize the server process so that it runs in a separate process group from Nvim.
--- Nvim will shutdown the process on exit, but if Nvim fails to exit cleanly this could leave --- Nvim will shutdown the process on exit, but if Nvim fails to exit cleanly this could leave
--- behind orphaned server processes. --- behind orphaned server processes.
--- (default: true) --- (default: true)
--- @field detached? boolean --- @field detached? boolean
--- ---
--- List of workspace folders passed to the language server. --- A table with flags for the client. The current (experimental) flags are:
--- For backwards compatibility rootUri and rootPath will be derived from the first workspace --- @field flags? vim.lsp.Client.Flags
--- folder in this list. See `workspaceFolders` in the LSP spec.
--- @field workspace_folders? lsp.WorkspaceFolder[]
--- ---
--- (default false) Server requires a workspace (no "single file" support). Note: Without --- Language ID as string. Defaults to the buffer filetype.
--- a workspace, cross-file features (navigation, hover) may or may not work depending on the --- @field get_language_id? fun(bufnr: integer, filetype: string): string
--- language server, even if the server doesn't require a workspace.
--- @field workspace_required? boolean
--- ---
--- Map overriding the default capabilities defined by |vim.lsp.protocol.make_client_capabilities()|, --- Map of LSP method names to |lsp-handler|s.
--- passed to the language server on initialization. Hint: use make_client_capabilities() and modify
--- its result.
--- - Note: To send an empty dictionary use |vim.empty_dict()|, else it will be encoded as an
--- array.
--- @field capabilities? lsp.ClientCapabilities
---
--- Map of language server method names to |lsp-handler|
--- @field handlers? table<string,function> --- @field handlers? table<string,function>
--- ---
--- Map with language server specific settings.
--- See the {settings} in |vim.lsp.Client|.
--- @field settings? lsp.LSPObject
---
--- Table that maps string of clientside commands to user-defined functions.
--- Commands passed to `start()` take precedence over the global command registry. Each key
--- must be a unique command name, and the value is a function which is called if any LSP action
--- (code action, code lenses, ...) triggers the command.
--- @field commands? table<string,fun(command: lsp.Command, ctx: table)>
---
--- Values to pass in the initialization request as `initializationOptions`. See `initialize` in --- Values to pass in the initialization request as `initializationOptions`. See `initialize` in
--- the LSP spec. --- the LSP spec.
--- @field init_options? lsp.LSPObject --- @field init_options? lsp.LSPObject
--- ---
--- Name in log messages. --- (default: client-id) Name in logs and user messages.
--- (default: client-id)
--- @field name? string --- @field name? string
--- ---
--- Language ID as string. Defaults to the buffer filetype. --- Called "position encoding" in LSP spec. The encoding that the LSP server expects, used for
--- @field get_language_id? fun(bufnr: integer, filetype: string): string --- communication. Not validated. Can be modified in `on_init` before text is sent to the server.
---
--- Called "position encoding" in LSP spec, the encoding that the LSP server expects.
--- Client does not verify this is correct.
--- @field offset_encoding? 'utf-8'|'utf-16'|'utf-32' --- @field offset_encoding? 'utf-8'|'utf-16'|'utf-32'
--- ---
--- Callback invoked when client attaches to a buffer.
--- @field on_attach? elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>
---
--- Callback invoked when the client operation throws an error. `code` is a number describing the error. --- Callback invoked when the client operation throws an error. `code` is a number describing the error.
--- Other arguments may be passed depending on the error kind. See `vim.lsp.rpc.client_errors` --- Other arguments may be passed depending on the error kind. See `vim.lsp.rpc.client_errors`
--- for possible errors. Use `vim.lsp.rpc.client_errors[code]` to get human-friendly name. --- for possible errors. Use `vim.lsp.rpc.client_errors[code]` to get human-friendly name.
--- @field on_error? fun(code: integer, err: string) --- @field on_error? fun(code: integer, err: string)
--- ---
--- Callback invoked before the LSP "initialize" phase, where `params` contains the parameters
--- being sent to the server and `config` is the config that was passed to |vim.lsp.start()|.
--- You can use this to modify parameters before they are sent.
--- @field before_init? fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)
---
--- Callback invoked after LSP "initialize", where `result` is a table of `capabilities` and
--- anything else the server may send. For example, clangd sends `init_result.offsetEncoding` if
--- `capabilities.offsetEncoding` was sent to it. You can only modify the `client.offset_encoding`
--- here before any notifications are sent.
--- @field on_init? elem_or_list<fun(client: vim.lsp.Client, init_result: lsp.InitializeResult)>
---
--- Callback invoked on client exit. --- Callback invoked on client exit.
--- - code: exit code of the process --- - code: exit code of the process
--- - signal: number describing the signal used to terminate (if any) --- - signal: number describing the signal used to terminate (if any)
--- - client_id: client handle --- - client_id: client handle
--- @field on_exit? elem_or_list<fun(code: integer, signal: integer, client_id: integer)> --- @field on_exit? elem_or_list<fun(code: integer, signal: integer, client_id: integer)>
--- ---
--- Callback invoked when client attaches to a buffer. --- Callback invoked after LSP "initialize", where `result` is a table of `capabilities` and
--- @field on_attach? elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)> --- anything else the server may send. For example, clangd sends `init_result.offsetEncoding` if
--- `capabilities.offsetEncoding` was sent to it. You can only modify the `client.offset_encoding`
--- here before any notifications are sent.
--- @field on_init? elem_or_list<fun(client: vim.lsp.Client, init_result: lsp.InitializeResult)>
---
--- Directory where the LSP server will base its workspaceFolders, rootUri, and rootPath on initialization.
--- @field root_dir? string
---
--- Map of language server-specific settings, decided by the client. Sent to the LS if requested via
--- `workspace/configuration`. Keys are case-sensitive.
--- @field settings? lsp.LSPObject
--- ---
--- Passed directly to the language server in the initialize request. Invalid/empty values will --- Passed directly to the language server in the initialize request. Invalid/empty values will
--- (default: "off") --- (default: "off")
--- @field trace? 'off'|'messages'|'verbose' --- @field trace? 'off'|'messages'|'verbose'
--- ---
--- A table with flags for the client. The current (experimental) flags are: --- List of workspace folders passed to the language server. For backwards compatibility rootUri and
--- @field flags? vim.lsp.Client.Flags --- rootPath are derived from the first workspace folder in this list. Can be `null` if the client
--- supports workspace folders but none are configured. See `workspaceFolders` in LSP spec.
--- @field workspace_folders? lsp.WorkspaceFolder[]
--- ---
--- Directory where the LSP server will base its workspaceFolders, rootUri, and rootPath on initialization. --- (default false) Server requires a workspace (no "single file" support). Note: Without
--- @field root_dir? string --- a workspace, cross-file features (navigation, hover) may or may not work depending on the
--- language server, even if the server doesn't require a workspace.
--- @field workspace_required? boolean
--- @class vim.lsp.Client.Progress: vim.Ringbuf<{token: integer|string, value: any}> --- @class vim.lsp.Client.Progress: vim.Ringbuf<{token: integer|string, value: any}>
--- @field pending table<lsp.ProgressToken,lsp.LSPAny> --- @field pending table<lsp.ProgressToken,lsp.LSPAny>
--- @class vim.lsp.Client --- @class vim.lsp.Client
--- ---
--- @field attached_buffers table<integer,true>
---
--- Capabilities provided by the client (editor or tool), at startup.
--- @field capabilities lsp.ClientCapabilities
---
--- Client commands. See [vim.lsp.ClientConfig].
--- @field commands table<string,fun(command: lsp.Command, ctx: table)>
---
--- Copy of the config passed to |vim.lsp.start()|.
--- @field config vim.lsp.ClientConfig
---
--- Capabilities provided at runtime (after startup).
--- @field dynamic_capabilities lsp.DynamicCapabilities
---
--- A table with flags for the client. The current (experimental) flags are:
--- @field flags vim.lsp.Client.Flags
---
--- See [vim.lsp.ClientConfig].
--- @field get_language_id fun(bufnr: integer, filetype: string): string
---
--- See [vim.lsp.ClientConfig].
--- @field handlers table<string,lsp.Handler>
---
--- The id allocated to the client. --- The id allocated to the client.
--- @field id integer --- @field id integer
--- ---
--- If a name is specified on creation, that will be used. Otherwise it is just --- @field initialized true?
--- the client id. This is used for logs and messages. ---
--- See [vim.lsp.ClientConfig].
--- @field name string --- @field name string
--- ---
--- RPC client object, for low level interaction with the client. --- See [vim.lsp.ClientConfig].
--- See |vim.lsp.rpc.start()|.
--- @field rpc vim.lsp.rpc.PublicClient
---
--- Called "position encoding" in LSP spec,
--- the encoding used for communicating with the server.
--- You can modify this in the `config`'s `on_init` method
--- before text is sent to the server.
--- @field offset_encoding string --- @field offset_encoding string
--- ---
--- The handlers used by the client as described in |lsp-handler|. --- A ring buffer (|vim.ringbuf()|) containing progress messages
--- @field handlers table<string,lsp.Handler> --- sent by the server.
--- @field progress vim.lsp.Client.Progress
--- ---
--- The current pending requests in flight to the server. Entries are key-value --- The current pending requests in flight to the server. Entries are key-value
--- pairs with the key being the request id while the value is a table with --- pairs with the key being the request id while the value is a table with
@ -171,34 +188,25 @@ local validate = vim.validate
--- are received from the server. --- are received from the server.
--- @field requests table<integer,{ type: string, bufnr: integer, method: string}?> --- @field requests table<integer,{ type: string, bufnr: integer, method: string}?>
--- ---
--- copy of the table that was passed by the user --- See [vim.lsp.ClientConfig].
--- to |vim.lsp.start()|.
--- @field config vim.lsp.ClientConfig
---
--- Response from the server sent on `initialize` describing the server's
--- capabilities.
--- @field server_capabilities lsp.ServerCapabilities?
---
--- Response from the server sent on `initialize` describing information about
--- the server.
--- @field server_info lsp.ServerInfo?
---
--- A ring buffer (|vim.ringbuf()|) containing progress messages
--- sent by the server.
--- @field progress vim.lsp.Client.Progress
---
--- @field initialized true?
---
--- The workspace folders configured in the client when the server starts.
--- This property is only available if the client supports workspace folders.
--- It can be `null` if the client supports workspace folders but none are
--- configured.
--- @field workspace_folders lsp.WorkspaceFolder[]?
--- @field root_dir string? --- @field root_dir string?
--- ---
--- @field attached_buffers table<integer,true> --- RPC client object, for low level interaction with the client.
--- See |vim.lsp.rpc.start()|.
--- @field rpc vim.lsp.rpc.PublicClient
---
--- Response from the server sent on `initialize` describing the server's capabilities.
--- @field server_capabilities lsp.ServerCapabilities?
---
--- Response from the server sent on `initialize` describing server information (e.g. version).
--- @field server_info lsp.ServerInfo?
---
--- See [vim.lsp.ClientConfig].
--- @field settings lsp.LSPObject
---
--- See [vim.lsp.ClientConfig].
--- @field workspace_folders lsp.WorkspaceFolder[]?
--- ---
--- @field private _log_prefix string
--- ---
--- Track this so that we can escalate automatically if we've already tried a --- Track this so that we can escalate automatically if we've already tried a
--- graceful shutdown --- graceful shutdown
@ -208,26 +216,8 @@ local validate = vim.validate
--- trace = "off" | "messages" | "verbose"; --- trace = "off" | "messages" | "verbose";
--- @field private _trace 'off'|'messages'|'verbose' --- @field private _trace 'off'|'messages'|'verbose'
--- ---
--- Table of command name to function which is called if any LSP action
--- (code action, code lenses, ...) triggers the command.
--- Client commands take precedence over the global command registry.
--- @field commands table<string,fun(command: lsp.Command, ctx: table)>
---
--- Map with language server specific settings. These are returned to the
--- language server if requested via `workspace/configuration`. Keys are
--- case-sensitive.
--- @field settings lsp.LSPObject
---
--- A table with flags for the client. The current (experimental) flags are:
--- @field flags vim.lsp.Client.Flags
---
--- @field get_language_id fun(bufnr: integer, filetype: string): string
---
--- The capabilities provided by the client (editor or tool)
--- @field capabilities lsp.ClientCapabilities
--- @field private registrations table<string,lsp.Registration[]> --- @field private registrations table<string,lsp.Registration[]>
--- @field dynamic_capabilities lsp.DynamicCapabilities --- @field private _log_prefix string
---
--- @field private _before_init_cb? vim.lsp.client.before_init_cb --- @field private _before_init_cb? vim.lsp.client.before_init_cb
--- @field private _on_attach_cbs vim.lsp.client.on_attach_cb[] --- @field private _on_attach_cbs vim.lsp.client.on_attach_cb[]
--- @field private _on_init_cbs vim.lsp.client.on_init_cb[] --- @field private _on_init_cbs vim.lsp.client.on_init_cb[]

6
runtime/lua/vim/shared.lua
View File

@ -95,7 +95,7 @@ end
--- ---
--- @see |string.gmatch()| --- @see |string.gmatch()|
--- @see |vim.split()| --- @see |vim.split()|
--- @see |lua-patterns| --- @see |lua-pattern|s
--- @see https://www.lua.org/pil/20.2.html --- @see https://www.lua.org/pil/20.2.html
--- @see http://lua-users.org/wiki/StringLibraryTutorial --- @see http://lua-users.org/wiki/StringLibraryTutorial
--- ---
@ -784,7 +784,7 @@ end
--- Trim whitespace (Lua pattern "%s") from both sides of a string. --- Trim whitespace (Lua pattern "%s") from both sides of a string.
--- ---
---@see |lua-patterns| ---@see |lua-pattern|s
---@see https://www.lua.org/pil/20.2.html ---@see https://www.lua.org/pil/20.2.html
---@param s string String to trim ---@param s string String to trim
---@return string String with whitespace removed from its beginning and end ---@return string String with whitespace removed from its beginning and end
@ -793,7 +793,7 @@ function vim.trim(s)
return s:match('^%s*(.*%S)') or '' return s:match('^%s*(.*%S)') or ''
end end
--- Escapes magic chars in |lua-patterns|. --- Escapes magic chars in |lua-pattern|s.
--- ---
---@see https://github.com/rxi/lume ---@see https://github.com/rxi/lume
---@param s string String to escape ---@param s string String to escape