diff options
Diffstat (limited to 'runtime/doc/lsp.txt')
| -rw-r--r-- | runtime/doc/lsp.txt | 1331 |
1 files changed, 742 insertions, 589 deletions
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 215515a2d9..5e97628f42 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -24,57 +24,62 @@ QUICKSTART *lsp-quickstart* Nvim provides an LSP client, but the servers are provided by third parties. Follow these steps to get LSP features: - 1. Install language servers using your package manager or by - following the upstream installation instruction. +1. Install language servers using your package manager or by following the + upstream installation instruction. You can find language servers here: + https://microsoft.github.io/language-server-protocol/implementors/servers/ - A list of language servers is available at: +2. Configure the LSP client per language server. See |vim.lsp.start()| or use + this minimal example as a guide: >lua - https://microsoft.github.io/language-server-protocol/implementors/servers/ - - 2. Configure the LSP client per language server. - A minimal example: ->lua vim.lsp.start({ name = 'my-server-name', cmd = {'name-of-language-server-executable'}, root_dir = vim.fs.dirname(vim.fs.find({'setup.py', 'pyproject.toml'}, { upward = true })[1]), }) < - See |vim.lsp.start()| for details. +3. Check that the server attached to the buffer: > + :lua =vim.lsp.get_clients() - 3. Configure keymaps and autocmds to utilize LSP features. - See |lsp-config|. +4. Configure keymaps and autocmds to use LSP features. See |lsp-config|. *lsp-config* - -Starting a LSP client will automatically report diagnostics via -|vim.diagnostic|. Read |vim.diagnostic.config()| to learn how to customize the -display. - -It also sets some buffer options if the options are otherwise empty and if the -language server supports the functionality. - -- 'omnifunc' is set to |vim.lsp.omnifunc()|. This allows to trigger completion - using |i_CTRL-X_CTRL-O| + *lsp-defaults* +When the LSP client starts it enables diagnostics |vim.diagnostic| (see +|vim.diagnostic.config()| to customize). It also sets various default options, +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. + +- '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 go-to-definition, |:tjump|, and keymaps like |CTRL-]|, |CTRL-W_]|, |CTRL-W_}| to utilize the language server. -- 'formatexpr' is set to |vim.lsp.formatexpr()| if both 'formatprg' and - 'formatexpr' are empty. This allows to format lines via |gq| if the language - server supports it. +- 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via + |gq| if the language server supports it. + - To opt out of this use |gw| instead of gq, or set 'formatexpr' on LspAttach. +- |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or + a custom keymap for `K` exists. + + *lsp-defaults-disable* +To override the above defaults, set or unset the options on |LspAttach|: >lua + vim.api.nvim_create_autocmd('LspAttach', { + callback = function(ev) + vim.bo[ev.buf].formatexpr = nil + vim.bo[ev.buf].omnifunc = nil + vim.keymap.del("n", "K", { buffer = ev.buf }) + end, + }) -To use other LSP features like hover, rename, etc. you can setup some -additional keymaps. It's recommended to setup them in a |LspAttach| autocmd to -ensure they're only active if there is a LSP client running. An example: ->lua +To use other LSP features like hover, rename, etc. you can set other keymaps +on |LspAttach|. Example: >lua vim.api.nvim_create_autocmd('LspAttach', { callback = function(args) vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf }) end, }) -< -The most used functions are: +The most common functions are: - |vim.lsp.buf.hover()| - |vim.lsp.buf.format()| @@ -98,11 +103,9 @@ calls behind capability checks: < To learn what capabilities are available you can run the following command in -a buffer with a started LSP client: +a buffer with a started LSP client: >vim ->vim - :lua =vim.lsp.get_active_clients()[1].server_capabilities -< + :lua =vim.lsp.get_clients()[1].server_capabilities Full list of features provided by default can be found in |lsp-buf|. @@ -110,35 +113,28 @@ Full list of features provided by default can be found in |lsp-buf|. FAQ *lsp-faq* - Q: How to force-reload LSP? - A: Stop all clients, then reload the buffer. >vim - - :lua vim.lsp.stop_client(vim.lsp.get_active_clients()) +- A: Stop all clients, then reload the buffer. >vim + :lua vim.lsp.stop_client(vim.lsp.get_clients()) :edit - Q: Why isn't completion working? - A: In the buffer where you want to use LSP, check that 'omnifunc' is set to - "v:lua.vim.lsp.omnifunc": >vim - - :verbose set omnifunc? - -< Some other plugin may be overriding the option. To avoid that, you could - set the option in an |after-directory| ftplugin, e.g. - "after/ftplugin/python.vim". +- A: In the buffer where you want to use LSP, check that 'omnifunc' is set to + "v:lua.vim.lsp.omnifunc": `:verbose set omnifunc?` + - Some other plugin may be overriding the option. To avoid that you could + set the option in an |after-directory| ftplugin, e.g. + "after/ftplugin/python.vim". - Q: How do I run a request synchronously (e.g. for formatting on file save)? - A: Check if the function has an `async` parameter and set the value to - false. - - E.g. code formatting: >vim +- A: Check if the function has an `async` parameter and set the value to + false. E.g. code formatting: >vim " Auto-format *.rs (rust) files prior to saving them " (async = false is the default for format) autocmd BufWritePre *.rs lua vim.lsp.buf.format({ async = false }) - < *lsp-vs-treesitter* - Q: How do LSP and Treesitter compare? - A: LSP requires a client and language server. The language server uses +- A: LSP requires a client and language server. The language server uses semantic analysis to understand code at a project level. This provides language servers with the ability to rename across files, find definitions in external libraries and more. @@ -161,128 +157,85 @@ The `vim.lsp.buf_…` functions perform operations for all LSP clients attached to the given buffer. |lsp-buf| LSP request/response handlers are implemented as Lua functions (see -|lsp-handler|). The |vim.lsp.handlers| table defines default handlers used -when creating a new client. Keys are LSP method names: >vim - - :lua print(vim.inspect(vim.tbl_keys(vim.lsp.handlers))) -< +|lsp-handler|). *lsp-method* -Methods are the names of requests and notifications as defined by the LSP -specification. These LSP requests/notifications are defined by default: - - callHierarchy/incomingCalls - callHierarchy/outgoingCalls - textDocument/codeAction - textDocument/completion - textDocument/declaration* - textDocument/definition - textDocument/documentHighlight - textDocument/documentSymbol - textDocument/formatting - textDocument/hover - textDocument/implementation* - textDocument/publishDiagnostics - textDocument/rangeFormatting - textDocument/references - textDocument/rename - textDocument/signatureHelp - textDocument/typeDefinition* - window/logMessage - window/showMessage - window/showDocument - window/showMessageRequest - workspace/applyEdit - workspace/symbol - -* NOTE: These are sometimes not implemented by servers. - - *lsp-handler* +Requests and notifications defined by the LSP specification are referred to as +"LSP methods". The Nvim LSP client provides default handlers in the global +|vim.lsp.handlers| table, you can list them with this command: >vim -lsp-handlers are functions with special signatures that are designed to handle -responses and notifications from LSP servers. - -For |lsp-request|, each |lsp-handler| has this signature: > - - function(err, result, ctx, config) + :lua vim.print(vim.tbl_keys(vim.lsp.handlers)) < - Parameters: ~ - {err} (table|nil) - When the language server is unable to complete a - request, a table with information about the error is - sent. Otherwise, it is `nil`. See |lsp-response|. - {result} (Result | Params | nil) - When the language server is able to successfully - complete a request, this contains the `result` key of - the response. See |lsp-response|. - {ctx} (table) - Context describes additional calling state associated - with the handler. It consists of the following key, - value pairs: - - {method} (string) - The |lsp-method| name. - {client_id} (number) - The ID of the |vim.lsp.client|. - {bufnr} (Buffer) - Buffer handle, or 0 for current. - {params} (table|nil) - The parameters used in the original - request which resulted in this handler - call. - {config} (table) - Configuration for the handler. - - Each handler can define its own configuration table - that allows users to customize the behavior of a - particular handler. - - To configure a particular |lsp-handler|, see: - |lsp-handler-configuration| - - - Returns: ~ - The |lsp-handler| can respond by returning two values: `result, err` - Where `err` must be shaped like an RPC error: - `{ code, message, data? }` +They are also listed below. Note that handlers depend on server support: they +won't run if your server doesn't support them. + +- callHierarchy/incomingCalls +- callHierarchy/outgoingCalls +- textDocument/codeAction +- textDocument/completion +- textDocument/declaration* +- textDocument/definition +- textDocument/diagnostic +- textDocument/documentHighlight +- textDocument/documentSymbol +- textDocument/formatting +- textDocument/hover +- textDocument/implementation* +- textDocument/inlayHint +- textDocument/publishDiagnostics +- textDocument/rangeFormatting +- textDocument/references +- textDocument/rename +- textDocument/semanticTokens/full +- textDocument/semanticTokens/full/delta +- textDocument/signatureHelp +- textDocument/typeDefinition* +- window/logMessage +- window/showMessage +- window/showDocument +- window/showMessageRequest +- workspace/applyEdit +- workspace/configuration +- workspace/executeCommand +- workspace/inlayHint/refresh +- workspace/symbol +- workspace/workspaceFolders - You can use |vim.lsp.rpc.rpc_response_error()| to create this object. + *lsp-handler* +LSP handlers are functions that handle |lsp-response|s to requests made by Nvim +to the server. (Notifications, as opposed to requests, are fire-and-forget: +there is no response, so they can't be handled. |lsp-notification|) -For |lsp-notification|, each |lsp-handler| has this signature: > +Each response handler has this signature: > - function(err, result, ctx, config) + function(err, result, ctx, config) < Parameters: ~ - {err} (nil) - This is always `nil`. - See |lsp-notification| - {result} (Result) - This contains the `params` key of the notification. - See |lsp-notification| - {ctx} (table) - Context describes additional calling state associated - with the handler. It consists of the following key, - value pairs: - - {method} (string) - The |lsp-method| name. - {client_id} (number) - The ID of the |vim.lsp.client|. - {config} (table) - Configuration for the handler. - - Each handler can define its own configuration table - that allows users to customize the behavior of a - particular handler. - - For an example, see: - |vim.lsp.diagnostic.on_publish_diagnostics()| - - To configure a particular |lsp-handler|, see: - |lsp-handler-configuration| + - {err} (table|nil) Error info dict, or `nil` if the request + completed. + - {result} (Result | Params | nil) `result` key of the |lsp-response| or + `nil` if the request failed. + - {ctx} (table) Table of calling state associated with the + handler, with these keys: + - {method} (string) |lsp-method| name. + - {client_id} (number) |vim.lsp.client| identifier. + - {bufnr} (Buffer) Buffer handle. + - {params} (table|nil) Request parameters table. + - {version} (number) Document version at time of + request. Handlers can compare this to the + current document version to check if the + response is "stale". See also |b:changedtick|. + - {config} (table) Handler-defined configuration table, which allows + users to customize handler behavior. + For an example, see: + |vim.lsp.diagnostic.on_publish_diagnostics()| + To configure a particular |lsp-handler|, see: + |lsp-handler-configuration| Returns: ~ - The |lsp-handler|'s return value will be ignored. + Two values `result, err` where `err` is shaped like an RPC error: > + { code, message, data? } +< You can use |vim.lsp.rpc.rpc_response_error()| to create this object. *lsp-handler-configuration* @@ -355,42 +308,37 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method Handlers can be set by: - Setting a field in vim.lsp.handlers. *vim.lsp.handlers* - vim.lsp.handlers is a global table that contains the default mapping of - |lsp-method| names to |lsp-handlers|. - - To override the handler for the `"textDocument/definition"` method: >lua + vim.lsp.handlers is a global table that contains the default mapping of + |lsp-method| names to |lsp-handlers|. To override the handler for the + `"textDocument/definition"` method: >lua vim.lsp.handlers["textDocument/definition"] = my_custom_default_definition < -- The {handlers} parameter for |vim.lsp.start_client()|. - This will set the |lsp-handler| as the default handler for this server. +- The {handlers} parameter of |vim.lsp.start()|. This sets the default + |lsp-handler| for the server being started. Example: >lua - For example: >lua - - vim.lsp.start_client { + vim.lsp.start { ..., -- Other configuration omitted. handlers = { ["textDocument/definition"] = my_custom_server_definition }, } -- The {handler} parameter for |vim.lsp.buf_request()|. - This will set the |lsp-handler| ONLY for the current request. +- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets + the |lsp-handler| ONLY for the given request(s). Example: >lua - For example: >lua - - vim.lsp.buf_request( + vim.lsp.buf_request_all( 0, "textDocument/definition", - definition_params, - my_request_custom_definition + my_request_params, + my_handler ) < In summary, the |lsp-handler| will be chosen based on the current |lsp-method| in the following order: -1. Handler passed to |vim.lsp.buf_request()|, if any. -2. Handler defined in |vim.lsp.start_client()|, if any. +1. Handler passed to |vim.lsp.buf_request_all()|, if any. +2. Handler defined in |vim.lsp.start()|, if any. 3. Handler defined in |vim.lsp.handlers|, if any. *vim.lsp.log_levels* @@ -411,12 +359,12 @@ name: >lua < *lsp-response* -For the format of the response message, see: - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage +LSP response shape: +https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage *lsp-notification* -For the format of the notification message, see: - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage +LSP notification shape: +https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage *lsp-on-list-handler* @@ -459,6 +407,8 @@ LspReferenceText used for highlighting "text" references LspReferenceRead used for highlighting "read" references *hl-LspReferenceWrite* LspReferenceWrite used for highlighting "write" references + *hl-LspInlayHint* +LspInlayHint used for highlighting inlay hints *lsp-highlight-codelens* @@ -482,13 +432,78 @@ LspSignatureActiveParameter Used to highlight the active parameter in the signature help. See |vim.lsp.handlers.signature_help()|. +------------------------------------------------------------------------------ +LSP SEMANTIC HIGHLIGHTS *lsp-semantic-highlight* + +When available, the LSP client highlights code using |lsp-semantic_tokens|, +which are another way that LSP servers can provide information about source +code. Note that this is in addition to treesitter syntax highlighting; +semantic highlighting does not replace syntax highlighting. + +The server will typically provide one token per identifier in the source code. +The token will have a `type` such as "function" or "variable", and 0 or more +`modifier`s such as "readonly" or "deprecated." The standard types and +modifiers are described here: +https://microsoft.github.io/language-server-protocol/specification/#textDocument_semanticTokens +LSP servers may also use off-spec types and modifiers. + +The LSP client adds one or more highlights for each token. The highlight +groups are derived from the token's type and modifiers: + • `@lsp.type.<type>.<ft>` for the type + • `@lsp.mod.<mod>.<ft>` for each modifier + • `@lsp.typemod.<type>.<mod>.<ft>` for each modifier +Use |:Inspect| to view the highlights for a specific token. Use |:hi| or +|nvim_set_hl()| to change the appearance of semantic highlights: >vim + + hi @lsp.type.function guifg=Yellow " function names are yellow + hi @lsp.type.variable.lua guifg=Green " variables in lua are green + hi @lsp.mod.deprecated gui=strikethrough " deprecated is crossed out + hi @lsp.typemod.function.async guifg=Blue " async functions are blue +< +The value |vim.highlight.priorities|`.semantic_tokens` is the priority of the +`@lsp.type.*` highlights. The `@lsp.mod.*` and `@lsp.typemod.*` highlights +have priorities one and two higher, respectively. + +You can disable semantic highlights by clearing the highlight groups: >lua + + -- Hide semantic highlights for functions + vim.api.nvim_set_hl(0, '@lsp.type.function', {}) + + -- Hide all semantic highlights + for _, group in ipairs(vim.fn.getcompletion("@lsp", "highlight")) do + vim.api.nvim_set_hl(0, group, {}) + end +< +You probably want these inside a |ColorScheme| autocommand. + +Use |LspTokenUpdate| and |vim.lsp.semantic_tokens.highlight_token()| for more +complex highlighting. + +The following groups are linked by default to standard |group-name|s: +> + @lsp.type.class Structure + @lsp.type.decorator Function + @lsp.type.enum Structure + @lsp.type.enumMember Constant + @lsp.type.function Function + @lsp.type.interface Structure + @lsp.type.macro Macro + @lsp.type.method Function + @lsp.type.namespace Structure + @lsp.type.parameter Identifier + @lsp.type.property Identifier + @lsp.type.struct Structure + @lsp.type.type Type + @lsp.type.typeParameter TypeDef + @lsp.type.variable Identifier +< ============================================================================== EVENTS *lsp-events* - *LspAttach* -After an LSP client attaches to a buffer. The |autocmd-pattern| is the -name of the buffer. When used from Lua, the client ID is passed to the -callback in the "data" table. Example: >lua +LspAttach *LspAttach* + After an LSP client attaches to a buffer. The |autocmd-pattern| is the + name of the buffer. When used from Lua, the client ID is passed to the + callback in the "data" table. Example: >lua vim.api.nvim_create_autocmd("LspAttach", { callback = function(args) @@ -503,10 +518,11 @@ callback in the "data" table. Example: >lua end, }) < - *LspDetach* -Just before an LSP client detaches from a buffer. The |autocmd-pattern| is the -name of the buffer. When used from Lua, the client ID is passed to the -callback in the "data" table. Example: >lua + +LspDetach *LspDetach* + Just before an LSP client detaches from a buffer. The |autocmd-pattern| + is the name of the buffer. When used from Lua, the client ID is passed + to the callback in the "data" table. Example: >lua vim.api.nvim_create_autocmd("LspDetach", { callback = function(args) @@ -516,20 +532,105 @@ callback in the "data" table. Example: >lua end, }) < -Also the following |User| |autocommand|s are provided: -LspProgressUpdate *LspProgressUpdate* - Upon receipt of a progress notification from the server. See - |vim.lsp.util.get_progress_messages()|. +LspNotify *LspNotify* + This event is triggered after each successful notification sent to an + LSP server. + + When used from Lua, the client_id, LSP method, and parameters are sent + in the "data" table. Example: >lua + + vim.api.nvim_create_autocmd('LspNotify', { + callback = function(args) + local bufnr = args.buf + local client_id = args.data.client_id + local method = args.data.method + local params = args.data.params + + -- do something with the notification + if method == 'textDocument/...' then + update_buffer(bufnr) + end + end, + }) +< + +LspProgress *LspProgress* + Upon receipt of a progress notification from the server. Notifications can + be polled from a `progress` ring buffer of a |vim.lsp.client| or use + |vim.lsp.status()| to get an aggregate message + + If the server sends a "work done progress", the `pattern` is set to `kind` + (one of `begin`, `report` or `end`). + + When used from Lua, the event contains a `data` table with `client_id` and + `result` properties. `result` will contain the request params sent by the + server. + + Example: >vim + autocmd LspProgress * redrawstatus +< LspRequest *LspRequest* - After a change to the active set of pending LSP requests. See {requests} - in |vim.lsp.client|. + For each request sent to an LSP server, this event is triggered for + every change to the request's status. The status can be one of + `pending`, `complete`, or `cancel` and is sent as the {type} on the + "data" table passed to the callback function. + + It triggers when the initial request is sent ({type} == `pending`) and + when the LSP server responds ({type} == `complete`). If a cancellation + is requested using `client.cancel_request(request_id)`, then this event + will trigger with {type} == `cancel`. + + When used from Lua, the client ID, request ID, and request are sent in + the "data" table. See {requests} in |vim.lsp.client| for details on the + {request} value. If the request type is `complete`, the request will be + deleted from the client's pending requests table immediately after + calling the event's callbacks. Example: >lua + + vim.api.nvim_create_autocmd('LspRequest', { + callback = function(args) + local bufnr = args.buf + local client_id = args.data.client_id + local request_id = args.data.request_id + local request = args.data.request + if request.type == 'pending' then + -- do something with pending requests + track_pending(client_id, bufnr, request_id, request) + elseif request.type == 'cancel' then + -- do something with pending cancel requests + track_canceling(client_id, bufnr, request_id, request) + elseif request.type == 'complete' then + -- do something with finished requests. this pending + -- request entry is about to be removed since it is complete + track_finish(client_id, bufnr, request_id, request) + end + end, + }) +< + +LspTokenUpdate *LspTokenUpdate* + When a visible semantic token is sent or updated by the LSP server, or + when an existing token becomes visible for the first time. The + |autocmd-pattern| is the name of the buffer. When used from Lua, the + token and client ID are passed to the callback in the "data" table. The + token fields are documented in |vim.lsp.semantic_tokens.get_at_pos()|. + Example: + >lua -Example: >vim - autocmd User LspProgressUpdate redrawstatus - autocmd User LspRequest redrawstatus + vim.api.nvim_create_autocmd('LspTokenUpdate', { + callback = function(args) + local token = args.data.token + if token.type == 'variable' and not token.modifiers.readonly then + vim.lsp.semantic_tokens.highlight_token( + token, args.buf, args.data.client_id, 'MyMutableVariableHighlight' + ) + end + end, + }) < + Note: doing anything other than calling + |vim.lsp.semantic_tokens.highlight_token()| is considered experimental. ============================================================================== Lua module: vim.lsp *lsp-core* @@ -541,8 +642,12 @@ buf_attach_client({bufnr}, {client_id}) *vim.lsp.buf_attach_client()* Without calling this, the server won't be notified of changes to a buffer. Parameters: ~ - • {bufnr} (number) Buffer handle, or 0 for current - • {client_id} (number) Client id + • {bufnr} (integer) Buffer handle, or 0 for current + • {client_id} (integer) Client id + + Return: ~ + (boolean) success `true` if client was attached successfully; `false` + otherwise buf_detach_client({bufnr}, {client_id}) *vim.lsp.buf_detach_client()* Detaches client from the specified buffer. Note: While the server is @@ -550,66 +655,65 @@ buf_detach_client({bufnr}, {client_id}) *vim.lsp.buf_detach_client()* send notifications should it ignore this notification. Parameters: ~ - • {bufnr} (number) Buffer handle, or 0 for current - • {client_id} (number) Client id + • {bufnr} (integer) Buffer handle, or 0 for current + • {client_id} (integer) Client id buf_is_attached({bufnr}, {client_id}) *vim.lsp.buf_is_attached()* Checks if a buffer is attached for a particular client. Parameters: ~ - • {bufnr} (number) Buffer handle, or 0 for current - • {client_id} (number) the client id + • {bufnr} (integer) Buffer handle, or 0 for current + • {client_id} (integer) the client id buf_notify({bufnr}, {method}, {params}) *vim.lsp.buf_notify()* Send a notification to a server Parameters: ~ - • {bufnr} (number|nil) The number of the buffer + • {bufnr} (integer|nil) The number of the buffer • {method} (string) Name of the request method • {params} (any) Arguments to send to the server Return: ~ - true if any client returns true; false otherwise + (boolean) success true if any client returns true; false otherwise *vim.lsp.buf_request_all()* -buf_request_all({bufnr}, {method}, {params}, {callback}) - Sends an async request for all active clients attached to the buffer. - Executes the callback on the combined result. Parameters are the same as - |vim.lsp.buf_request()| but the return result and callback are different. +buf_request_all({bufnr}, {method}, {params}, {handler}) + Sends an async request for all active clients attached to the buffer and + executes the `handler` callback with the combined result. Parameters: ~ - • {bufnr} (number) Buffer handle, or 0 for current. - • {method} (string) LSP method name - • {params} (table|nil) Parameters to send to the server - • {callback} (function) The callback to call when all requests are - finished. + • {bufnr} (integer) Buffer handle, or 0 for current. + • {method} (string) LSP method name + • {params} (table|nil) Parameters to send to the server + • {handler} (function) Handler called after all requests are completed. + Server results are passed as a `client_id:result` map. Return: ~ - (function) A function that will cancel all requests which is the same - as the one returned from `buf_request`. + (function) cancel Function that cancels all requests. *vim.lsp.buf_request_sync()* buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) Sends a request to all server and waits for the response of all of them. Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the - result. Parameters are the same as |vim.lsp.buf_request()| but the return - result is different. Wait maximum of {timeout_ms} (default 1000) ms. + result. Parameters are the same as |vim.lsp.buf_request_all()| but the + result is different. Waits a maximum of {timeout_ms} (default 1000) ms. Parameters: ~ - • {bufnr} (number) Buffer handle, or 0 for current. + • {bufnr} (integer) Buffer handle, or 0 for current. • {method} (string) LSP method name • {params} (table|nil) Parameters to send to the server - • {timeout_ms} (number|nil) Maximum time in milliseconds to wait for a + • {timeout_ms} (integer|nil) Maximum time in milliseconds to wait for a result. Defaults to 1000 - Return: ~ - Map of client_id:request_result. On timeout, cancel or error, returns - `(nil, err)` where `err` is a string describing the failure reason. + Return (multiple): ~ + (table) result Map of client_id:request_result. + (string|nil) err On timeout, cancel, or error, `err` is a string + describing the failure reason, and `result` is nil. client() *vim.lsp.client* LSP client object. You can get an active client object via - |vim.lsp.get_client_by_id()| or |vim.lsp.get_active_clients()|. + |vim.lsp.get_client_by_id()| or |vim.lsp.get_clients()|. • Methods: • request(method, params, [handler], bufnr) Sends a request to the @@ -658,35 +762,42 @@ client() *vim.lsp.client* 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. + "cancel" for a cancel request. It will be "complete" ephemerally while + executing |LspRequest| autocmds when replies are received from the + server. • {config} (table): copy of the table that was passed by the user to |vim.lsp.start_client()|. • {server_capabilities} (table): Response from the server sent on `initialize` describing the server's capabilities. + • {progress} A ring buffer (|vim.ringbuf()|) containing progress + messages sent by the server. client_is_stopped({client_id}) *vim.lsp.client_is_stopped()* Checks whether a client is stopped. Parameters: ~ - • {client_id} (number) + • {client_id} (integer) Return: ~ - true if client is stopped, false otherwise. + (boolean) stopped true if client is stopped, false otherwise. - *vim.lsp.for_each_buffer_client()* -for_each_buffer_client({bufnr}, {fn}) - Invokes a function for each LSP client attached to a buffer. +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. - Parameters: ~ - • {bufnr} (number) Buffer number - • {fn} (function) Function to run on each client attached to buffer - {bufnr}. The function takes the client, client ID, and buffer - number as arguments. Example: >lua + 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. - vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr) - print(vim.inspect(client)) - end) -< + If a 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[] + + The second argument is the `ctx` of |lsp-handler| formatexpr({opts}) *vim.lsp.formatexpr()* Provides an interface between the built-in client and a `formatexpr` @@ -694,8 +805,8 @@ formatexpr({opts}) *vim.lsp.formatexpr()* Currently only supports a single client. This can be set via `setlocal formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in - `on_attach` via `vim.api.nvim_buf_set_option(bufnr, 'formatexpr', - 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})')`. + `on_attach` via `vim.bo[bufnr].formatexpr = + 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`. Parameters: ~ • {opts} (table) options for customizing the formatting expression @@ -703,62 +814,64 @@ formatexpr({opts}) *vim.lsp.formatexpr()* • timeout_ms (default 500ms). The timeout period for the formatting request. -get_active_clients({filter}) *vim.lsp.get_active_clients()* - Get active clients. - - Parameters: ~ - • {filter} (table|nil) A table with key-value pairs used to filter the - returned clients. The available keys are: - • id (number): Only return clients with the given id - • bufnr (number): Only return clients attached to this - buffer - • name (string): Only return clients with the given name - - Return: ~ - (table) List of |vim.lsp.client| objects - *vim.lsp.get_buffers_by_client_id()* get_buffers_by_client_id({client_id}) Returns list of buffers attached to client_id. Parameters: ~ - • {client_id} (number) client id + • {client_id} (integer) client id Return: ~ - (list) of buffer ids + integer[] buffers list of buffer ids get_client_by_id({client_id}) *vim.lsp.get_client_by_id()* Gets a client by id, or nil if the id is invalid. The returned client may not yet be fully initialized. Parameters: ~ - • {client_id} (number) client id + • {client_id} (integer) client id + + Return: ~ + (nil|lsp.Client) client rpc object + +get_clients({filter}) *vim.lsp.get_clients()* + Get active clients. + + Parameters: ~ + • {filter} (table|nil) A table with key-value pairs used to filter the + returned clients. The available keys are: + • id (number): Only return clients with the given id + • bufnr (number): Only return clients attached to this + buffer + • name (string): Only return clients with the given name + • method (string): Only return clients supporting the given + method Return: ~ - |vim.lsp.client| object, or nil + lsp.Client []: List of |vim.lsp.client| objects get_log_path() *vim.lsp.get_log_path()* Gets the path of the logfile used by the LSP client. Return: ~ - (String) Path to logfile. + (string) path to log file omnifunc({findstart}, {base}) *vim.lsp.omnifunc()* Implements 'omnifunc' compatible LSP completion. Paramete |