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

doc(lsp): format arguments to start_client() (#21980)

Browse Source 
docs(lsp): format arguments to start_client()
This commit is contained in:
Lewis Russell
2023-01-24 18:04:15 +00:00
committed by GitHub
parent cd613712b1
commit 9166116c67
2 changed files with 195 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
runtime/doc/lsp.txt
View File

@@ -832,128 +832,118 @@ start({config}, {opts}) *vim.lsp.start()*
start_client({config}) *vim.lsp.start_client()* start_client({config}) *vim.lsp.start_client()*
Starts and initializes a client with the given configuration. Starts and initializes a client with the given configuration.
Parameter `cmd` is required. Field `cmd` in {config} is required.
The following parameters describe fields in the {config} table.
Parameters: ~ Parameters: ~
• {cmd} (table|string|fun(dispatchers: table):table) • {config} (table) Configuration for the server:
command string or list treated like |jobstart()|. • cmd: (table|string|fun(dispatchers: table):table) command
The command must launch the language server string or list treated like |jobstart()|. The command must
process. `cmd` can also be a function that launch the language server process. `cmd` can also be a
creates an RPC client. The function receives a function that creates an RPC client. The function receives
dispatchers table and must return a table with a dispatchers table and must return a table with the
the functions `request`, `notify`, `is_closing` functions `request`, `notify`, `is_closing` and
and `terminate` See |vim.lsp.rpc.request()| and `terminate` See |vim.lsp.rpc.request()| and
|vim.lsp.rpc.notify()| For TCP there is a |vim.lsp.rpc.notify()| For TCP there is a built-in rpc
built-in rpc client factory: client factory: |vim.lsp.rpc.connect()|
|vim.lsp.rpc.connect()| • cmd_cwd: (string, default=|getcwd()|) Directory to launch
• {cmd_cwd} (string, default=|getcwd()|) 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 on
• {cmd_env} (table) Environment flags to pass to the LSP on spawn. Can be specified using keys like a map or as a list
spawn. Can be specified using keys like a map or with `k=v` pairs or both. Non-string values are coerced to string.
as a list with `k=v` pairs or both. Non-string values are coerced to Example: >
string. Example: >
{ "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; } { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
< <
• {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
group from Nvim. Nvim will shutdown the process Nvim. Nvim will shutdown the process on exit, but if Nvim
on exit, but if Nvim fails to exit cleanly this fails to exit cleanly this could leave behind orphaned
could leave behind orphaned server processes. server processes.
• {workspace_folders} (table) List of workspace folders passed to the • workspace_folders: (table) List of workspace folders
language server. For backwards compatibility passed to the language server. For backwards compatibility
rootUri and rootPath will be derived from the rootUri and rootPath will be derived from the first
first workspace folder in this list. See workspace folder in this list. See `workspaceFolders` in
`workspaceFolders` in the LSP spec. the LSP spec.
• {capabilities} Map overriding the default capabilities defined • capabilities: Map overriding the default capabilities
by |vim.lsp.protocol.make_client_capabilities()|, defined by |vim.lsp.protocol.make_client_capabilities()|,
passed to the language server on initialization. passed to the language server on initialization. Hint: use
Hint: use make_client_capabilities() and modify make_client_capabilities() and modify its result.
its result. • Note: To send an empty dictionary use
• Note: To send an empty dictionary use `{[vim.type_idx]=vim.types.dictionary}`, else it will be
`{[vim.type_idx]=vim.types.dictionary}`, else encoded as an array.
it will be encoded as an array.
• {handlers} Map of language server method names to • handlers: Map of language server method names to
|lsp-handler| |lsp-handler|
• {settings} Map with language server specific settings. These • settings: Map with language server specific settings.
are returned to the language server if requested These are returned to the language server if requested via
via `workspace/configuration`. Keys are `workspace/configuration`. Keys are case-sensitive.
case-sensitive. • commands: table Table that maps string of clientside
• {commands} (table) Table that maps string of clientside commands to user-defined functions. Commands passed to
commands to user-defined functions. Commands start_client take precedence over the global command
passed to start_client take precedence over the registry. Each key must be a unique command name, and the
global command registry. Each key must be a value is a function which is called if any LSP action
unique command name, and the value is a function (code action, code lenses, ...) triggers the command.
which is called if any LSP action (code action, • init_options Values to pass in the initialization request
code lenses, ...) triggers the command. as `initializationOptions`. See `initialize` in the LSP
• {init_options} Values to pass in the initialization request as spec.
`initializationOptions`. See `initialize` in the • name: (string, default=client-id) Name in log messages.
LSP spec. • get_language_id: function(bufnr, filetype) -> language ID
• {name} (string, default=client-id) Name in log messages. as string. Defaults to the filetype.
• {get_language_id} function(bufnr, filetype) -> language ID as • offset_encoding: (default="utf-16") One of "utf-8",
string. Defaults to the filetype. "utf-16", or "utf-32" which is the encoding that the LSP
• {offset_encoding} (default="utf-16") One of "utf-8", "utf-16", or server expects. Client does not verify this is correct.
"utf-32" which is the encoding that the LSP • on_error: Callback with parameters (code, ...), invoked
server expects. Client does not verify this is when the client operation throws an error. `code` is a
correct. number describing the error. Other arguments may be passed
• {on_error} Callback with parameters (code, ...), invoked depending on the error kind. See
when the client operation throws an error. `code` `vim.lsp.rpc.client_errors` for possible errors. Use
is a number describing the error. Other arguments `vim.lsp.rpc.client_errors[code]` to get human-friendly
may be passed depending on the error kind. See name.
`vim.lsp.rpc.client_errors` for possible errors. • before_init: Callback with parameters (initialize_params,
Use `vim.lsp.rpc.client_errors[code]` to get config) invoked before the LSP "initialize" phase, where
human-friendly name. `params` contains the parameters being sent to the server
• {before_init} Callback with parameters (initialize_params, and `config` is the config that was passed to
config) invoked before the LSP "initialize" |vim.lsp.start_client()|. You can use this to modify
phase, where `params` contains the parameters parameters before they are sent.
being sent to the server and `config` is the • on_init: Callback (client, initialize_result) invoked
config that was passed to after LSP "initialize", where `result` is a table of
|vim.lsp.start_client()|. You can use this to `capabilities` and anything else the server may send. For
modify parameters before they are sent. example, clangd sends `initialize_result.offsetEncoding`
• {on_init} Callback (client, initialize_result) invoked if `capabilities.offsetEncoding` was sent to it. You can
after LSP "initialize", where `result` is a table only modify the `client.offset_encoding` here before any
of `capabilities` and anything else the server notifications are sent. Most language servers expect to be
may send. For example, clangd sends sent client specified settings after initialization.
`initialize_result.offsetEncoding` if Neovim does not make this assumption. A
`capabilities.offsetEncoding` was sent to it. You `workspace/didChangeConfiguration` notification should be
can only modify the `client.offset_encoding` here sent to the server during on_init.
before any notifications are sent. Most language • on_exit Callback (code, signal, client_id) invoked on
servers expect to be sent client specified client exit.
settings after initialization. Neovim does not • code: exit code of the process
make this assumption. A • signal: number describing the signal used to terminate
`workspace/didChangeConfiguration` notification (if any)
should be sent to the server during on_init. • client_id: client handle
• {on_exit} Callback (code, signal, client_id) invoked on
client exit. • on_attach: Callback (client, bufnr) invoked when client
• code: exit code of the process attaches to a buffer.
• signal: number describing the signal used to • trace: ("off" | "messages" | "verbose" | nil) passed
terminate (if any) directly to the language server in the initialize request.
• client_id: client handle Invalid/empty values will default to "off"
• {on_attach} Callback (client, bufnr) invoked when client • flags: A table with flags for the client. The current
attaches to a buffer. (experimental) flags are:
• {trace} "off" | "messages" | "verbose" | nil passed • allow_incremental_sync (bool, default true): Allow using
directly to the language server in the initialize incremental sync for buffer edits
request. Invalid/empty values will default to • debounce_text_changes (number, default 150): Debounce
"off" didChange notifications to the server by the given
• {flags} A table with flags for the client. The current number in milliseconds. No debounce occurs if nil
(experimental) flags are: • exit_timeout (number|boolean, default false):
• allow_incremental_sync (bool, default true): Milliseconds to wait for server to exit cleanly after
Allow using incremental sync for buffer edits sending the "shutdown" request before sending kill -15.
• debounce_text_changes (number, default 150): If set to false, nvim exits immediately after sending
Debounce didChange notifications to the server the "shutdown" request to the server.
by the given number in milliseconds. No
debounce occurs if nil • root_dir: (string) Directory where the LSP server will
• exit_timeout (number|boolean, default false): base its workspaceFolders, rootUri, and rootPath on
Milliseconds to wait for server to exit cleanly initialization.
after sending the "shutdown" request before
sending kill -15. If set to false, nvim exits
immediately after sending the "shutdown"
request to the server.
• {root_dir} (string) Directory where the LSP server will base
its workspaceFolders, rootUri, and rootPath on
initialization.
Return: ~ Return: ~
Client id. |vim.lsp.get_client_by_id()| Note: client may not be fully Client id. |vim.lsp.get_client_by_id()| Note: client may not be fully

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

@@ -897,115 +897,114 @@ end
-- --
--- Starts and initializes a client with the given configuration. --- Starts and initializes a client with the given configuration.
--- ---
--- Parameter `cmd` is required. --- Field `cmd` in {config} is required.
--- ---
--- The following parameters describe fields in the {config} table. ---@param config (table) Configuration for the server:
--- - cmd: (table|string|fun(dispatchers: table):table) command string or
--- list treated like |jobstart()|. The command must launch the language server
--- process. `cmd` can also be a function that creates an RPC client.
--- The function receives a dispatchers table and must return a table with the
--- functions `request`, `notify`, `is_closing` and `terminate`
--- See |vim.lsp.rpc.request()| and |vim.lsp.rpc.notify()|
--- For TCP there is a built-in rpc client factory: |vim.lsp.rpc.connect()|
--- ---
--- - cmd_cwd: (string, default=|getcwd()|) Directory to launch
--- the `cmd` process. Not related to `root_dir`.
--- ---
---@param cmd: (table|string|fun(dispatchers: table):table) command string or --- - cmd_env: (table) Environment flags to pass to the LSP on
--- list treated like |jobstart()|. The command must launch the language server --- spawn. Can be specified using keys like a map or as a list with `k=v`
--- process. `cmd` can also be a function that creates an RPC client. --- pairs or both. Non-string values are coerced to string.
--- The function receives a dispatchers table and must return a table with the --- Example:
--- functions `request`, `notify`, `is_closing` and `terminate` --- <pre>
--- See |vim.lsp.rpc.request()| and |vim.lsp.rpc.notify()| --- { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
--- For TCP there is a built-in rpc client factory: |vim.lsp.rpc.connect()| --- </pre>
--- ---
---@param cmd_cwd: (string, default=|getcwd()|) Directory to launch --- - detached: (boolean, default true) Daemonize the server process so that it runs in a
--- the `cmd` process. Not related to `root_dir`. --- separate process group from Nvim. Nvim will shutdown the process on exit, but if Nvim fails to
--- exit cleanly this could leave behind orphaned server processes.
--- ---
---@param cmd_env: (table) Environment flags to pass to the LSP on --- - workspace_folders: (table) List of workspace folders passed to the
--- spawn. Can be specified using keys like a map or as a list with `k=v` --- language server. For backwards compatibility rootUri and rootPath will be
--- pairs or both. Non-string values are coerced to string. --- derived from the first workspace folder in this list. See `workspaceFolders` in
--- Example: --- the LSP spec.
--- <pre>
--- { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
--- </pre>
--- ---
---@param detached: (boolean, default true) Daemonize the server process so that it runs in a --- - capabilities: Map overriding the default capabilities defined by
--- separate process group from Nvim. Nvim will shutdown the process on exit, but if Nvim fails to --- |vim.lsp.protocol.make_client_capabilities()|, passed to the language
--- exit cleanly this could leave behind orphaned server processes. --- server on initialization. Hint: use make_client_capabilities() and modify
--- its result.
--- - Note: To send an empty dictionary use
--- `{[vim.type_idx]=vim.types.dictionary}`, else it will be encoded as an
--- array.
--- ---
---@param workspace_folders (table) List of workspace folders passed to the --- - handlers: Map of language server method names to |lsp-handler|
--- 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.
--- ---
---@param capabilities Map overriding the default capabilities defined by --- - settings: Map with language server specific settings. These are
--- |vim.lsp.protocol.make_client_capabilities()|, passed to the language --- returned to the language server if requested via `workspace/configuration`.
--- server on initialization. Hint: use make_client_capabilities() and modify --- Keys are case-sensitive.
--- its result.
--- - Note: To send an empty dictionary use
--- `{[vim.type_idx]=vim.types.dictionary}`, else it will be encoded as an
--- array.
--- ---
---@param handlers Map of language server method names to |lsp-handler| --- - commands: table Table that maps string of clientside commands to user-defined functions.
--- Commands passed to start_client 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.
--- ---
---@param settings Map with language server specific settings. These are --- - init_options Values to pass in the initialization request
--- returned to the language server if requested via `workspace/configuration`. --- as `initializationOptions`. See `initialize` in the LSP spec.
--- Keys are case-sensitive.
--- ---
---@param commands table Table that maps string of clientside commands to user-defined functions. --- - name: (string, default=client-id) Name in log messages.
--- Commands passed to start_client 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.
--- ---
---@param init_options Values to pass in the initialization request --- - get_language_id: function(bufnr, filetype) -> language ID as string.
--- as `initializationOptions`. See `initialize` in the LSP spec. --- Defaults to the filetype.
--- ---
---@param name (string, default=client-id) Name in log messages. --- - offset_encoding: (default="utf-16") One of "utf-8", "utf-16",
--- or "utf-32" which is the encoding that the LSP server expects. Client does
--- not verify this is correct.
--- ---
---@param get_language_id function(bufnr, filetype) -> language ID as string. --- - on_error: Callback with parameters (code, ...), invoked
--- Defaults to the filetype. --- 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.
--- ---
---@param offset_encoding (default="utf-16") One of "utf-8", "utf-16", --- - before_init: Callback with parameters (initialize_params, config)
--- or "utf-32" which is the encoding that the LSP server expects. Client does --- invoked before the LSP "initialize" phase, where `params` contains the
--- not verify this is correct. --- parameters being sent to the server and `config` is the config that was
--- passed to |vim.lsp.start_client()|. You can use this to modify parameters before
--- they are sent.
--- ---
---@param on_error Callback with parameters (code, ...), invoked --- - on_init: Callback (client, initialize_result) invoked after LSP
--- when the client operation throws an error. `code` is a number describing --- "initialize", where `result` is a table of `capabilities` and anything else
--- the error. Other arguments may be passed depending on the error kind. See --- the server may send. For example, clangd sends
--- `vim.lsp.rpc.client_errors` for possible errors. --- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was
--- Use `vim.lsp.rpc.client_errors[code]` to get human-friendly name. --- sent to it. You can only modify the `client.offset_encoding` here before
--- any notifications are sent. Most language servers expect to be sent client specified settings after
--- initialization. Neovim does not make this assumption. A
--- `workspace/didChangeConfiguration` notification should be sent
--- to the server during on_init.
--- ---
---@param before_init Callback with parameters (initialize_params, config) --- - on_exit Callback (code, signal, client_id) invoked on client
--- 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_client()|. You can use this to modify parameters before
--- they are sent.
---
---@param on_init Callback (client, initialize_result) invoked after LSP
--- "initialize", where `result` is a table of `capabilities` and anything else
--- the server may send. For example, clangd sends
--- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was
--- sent to it. You can only modify the `client.offset_encoding` here before
--- any notifications are sent. Most language servers expect to be sent client specified settings after
--- initialization. Neovim does not make this assumption. A
--- `workspace/didChangeConfiguration` notification should be sent
--- to the server during on_init.
---
---@param on_exit Callback (code, signal, client_id) invoked on client
--- exit. --- 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
--- ---
---@param on_attach Callback (client, bufnr) invoked when client --- - on_attach: Callback (client, bufnr) invoked when client
--- attaches to a buffer. --- attaches to a buffer.
--- ---
---@param trace: "off" | "messages" | "verbose" | nil passed directly to the language --- - trace: ("off" | "messages" | "verbose" | nil) passed directly to the language
--- server in the initialize request. Invalid/empty values will default to "off" --- server in the initialize request. Invalid/empty values will default to "off"
---@param flags: A table with flags for the client. The current (experimental) flags are:
--- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits
--- - debounce_text_changes (number, default 150): Debounce didChange
--- notifications to the server by the given number in milliseconds. No debounce
--- occurs if nil
--- - exit_timeout (number|boolean, default false): Milliseconds to wait for server to
--- exit cleanly after sending the "shutdown" request before sending kill -15.
--- If set to false, nvim exits immediately after sending the "shutdown" request to the server.
--- ---
---@param root_dir string Directory where the LSP --- - flags: A table with flags for the client. The current (experimental) flags are:
--- server will base its workspaceFolders, rootUri, and rootPath --- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits
--- on initialization. --- - debounce_text_changes (number, default 150): Debounce didChange
--- notifications to the server by the given number in milliseconds. No debounce
--- occurs if nil
--- - exit_timeout (number|boolean, default false): Milliseconds to wait for server to
--- exit cleanly after sending the "shutdown" request before sending kill -15.
--- If set to false, nvim exits immediately after sending the "shutdown" request to the server.
---
--- - root_dir: (string) Directory where the LSP
--- server will base its workspaceFolders, rootUri, and rootPath
--- on initialization.
--- ---
---@returns Client id. |vim.lsp.get_client_by_id()| Note: client may not be ---@returns Client id. |vim.lsp.get_client_by_id()| Note: client may not be
--- fully initialized. Use `on_init` to do any actions once --- fully initialized. Use `on_init` to do any actions once