mirror of
https://github.com/neovim/neovim.git
synced 2024-12-20 11:15:14 -07:00
3973a5e405
This function is used only in the `workspace/configuration` handler, and does not warrant a public API because of its confusing return types. The only caller `vim.lsp.handlers["workspace.configuration"]` is also refactored to use `vim.tbl_get()` instead.
2227 lines
95 KiB
Plaintext
2227 lines
95 KiB
Plaintext
*lsp.txt* LSP
|
|
|
|
|
|
NVIM REFERENCE MANUAL
|
|
|
|
|
|
LSP client/framework *lsp* *LSP*
|
|
|
|
Nvim supports the Language Server Protocol (LSP), which means it acts as
|
|
a client to LSP servers and includes a Lua framework `vim.lsp` for building
|
|
enhanced LSP tools.
|
|
|
|
https://microsoft.github.io/language-server-protocol/
|
|
|
|
LSP facilitates features like go-to-definition, find-references, hover,
|
|
completion, rename, format, refactor, etc., using semantic whole-project
|
|
analysis (unlike |ctags|).
|
|
|
|
Type |gO| to see the table of contents.
|
|
|
|
==============================================================================
|
|
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. You can find language servers here:
|
|
https://microsoft.github.io/language-server-protocol/implementors/servers/
|
|
|
|
2. Configure the LSP client per language server. See |vim.lsp.start()| or use
|
|
this minimal example as a guide: >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]),
|
|
})
|
|
<
|
|
3. Check that the server attached to the buffer: >
|
|
:lua =vim.lsp.get_clients()
|
|
|
|
4. Configure keymaps and autocmds to use LSP features. See |lsp-config|.
|
|
|
|
*lsp-config*
|
|
*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()|, 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 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 common functions are:
|
|
|
|
- |vim.lsp.buf.hover()|
|
|
- |vim.lsp.buf.format()|
|
|
- |vim.lsp.buf.references()|
|
|
- |vim.lsp.buf.implementation()|
|
|
- |vim.lsp.buf.code_action()|
|
|
|
|
|
|
Not all language servers provide the same capabilities. To ensure you only set
|
|
keymaps if the language server supports a feature, you can guard the keymap
|
|
calls behind capability checks:
|
|
>lua
|
|
vim.api.nvim_create_autocmd('LspAttach', {
|
|
callback = function(args)
|
|
local client = vim.lsp.get_client_by_id(args.data.client_id)
|
|
if client.server_capabilities.hoverProvider then
|
|
vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
|
|
end
|
|
end,
|
|
})
|
|
<
|
|
|
|
To learn what capabilities are available you can run the following command in
|
|
a buffer with a started LSP client: >vim
|
|
|
|
:lua =vim.lsp.get_clients()[1].server_capabilities
|
|
|
|
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_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": `: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
|
|
|
|
" 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
|
|
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.
|
|
|
|
Treesitter is a language parsing library that provides excellent tools
|
|
for incrementally parsing text and handling errors. This makes it a great
|
|
fit for editors to understand the contents of the current file for things
|
|
like syntax highlighting, simple goto-definitions, scope analysis and
|
|
more.
|
|
|
|
LSP and Treesitter are both great tools for editing and inspecting code.
|
|
|
|
================================================================================
|
|
LSP API *lsp-api*
|
|
|
|
LSP core API is described at |lsp-core|. Those are the core functions for
|
|
creating and managing clients.
|
|
|
|
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|).
|
|
*lsp-method*
|
|
|
|
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
|
|
|
|
:lua vim.print(vim.tbl_keys(vim.lsp.handlers))
|
|
<
|
|
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
|
|
|
|
*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|)
|
|
|
|
Each response handler has this signature: >
|
|
|
|
function(err, result, ctx, config)
|
|
<
|
|
Parameters: ~
|
|
- {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: ~
|
|
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*
|
|
|
|
To configure the behavior of a builtin |lsp-handler|, the convenient method
|
|
|vim.lsp.with()| is provided for users.
|
|
|
|
To configure the behavior of |vim.lsp.diagnostic.on_publish_diagnostics()|,
|
|
consider the following example, where a new |lsp-handler| is created using
|
|
|vim.lsp.with()| that no longer generates signs for the diagnostics: >lua
|
|
|
|
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
|
|
vim.lsp.diagnostic.on_publish_diagnostics, {
|
|
-- Disable signs
|
|
signs = false,
|
|
}
|
|
)
|
|
<
|
|
To enable signs, use |vim.lsp.with()| again to create and assign a new
|
|
|lsp-handler| to |vim.lsp.handlers| for the associated method: >lua
|
|
|
|
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
|
|
vim.lsp.diagnostic.on_publish_diagnostics, {
|
|
-- Enable signs
|
|
signs = true,
|
|
}
|
|
)
|
|
<
|
|
To configure a handler on a per-server basis, you can use the {handlers} key
|
|
for |vim.lsp.start_client()| >lua
|
|
|
|
vim.lsp.start_client {
|
|
..., -- Other configuration omitted.
|
|
handlers = {
|
|
["textDocument/publishDiagnostics"] = vim.lsp.with(
|
|
vim.lsp.diagnostic.on_publish_diagnostics, {
|
|
-- Disable virtual_text
|
|
virtual_text = false,
|
|
}
|
|
),
|
|
},
|
|
}
|
|
<
|
|
or if using "nvim-lspconfig", you can use the {handlers} key of `setup()`:
|
|
>lua
|
|
|
|
require('lspconfig').rust_analyzer.setup {
|
|
handlers = {
|
|
["textDocument/publishDiagnostics"] = vim.lsp.with(
|
|
vim.lsp.diagnostic.on_publish_diagnostics, {
|
|
-- Disable virtual_text
|
|
virtual_text = false
|
|
}
|
|
),
|
|
}
|
|
}
|
|
<
|
|
Some handlers do not have an explicitly named handler function (such as
|
|
||vim.lsp.diagnostic.on_publish_diagnostics()|). To override these, first
|
|
create a reference to the existing handler: >lua
|
|
|
|
local on_references = vim.lsp.handlers["textDocument/references"]
|
|
vim.lsp.handlers["textDocument/references"] = vim.lsp.with(
|
|
on_references, {
|
|
-- Use location list instead of quickfix list
|
|
loclist = true,
|
|
}
|
|
)
|
|
<
|
|
*lsp-handler-resolution*
|
|
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["textDocument/definition"] = my_custom_default_definition
|
|
<
|
|
- The {handlers} parameter of |vim.lsp.start()|. This sets the default
|
|
|lsp-handler| for the server being started. Example: >lua
|
|
|
|
vim.lsp.start {
|
|
..., -- Other configuration omitted.
|
|
handlers = {
|
|
["textDocument/definition"] = my_custom_server_definition
|
|
},
|
|
}
|
|
|
|
- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets
|
|
the |lsp-handler| ONLY for the given request(s). Example: >lua
|
|
|
|
vim.lsp.buf_request_all(
|
|
0,
|
|
"textDocument/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_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*
|
|
Log levels are defined in |vim.log.levels|
|
|
|
|
|
|
VIM.LSP.PROTOCOL *vim.lsp.protocol*
|
|
|
|
Module `vim.lsp.protocol` defines constants dictated by the LSP specification,
|
|
and helper functions for creating protocol-related objects.
|
|
https://github.com/microsoft/language-server-protocol/raw/gh-pages/_specifications/specification-3-14.md
|
|
|
|
For example `vim.lsp.protocol.ErrorCodes` allows reverse lookup by number or
|
|
name: >lua
|
|
|
|
vim.lsp.protocol.TextDocumentSyncKind.Full == 1
|
|
vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"
|
|
<
|
|
|
|
*lsp-response*
|
|
LSP response shape:
|
|
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage
|
|
|
|
*lsp-notification*
|
|
LSP notification shape:
|
|
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage
|
|
|
|
*lsp-on-list-handler*
|
|
|
|
`on_list` receives a table with:
|
|
|
|
- `items` table[], structured like |setqflist-what|
|
|
- `title` string, title for the list.
|
|
- `context` table|nil. `ctx` from |lsp-handler|
|
|
|
|
This table can be used with vim.fn.setqflist or vim.fn.setloclist. E.g.:
|
|
>lua
|
|
local function on_list(options)
|
|
vim.fn.setqflist({}, ' ', options)
|
|
vim.api.nvim_command('cfirst')
|
|
end
|
|
|
|
vim.lsp.buf.definition{on_list=on_list}
|
|
vim.lsp.buf.references(nil, {on_list=on_list})
|
|
<
|
|
If you prefer loclist do something like this:
|
|
>lua
|
|
local function on_list(options)
|
|
vim.fn.setloclist(0, {}, ' ', options)
|
|
vim.api.nvim_command('lopen')
|
|
end
|
|
<
|
|
================================================================================
|
|
LSP HIGHLIGHT *lsp-highlight*
|
|
|
|
Reference Highlights:
|
|
|
|
Highlight groups that are meant to be used by |vim.lsp.buf.document_highlight()|.
|
|
|
|
You can see more about the differences in types here:
|
|
https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight
|
|
|
|
*hl-LspReferenceText*
|
|
LspReferenceText used for highlighting "text" references
|
|
*hl-LspReferenceRead*
|
|
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*
|
|
|
|
Highlight groups related to |lsp-codelens| functionality.
|
|
|
|
*hl-LspCodeLens*
|
|
LspCodeLens
|
|
Used to color the virtual text of the codelens. See
|
|
|nvim_buf_set_extmark()|.
|
|
|
|
LspCodeLensSeparator *hl-LspCodeLensSeparator*
|
|
Used to color the separator between two or more code lenses.
|
|
|
|
*lsp-highlight-signature*
|
|
|
|
Highlight groups related to |vim.lsp.handlers.signature_help()|.
|
|
|
|
*hl-LspSignatureActiveParameter*
|
|
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 *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)
|
|
local bufnr = args.buf
|
|
local client = vim.lsp.get_client_by_id(args.data.client_id)
|
|
if client.server_capabilities.completionProvider then
|
|
vim.bo[bufnr].omnifunc = "v:lua.vim.lsp.omnifunc"
|
|
end
|
|
if client.server_capabilities.definitionProvider then
|
|
vim.bo[bufnr].tagfunc = "v:lua.vim.lsp.tagfunc"
|
|
end
|
|
end,
|
|
})
|
|
<
|
|
|
|
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)
|
|
local client = vim.lsp.get_client_by_id(args.data.client_id)
|
|
-- Do something with the client
|
|
vim.cmd("setlocal tagfunc< omnifunc<")
|
|
end,
|
|
})
|
|
<
|
|
|
|
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*
|
|
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
|
|
|
|
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*
|
|
|
|
buf_attach_client({bufnr}, {client_id}) *vim.lsp.buf_attach_client()*
|
|
Implements the `textDocument/did…` notifications required to track a
|
|
buffer for any language server.
|
|
|
|
Without calling this, the server won't be notified of changes to a buffer.
|
|
|
|
Parameters: ~
|
|
• {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
|
|
notified that the text document (buffer) was closed, it is still able to
|
|
send notifications should it ignore this notification.
|
|
|
|
Parameters: ~
|
|
• {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} (`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} (`integer?`) The number of the buffer
|
|
• {method} (`string`) Name of the request method
|
|
• {params} (`any`) Arguments to send to the server
|
|
|
|
Return: ~
|
|
(`boolean`) success true if any client returns true; false otherwise
|
|
|
|
*vim.lsp.buf_request_all()*
|
|
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} (`integer`) Buffer handle, or 0 for current.
|
|
• {method} (`string`) LSP method name
|
|
• {params} (`table?`) 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`) 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_all()| but the
|
|
result is different. Waits a maximum of {timeout_ms} (default 1000) ms.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer`) Buffer handle, or 0 for current.
|
|
• {method} (`string`) LSP method name
|
|
• {params} (`table?`) Parameters to send to the server
|
|
• {timeout_ms} (`integer?`) Maximum time in milliseconds to wait for a
|
|
result. Defaults to 1000
|
|
|
|
Return (multiple): ~
|
|
(`table`) result Map of client_id:request_result.
|
|
(`string?`) 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_clients()|.
|
|
|
|
• Methods:
|
|
• request(method, params, [handler], bufnr) Sends a request to the
|
|
server. This is a thin wrapper around {client.rpc.request} with some
|
|
additional checking. If {handler} is not specified, If one is not
|
|
found there, then an error will occur. Returns: {status},
|
|
{[client_id]}. {status} is a boolean indicating if the notification
|
|
was successful. If it is `false`, then it will always be `false` (the
|
|
client has shutdown). If {status} is `true`, the function returns
|
|
{request_id} as the second result. You can use this with
|
|
`client.cancel_request(request_id)` to cancel the request.
|
|
• request_sync(method, params, timeout_ms, bufnr) Sends a request to the
|
|
server and synchronously waits for the response. This is a wrapper
|
|
around {client.request} Returns: { err=err, result=result }, a
|
|
dictionary, where `err` and `result` come from the |lsp-handler|. On
|
|
timeout, cancel or error, returns `(nil, err)` where `err` is a string
|
|
describing the failure reason. If the request was unsuccessful returns
|
|
`nil`.
|
|
• notify(method, params) Sends a notification to an LSP server. Returns:
|
|
a boolean to indicate if the notification was successful. If it is
|
|
false, then it will always be false (the client has shutdown).
|
|
• cancel_request(id) Cancels a request with a given request id. Returns:
|
|
same as `notify()`.
|
|
• stop([force]) Stops a client, optionally with force. By default, it
|
|
will just ask the server to shutdown without force. If you request to
|
|
stop a client which has previously been requested to shutdown, it will
|
|
automatically escalate and force shutdown.
|
|
• is_stopped() Checks whether a client is stopped. Returns: true if the
|
|
client is fully stopped.
|
|
• on_attach(client, bufnr) Runs the on_attach function from the client's
|
|
config if it was defined. Useful for buffer-local setup.
|
|
• supports_method(method, [opts]): boolean Checks if a client supports a
|
|
given method. Always returns true for unknown off-spec methods. [opts]
|
|
is a optional `{bufnr?: integer}` table. Some language server
|
|
capabilities can be file specific.
|
|
|
|
• Members
|
|
• {id} (number): 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} (table): RPC client object, for low level interaction with the
|
|
client. See |vim.lsp.rpc.start()|.
|
|
• {offset_encoding} (string): 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): The handlers used by the client as described in
|
|
|lsp-handler|.
|
|
• {requests} (table): 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} (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} (`integer`)
|
|
|
|
Return: ~
|
|
(`boolean`) stopped true if client is stopped, false otherwise.
|
|
|
|
commands *vim.lsp.commands*
|
|
Registry for client side commands. This is an extension point for plugins
|
|
to handle custom commands which are not part of the core language server
|
|
protocol specification.
|
|
|
|
The registry is a table where the key is a unique command name, and the
|
|
value is a function which is called if any LSP action (code action, code
|
|
lenses, ...) triggers the command.
|
|
|
|
If 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`
|
|
function.
|
|
|
|
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.bo[bufnr].formatexpr =
|
|
'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`.
|
|
|
|
Parameters: ~
|
|
• {opts} (`table`) options for customizing the formatting expression
|
|
which takes the following optional keys:
|
|
• timeout_ms (default 500ms). The timeout period for the
|
|
formatting request.
|
|
|
|
*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} (`integer`) client id
|
|
|
|
Return: ~
|
|
(`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} (`integer`) client id
|
|
|
|
Return: ~
|
|
(`lsp.Client?`) client rpc object
|
|
|
|
get_clients({filter}) *vim.lsp.get_clients()*
|
|
Get active clients.
|
|
|
|
Parameters: ~
|
|
• {filter} (`table?`) 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: ~
|
|
(`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 log file
|
|
|
|
omnifunc({findstart}, {base}) *vim.lsp.omnifunc()*
|
|
Implements 'omnifunc' compatible LSP completion.
|
|
|
|
Parameters: ~
|
|
• {findstart} (`integer`) 0 or 1, decides behavior
|
|
• {base} (`integer`) findstart=0, text to match against
|
|
|
|
Return: ~
|
|
(`integer|table`) Decided by {findstart}:
|
|
• findstart=0: column where the completion starts, or -2 or -3
|
|
• findstart=1: list of matches (actually just calls |complete()|)
|
|
|
|
See also: ~
|
|
• |complete-functions|
|
|
• |complete-items|
|
|
• |CompleteDone|
|
|
|
|
set_log_level({level}) *vim.lsp.set_log_level()*
|
|
Sets the global log level for LSP logging.
|
|
|
|
Levels by name: "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "OFF"
|
|
|
|
Level numbers begin with "TRACE" at 0
|
|
|
|
Use `lsp.log_levels` for reverse lookup.
|
|
|
|
Parameters: ~
|
|
• {level} (`integer|string`) the case insensitive level name or number
|
|
|
|
See also: ~
|
|
• |vim.lsp.log_levels|
|
|
|
|
start({config}, {opts}) *vim.lsp.start()*
|
|
Create a new LSP client and start a language server or reuses an already
|
|
running client if one is found matching `name` and `root_dir`. Attaches
|
|
the current buffer to the client.
|
|
|
|
Example: >lua
|
|
vim.lsp.start({
|
|
name = 'my-server-name',
|
|
cmd = {'name-of-language-server-executable'},
|
|
root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]),
|
|
})
|
|
<
|
|
|
|
See |vim.lsp.start_client()| for all available options. The most important
|
|
are:
|
|
|
|
• `name` arbitrary name for the LSP client. Should be unique per language
|
|
server.
|
|
• `cmd` command (in list form) used to start the language server. Must be
|
|
absolute, or found on `$PATH`. Shell constructs like `~` are not
|
|
expanded.
|
|
• `root_dir` path to the project root. By default this is used to decide
|
|
if an existing client should be re-used. The example above uses
|
|
|vim.fs.find()| and |vim.fs.dirname()| to detect the root by traversing
|
|
the file system upwards starting from the current directory until either
|
|
a `pyproject.toml` or `setup.py` file is found.
|
|
• `workspace_folders` list of `{ uri:string, name: string }` tables
|
|
specifying the project root folders used by the language server. If
|
|
`nil` the property is derived from `root_dir` for convenience.
|
|
|
|
Language servers use this information to discover metadata like the
|
|
dependencies of your project and they tend to index the contents within
|
|
the project folder.
|
|
|
|
To ensure a language server is only started for languages it can handle,
|
|
make sure to call |vim.lsp.start()| within a |FileType| autocmd. Either
|
|
use |:au|, |nvim_create_autocmd()| or put the call in a
|
|
`ftplugin/<filetype_name>.lua` (See |ftplugin-name|)
|
|
|
|
Parameters: ~
|
|
• {config} (`table`) Same configuration as documented in
|
|
|vim.lsp.start_client()|
|
|
• {opts} (`lsp.StartOpts?`) Optional keyword arguments:
|
|
• reuse_client (fun(client: client, config: table): boolean)
|
|
Predicate used to decide if a client should be re-used.
|
|
Used on all running clients. The default implementation
|
|
re-uses a client if name and root_dir matches.
|
|
• bufnr (number) Buffer handle to attach to if starting or
|
|
re-using a client (0 for current).
|
|
|
|
Return: ~
|
|
(`integer?`) client_id
|
|
|
|
start_client({config}) *vim.lsp.start_client()*
|
|
Starts and initializes a client with the given configuration.
|
|
|
|
Field `cmd` in {config} is required.
|
|
|
|
Parameters: ~
|
|
• {config} (`lsp.ClientConfig`) Configuration for the server:
|
|
• cmd: (string[]|fun(dispatchers: table):table) command a
|
|
list of strings 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`.
|
|
• cmd_env: (table) Environment flags to pass to the LSP on
|
|
spawn. Must be specified using a table. Non-string values
|
|
are coerced to string. Example: >
|
|
|
|
{ PORT = 8080; HOST = "0.0.0.0"; }
|
|
<
|
|
• detached: (boolean, default true) 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 behind orphaned
|
|
server processes.
|
|
• workspace_folders: (table) 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.
|
|
• capabilities: 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: Map of language server method names to
|
|
|lsp-handler|
|
|
• settings: Map with language server specific settings.
|
|
These are returned to the language server if requested via
|
|
`workspace/configuration`. Keys are case-sensitive.
|
|
• 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.
|
|
• init_options 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: function(bufnr, filetype) -> language ID
|
|
as string. Defaults to the filetype.
|
|
• 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.
|
|
• on_error: Callback with parameters (code, ...), 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: Callback with parameters (initialize_params,
|
|
config) 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.
|
|
• 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. Nvim
|
|
does not make this assumption. A
|
|
`workspace/didChangeConfiguration` notification should be
|
|
sent to the server during on_init.
|
|
• on_exit Callback (code, signal, client_id) 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: Callback (client, bufnr) invoked when client
|
|
attaches to a buffer.
|
|
• trace: ("off" | "messages" | "verbose" | nil) passed
|
|
directly to the language server in the initialize request.
|
|
Invalid/empty values will default to "off"
|
|
• 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.
|
|
|
|
• root_dir: (string) Directory where the LSP server will
|
|
base its workspaceFolders, rootUri, and rootPath on
|
|
initialization.
|
|
|
|
Return: ~
|
|
(`integer?`) client_id. |vim.lsp.get_client_by_id()| Note: client may
|
|
not be fully initialized. Use `on_init` to do any actions once the
|
|
client has been initialized.
|
|
|
|
status() *vim.lsp.status()*
|
|
Consumes the latest progress messages from all clients and formats them as
|
|
a string. Empty if there are no clients or if no new messages
|
|
|
|
Return: ~
|
|
(`string`)
|
|
|
|
stop_client({client_id}, {force}) *vim.lsp.stop_client()*
|
|
Stops a client(s).
|
|
|
|
You can also use the `stop()` function on a |vim.lsp.client| object. To
|
|
stop all clients: >lua
|
|
vim.lsp.stop_client(vim.lsp.get_clients())
|
|
<
|
|
|
|
By default asks the server to shutdown, unless stop was requested already
|
|
for this client, then force-shutdown is attempted.
|
|
|
|
Parameters: ~
|
|
• {client_id} (`integer|table`) id or |vim.lsp.client| object, or list
|
|
thereof
|
|
• {force} (`boolean?`) shutdown forcefully
|
|
|
|
tagfunc({pattern}, {flags}) *vim.lsp.tagfunc()*
|
|
Provides an interface between the built-in client and 'tagfunc'.
|
|
|
|
When used with normal mode commands (e.g. |CTRL-]|) this will invoke the
|
|
"textDocument/definition" LSP method to find the tag under the cursor.
|
|
Otherwise, uses "workspace/symbol". If no results are returned from any
|
|
LSP servers, falls back to using built-in tags.
|
|
|
|
Parameters: ~
|
|
• {pattern} (`string`) Pattern used to find a workspace symbol
|
|
• {flags} (`string`) See |tag-function|
|
|
|
|
Return: ~
|
|
(`table[]`) tags A list of matching tags
|
|
|
|
with({handler}, {override_config}) *vim.lsp.with()*
|
|
Function to manage overriding defaults for LSP handlers.
|
|
|
|
Parameters: ~
|
|
• {handler} (`lsp.Handler`) See |lsp-handler|
|
|
• {override_config} (`table`) Table containing the keys to override
|
|
behavior of the {handler}
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.lsp.buf *lsp-buf*
|
|
|
|
*vim.lsp.buf.add_workspace_folder()*
|
|
add_workspace_folder({workspace_folder})
|
|
Add the folder at path to the workspace folders. If {path} is not
|
|
provided, the user will be prompted for a path using |input()|.
|
|
|
|
clear_references() *vim.lsp.buf.clear_references()*
|
|
Removes document highlights from current buffer.
|
|
|
|
code_action({options}) *vim.lsp.buf.code_action()*
|
|
Selects a code action available at the current cursor position.
|
|
|
|
Parameters: ~
|
|
• {options} (`table?`) Optional table which holds the following
|
|
optional fields:
|
|
• context: (table|nil) Corresponds to `CodeActionContext` of
|
|
the LSP specification:
|
|
• diagnostics (table|nil): LSP `Diagnostic[]`. Inferred
|
|
from the current position if not provided.
|
|
• only (table|nil): List of LSP `CodeActionKind`s used to
|
|
filter the code actions. Most language servers support
|
|
values like `refactor` or `quickfix`.
|
|
• triggerKind (number|nil): The reason why code actions
|
|
were requested.
|
|
|
|
• filter: (function|nil) Predicate taking an `CodeAction`
|
|
and returning a boolean.
|
|
• apply: (boolean|nil) When set to `true`, and there is
|
|
just one remaining action (after filtering), the action
|
|
is applied without user query.
|
|
• range: (table|nil) Range for which code actions should be
|
|
requested. If in visual mode this defaults to the active
|
|
selection. Table must contain `start` and `end` keys with
|
|
{row,col} tuples using mark-like indexing. See
|
|
|api-indexing|
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
|
|
• vim.lsp.protocol.CodeActionTriggerKind
|
|
|
|
completion({context}) *vim.lsp.buf.completion()*
|
|
Retrieves the completion items at the current cursor position. Can only be
|
|
called in Insert mode.
|
|
|
|
Parameters: ~
|
|
• {context} (`table`) (context support not yet implemented) Additional
|
|
information about the context in which a completion was
|
|
triggered (how it was triggered, and by which trigger
|
|
character, if applicable)
|
|
|
|
See also: ~
|
|
• vim.lsp.protocol.CompletionTriggerKind
|
|
|
|
declaration({options}) *vim.lsp.buf.declaration()*
|
|
Jumps to the declaration of the symbol under the cursor.
|
|
|
|
Note: ~
|
|
• Many servers do not implement this method. Generally, see
|
|
|vim.lsp.buf.definition()| instead.
|
|
|
|
Parameters: ~
|
|
• {options} (`table?`) additional options
|
|
• reuse_win: (boolean) Jump to existing window if buffer is
|
|
already open.
|
|
• on_list: (function) |lsp-on-list-handler| replacing the
|
|
default handler. Called for any non-empty result.
|
|
|
|
definition({options}) *vim.lsp.buf.definition()*
|
|
Jumps to the definition of the symbol under the cursor.
|
|
|
|
Parameters: ~
|
|
• {options} (`table?`) additional options
|
|
• reuse_win: (boolean) Jump to existing window if buffer is
|
|
already open.
|
|
• on_list: (function) |lsp-on-list-handler| replacing the
|
|
default handler. Called for any non-empty result.
|
|
|
|
document_highlight() *vim.lsp.buf.document_highlight()*
|
|
Send request to the server to resolve document highlights for the current
|
|
text document position. This request can be triggered by a key mapping or
|
|
by events such as `CursorHold`, e.g.: >vim
|
|
autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight()
|
|
autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()
|
|
autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()
|
|
<
|
|
|
|
Note: Usage of |vim.lsp.buf.document_highlight()| requires the following
|
|
highlight groups to be defined or you won't be able to see the actual
|
|
highlights. |hl-LspReferenceText| |hl-LspReferenceRead|
|
|
|hl-LspReferenceWrite|
|
|
|
|
document_symbol({options}) *vim.lsp.buf.document_symbol()*
|
|
Lists all symbols in the current buffer in the quickfix window.
|
|
|
|
Parameters: ~
|
|
• {options} (`table?`) additional options
|
|
• on_list: (function) handler for list results. See
|
|
|lsp-on-list-handler|
|
|
|
|
execute_command({command_params}) *vim.lsp.buf.execute_command()*
|
|
Executes an LSP server command.
|
|
|
|
Parameters: ~
|
|
• {command_params} (`table`) A valid `ExecuteCommandParams` object
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
|
|
|
|
format({options}) *vim.lsp.buf.format()*
|
|
Formats a buffer using the attached (and optionally filtered) language
|
|
server clients.
|
|
|
|
Parameters: ~
|
|
• {options} (`table?`) Optional table which holds the following
|
|
optional fields:
|
|
• formatting_options (table|nil): Can be used to specify
|
|
FormattingOptions. Some unspecified options will be
|
|
automatically derived from the current Nvim options. See https://microsoft.github.io/language-server-protocol/specification/#formattingOptions
|
|
• timeout_ms (integer|nil, default 1000): Time in
|
|
milliseconds to block for formatting requests. No effect
|
|
if async=true
|
|
• bufnr (number|nil): Restrict formatting to the clients
|
|
attached to the given buffer, defaults to the current
|
|
buffer (0).
|
|
• filter (function|nil): Predicate used to filter clients.
|
|
Receives a client as argument and must return a boolean.
|
|
Clients matching the predicate are included. Example: >lua
|
|
|
|
-- Never request typescript-language-server for formatting
|
|
vim.lsp.buf.format {
|
|
filter = function(client) return client.name ~= "tsserver" end
|
|
}
|
|
<
|
|
• async boolean|nil If true the method won't block.
|
|
Defaults to false. Editing the buffer while formatting
|
|
asynchronous can lead to unexpected changes.
|
|
• id (number|nil): Restrict formatting to the client with
|
|
ID (client.id) matching this field.
|
|
• name (string|nil): Restrict formatting to the client with
|
|
name (client.name) matching this field.
|
|
• range (table|nil) Range to format. Table must contain
|
|
`start` and `end` keys with {row,col} tuples using (1,0)
|
|
indexing. Defaults to current selection in visual mode
|
|
Defaults to `nil` in other modes, formatting the full
|
|
buffer
|
|
|
|
hover() *vim.lsp.buf.hover()*
|
|
Displays hover information about the symbol under the cursor in a floating
|
|
window. Calling the function twice will jump into the floating window.
|
|
|
|
implementation({options}) *vim.lsp.buf.implementation()*
|
|
Lists all the implementations for the symbol under the cursor in the
|
|
quickfix window.
|
|
|
|
Parameters: ~
|
|
• {options} (`table?`) additional options
|
|
• on_list: (function) |lsp-on-list-handler| replacing the
|
|
default handler. Called for any non-empty result.
|
|
|
|
incoming_calls() *vim.lsp.buf.incoming_calls()*
|
|
Lists all the call sites of the symbol under the cursor in the |quickfix|
|
|
window. If the symbol can resolve to multiple items, the user can pick one
|
|
in the |inputlist()|.
|
|
|
|
list_workspace_folders() *vim.lsp.buf.list_workspace_folders()*
|
|
List workspace folders.
|
|
|
|
outgoing_calls() *vim.lsp.buf.outgoing_calls()*
|
|
Lists all the items that are called by the symbol under the cursor in the
|
|
|quickfix| window. If the symbol can resolve to multiple items, the user
|
|
can pick one in the |inputlist()|.
|
|
|
|
references({context}, {options}) *vim.lsp.buf.references()*
|
|
Lists all the references to the symbol under the cursor in the quickfix
|
|
window.
|
|
|
|
Parameters: ~
|
|
• {context} (`table?`) Context for the request
|
|
• {options} (`table?`) additional options
|
|
• on_list: (function) handler for list results. See
|
|
|lsp-on-list-handler|
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
|
|
|
|
*vim.lsp.buf.remove_workspace_folder()*
|
|
remove_workspace_folder({workspace_folder})
|
|
Remove the folder at path from the workspace folders. If {path} is not
|
|
provided, the user will be prompted for a path using |input()|.
|
|
|
|
rename({new_name}, {options}) *vim.lsp.buf.rename()*
|
|
Renames all references to the symbol under the cursor.
|
|
|
|
Parameters: ~
|
|
• {new_name} (`string?`) If not provided, the user will be prompted for
|
|
a new name using |vim.ui.input()|.
|
|
• {options} (`table?`) additional options
|
|
• filter (function|nil): Predicate used to filter clients.
|
|
Receives a client as argument and must return a boolean.
|
|
Clients matching the predicate are included.
|
|
• name (string|nil): Restrict clients used for rename to
|
|
ones where client.name matches this field.
|
|
|
|
signature_help() *vim.lsp.buf.signature_help()*
|
|
Displays signature information about the symbol under the cursor in a
|
|
floating window.
|
|
|
|
type_definition({options}) *vim.lsp.buf.type_definition()*
|
|
Jumps to the definition of the type of the symbol under the cursor.
|
|
|
|
Parameters: ~
|
|
• {options} (`table?`) additional options
|
|
• reuse_win: (boolean) Jump to existing window if buffer is
|
|
already open.
|
|
• on_list: (function) |lsp-on-list-handler| replacing the
|
|
default handler. Called for any non-empty result.
|
|
|
|
workspace_symbol({query}, {options}) *vim.lsp.buf.workspace_symbol()*
|
|
Lists all symbols in the current workspace in the quickfix window.
|
|
|
|
The list is filtered against {query}; if the argument is omitted from the
|
|
call, the user is prompted to enter a string on the command line. An empty
|
|
string means no filtering is done.
|
|
|
|
Parameters: ~
|
|
• {query} (`string?`) optional
|
|
• {options} (`table?`) additional options
|
|
• on_list: (function) handler for list results. See
|
|
|lsp-on-list-handler|
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.lsp.diagnostic *lsp-diagnostic*
|
|
|
|
*vim.lsp.diagnostic.get_namespace()*
|
|
get_namespace({client_id}, {is_pull})
|
|
Get the diagnostic namespace associated with an LSP client
|
|
|vim.diagnostic| for diagnostics
|
|
|
|
Parameters: ~
|
|
• {client_id} (`integer`) The id of the LSP client
|
|
• {is_pull} (`boolean?`) Whether the namespace is for a pull or push
|
|
client. Defaults to push
|
|
|
|
*vim.lsp.diagnostic.on_diagnostic()*
|
|
on_diagnostic({_}, {result}, {ctx}, {config})
|
|
|lsp-handler| for the method "textDocument/diagnostic"
|
|
|
|
See |vim.diagnostic.config()| for configuration options. Handler-specific
|
|
configuration can be set using |vim.lsp.with()|: >lua
|
|
vim.lsp.handlers["textDocument/diagnostic"] = vim.lsp.with(
|
|
vim.lsp.diagnostic.on_diagnostic, {
|
|
-- Enable underline, use default values
|
|
underline = true,
|
|
-- Enable virtual text, override spacing to 4
|
|
virtual_text = {
|
|
spacing = 4,
|
|
},
|
|
-- Use a function to dynamically turn signs off
|
|
-- and on, using buffer local variables
|
|
signs = function(namespace, bufnr)
|
|
return vim.b[bufnr].show_signs == true
|
|
end,
|
|
-- Disable a feature
|
|
update_in_insert = false,
|
|
}
|
|
)
|
|
<
|
|
|
|
Parameters: ~
|
|
• {ctx} (`lsp.HandlerContext`)
|
|
• {config} (`table`) Configuration table (see
|
|
|vim.diagnostic.config()|).
|
|
|
|
*vim.lsp.diagnostic.on_publish_diagnostics()*
|
|
on_publish_diagnostics({_}, {result}, {ctx}, {config})
|
|
|lsp-handler| for the method "textDocument/publishDiagnostics"
|
|
|
|
See |vim.diagnostic.config()| for configuration options. Handler-specific
|
|
configuration can be set using |vim.lsp.with()|: >lua
|
|
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
|
|
vim.lsp.diagnostic.on_publish_diagnostics, {
|
|
-- Enable underline, use default values
|
|
underline = true,
|
|
-- Enable virtual text, override spacing to 4
|
|
virtual_text = {
|
|
spacing = 4,
|
|
},
|
|
-- Use a function to dynamically turn signs off
|
|
-- and on, using buffer local variables
|
|
signs = function(namespace, bufnr)
|
|
return vim.b[bufnr].show_signs == true
|
|
end,
|
|
-- Disable a feature
|
|
update_in_insert = false,
|
|
}
|
|
)
|
|
<
|
|
|
|
Parameters: ~
|
|
• {ctx} (`lsp.HandlerContext`)
|
|
• {config} (`table`) Configuration table (see
|
|
|vim.diagnostic.config()|).
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.lsp.codelens *lsp-codelens*
|
|
|
|
clear({client_id}, {bufnr}) *vim.lsp.codelens.clear()*
|
|
Clear the lenses
|
|
|
|
Parameters: ~
|
|
• {client_id} (`integer?`) filter by client_id. All clients if nil
|
|
• {bufnr} (`integer?`) filter by buffer. All buffers if nil
|
|
|
|
display({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.display()*
|
|
Display the lenses using virtual text
|
|
|
|
Parameters: ~
|
|
• {lenses} (`lsp.CodeLens[]?`) lenses to display
|
|
• {bufnr} (`integer`)
|
|
• {client_id} (`integer`)
|
|
|
|
get({bufnr}) *vim.lsp.codelens.get()*
|
|
Return all lenses for the given buffer
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer`) Buffer number. 0 can be used for the current
|
|
buffer.
|
|
|
|
Return: ~
|
|
(`lsp.CodeLens[]`)
|
|
|
|
*vim.lsp.codelens.on_codelens()*
|
|
on_codelens({err}, {result}, {ctx}, {_})
|
|
|lsp-handler| for the method `textDocument/codeLens`
|
|
|
|
Parameters: ~
|
|
• {ctx} (`lsp.HandlerContext`)
|
|
|
|
refresh() *vim.lsp.codelens.refresh()*
|
|
Refresh the codelens for the current buffer
|
|
|
|
It is recommended to trigger this using an autocmd or via keymap.
|
|
|
|
Example: >vim
|
|
autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()
|
|
<
|
|
|
|
run() *vim.lsp.codelens.run()*
|
|
Run the code lens in the current line
|
|
|
|
save({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.save()*
|
|
Store lenses for a specific buffer and client
|
|
|
|
Parameters: ~
|
|
• {lenses} (`lsp.CodeLens[]?`) lenses to store
|
|
• {bufnr} (`integer`)
|
|
• {client_id} (`integer`)
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.lsp.inlay_hint *lsp-inlay_hint*
|
|
|
|
enable({bufnr}, {enable}) *vim.lsp.inlay_hint.enable()*
|
|
Enable/disable/toggle inlay hints for a buffer
|
|
|
|
Note: ~
|
|
This API is pre-release (unstable).
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) Buffer handle, or 0 or nil for current
|
|
• {enable} (`boolean?`) true/nil to enable, false to disable
|
|
|
|
get({filter}) *vim.lsp.inlay_hint.get()*
|
|
Get the list of inlay hints, (optionally) restricted by buffer or range.
|
|
|
|
Example usage: >lua
|
|
local hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer
|
|
|
|
local client = vim.lsp.get_client_by_id(hint.client_id)
|
|
resolved_hint = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0).result
|
|
vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding)
|
|
|
|
location = resolved_hint.label[1].location
|
|
client.request('textDocument/hover', {
|
|
textDocument = { uri = location.uri },
|
|
position = location.range.start,
|
|
})
|
|
<
|
|
|
|
Note: ~
|
|
This API is pre-release (unstable).
|
|
|
|
Parameters: ~
|
|
• {filter} (`vim.lsp.inlay_hint.get.filter?`) Optional filters
|
|
|kwargs|:
|
|
• bufnr (integer?): 0 for current buffer
|
|
• range (lsp.Range?)
|
|
|
|
Return: ~
|
|
(`vim.lsp.inlay_hint.get.ret[]`) Each list item is a table with the
|
|
following fields:
|
|
• bufnr (integer)
|
|
• client_id (integer)
|
|
• inlay_hint (lsp.InlayHint)
|
|
|
|
is_enabled({bufnr}) *vim.lsp.inlay_hint.is_enabled()*
|
|
Note: ~
|
|
This API is pre-release (unstable).
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) Buffer handle, or 0 or nil for current
|
|
|
|
Return: ~
|
|
(`boolean`)
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.lsp.semantic_tokens *lsp-semantic_tokens*
|
|
|
|
force_refresh({bufnr}) *vim.lsp.semantic_tokens.force_refresh()*
|
|
Force a refresh of all semantic tokens
|
|
|
|
Only has an effect if the buffer is currently active for semantic token
|
|
highlighting (|vim.lsp.semantic_tokens.start()| has been called for it)
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) filter by buffer. All buffers if nil, current
|
|
buffer if 0
|
|
|
|
*vim.lsp.semantic_tokens.get_at_pos()*
|
|
get_at_pos({bufnr}, {row}, {col})
|
|
Return the semantic token(s) at the given position. If called without
|
|
arguments, returns the token under the cursor.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) Buffer number (0 for current buffer, default)
|
|
• {row} (`integer?`) Position row (default cursor position)
|
|
• {col} (`integer?`) Position column (default cursor position)
|
|
|
|
Return: ~
|
|
(`table?`) List of tokens at position. Each token has the following
|
|
fields:
|
|
• line (integer) line number, 0-based
|
|
• start_col (integer) start column, 0-based
|
|
• end_col (integer) end column, 0-based
|
|
• type (string) token type as string, e.g. "variable"
|
|
• modifiers (table) token modifiers as a set. E.g., { static = true,
|
|
readonly = true }
|
|
• client_id (integer)
|
|
|
|
*vim.lsp.semantic_tokens.highlight_token()*
|
|
highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts})
|
|
Highlight a semantic token.
|
|
|
|
Apply an extmark with a given highlight group for a semantic token. The
|
|
mark will be deleted by the semantic token engine when appropriate; for
|
|
example, when the LSP sends updated tokens. This function is intended for
|
|
use inside |LspTokenUpdate| callbacks.
|
|
|
|
Parameters: ~
|
|
• {token} (`table`) a semantic token, found as `args.data.token` in
|
|
|LspTokenUpdate|.
|
|
• {bufnr} (`integer`) the buffer to highlight
|
|
• {client_id} (`integer`) The ID of the |vim.lsp.client|
|
|
• {hl_group} (`string`) Highlight group name
|
|
• {opts} (`table?`) Optional parameters.
|
|
• priority: (integer|nil) Priority for the applied
|
|
extmark. Defaults to
|
|
`vim.highlight.priorities.semantic_tokens + 3`
|
|
|
|
start({bufnr}, {client_id}, {opts}) *vim.lsp.semantic_tokens.start()*
|
|
Start the semantic token highlighting engine for the given buffer with the
|
|
given client. The client must already be attached to the buffer.
|
|
|
|
NOTE: This is currently called automatically by
|
|
|vim.lsp.buf_attach_client()|. To opt-out of semantic highlighting with a
|
|
server that supports it, you can delete the semanticTokensProvider table
|
|
from the {server_capabilities} of your client in your |LspAttach| callback
|
|
or your configuration's `on_attach` callback: >lua
|
|
client.server_capabilities.semanticTokensProvider = nil
|
|
<
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer`)
|
|
• {client_id} (`integer`)
|
|
• {opts} (`table?`) Optional keyword arguments
|
|
• debounce (integer, default: 200): Debounce token
|
|
requests to the server by the given number in
|
|
milliseconds
|
|
|
|
stop({bufnr}, {client_id}) *vim.lsp.semantic_tokens.stop()*
|
|
Stop the semantic token highlighting engine for the given buffer with the
|
|
given client.
|
|
|
|
NOTE: This is automatically called by a |LspDetach| autocmd that is set up
|
|
as part of `start()`, so you should only need this function to manually
|
|
disengage the semantic token engine without fully detaching the LSP client
|
|
from the buffer.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer`)
|
|
• {client_id} (`integer`)
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.lsp.handlers *lsp-handlers*
|
|
|
|
hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()*
|
|
|lsp-handler| for the method "textDocument/hover" >lua
|
|
vim.lsp.handlers["textDocument/hover"] = vim.lsp.with(
|
|
vim.lsp.handlers.hover, {
|
|
-- Use a sharp border with `FloatBorder` highlights
|
|
border = "single",
|
|
-- add the title in hover float window
|
|
title = "hover"
|
|
}
|
|
)
|
|
<
|
|
|
|
Parameters: ~
|
|
• {ctx} (`lsp.HandlerContext`)
|
|
• {config} (`table`) Configuration table.
|
|
• border: (default=nil)
|
|
• Add borders to the floating window
|
|
• See |vim.lsp.util.open_floating_preview()| for more
|
|
options.
|
|
|
|
*vim.lsp.handlers.signature_help()*
|
|
signature_help({_}, {result}, {ctx}, {config})
|
|
|lsp-handler| for the method "textDocument/signatureHelp".
|
|
|
|
The active parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua
|
|
vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
|
|
vim.lsp.handlers.signature_help, {
|
|
-- Use a sharp border with `FloatBorder` highlights
|
|
border = "single"
|
|
}
|
|
)
|
|
<
|
|
|
|
Parameters: ~
|
|
• {result} (`table`) Response from the language server
|
|
• {ctx} (`lsp.HandlerContext`) Client context
|
|
• {config} (`table`) Configuration table.
|
|
• border: (default=nil)
|
|
• Add borders to the floating window
|
|
• See |vim.lsp.util.open_floating_preview()| for more
|
|
options
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.lsp.util *lsp-util*
|
|
|
|
*vim.lsp.util.apply_text_document_edit()*
|
|
apply_text_document_edit({text_document_edit}, {index}, {offset_encoding})
|
|
Applies a `TextDocumentEdit`, which is a list of changes to a single
|
|
document.
|
|
|
|
Parameters: ~
|
|
• {text_document_edit} (`table`) a `TextDocumentEdit` object
|
|
• {index} (`integer`) Optional index of the edit, if from
|
|
a list of edits (or nil, if not from a list)
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit
|
|
|
|
*vim.lsp.util.apply_text_edits()*
|
|
apply_text_edits({text_edits}, {bufnr}, {offset_encoding})
|
|
Applies a list of text edits to a buffer.
|
|
|
|
Parameters: ~
|
|
• {text_edits} (`table`) list of `TextEdit` objects
|
|
• {bufnr} (`integer`) Buffer id
|
|
• {offset_encoding} (`string`) utf-8|utf-16|utf-32
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit
|
|
|
|
*vim.lsp.util.apply_workspace_edit()*
|
|
apply_workspace_edit({workspace_edit}, {offset_encoding})
|
|
Applies a `WorkspaceEdit`.
|
|
|
|
Parameters: ~
|
|
• {workspace_edit} (`table`) `WorkspaceEdit`
|
|
• {offset_encoding} (`string`) utf-8|utf-16|utf-32 (required)
|
|
|
|
buf_clear_references({bufnr}) *vim.lsp.util.buf_clear_references()*
|
|
Removes document highlights from a buffer.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) Buffer id
|
|
|
|
*vim.lsp.util.buf_highlight_references()*
|
|
buf_highlight_references({bufnr}, {references}, {offset_encoding})
|
|
Shows a list of document highlights for a certain buffer.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer`) Buffer id
|
|
• {references} (`table`) List of `DocumentHighlight` objects to
|
|
highlight
|
|
• {offset_encoding} (`string`) One of "utf-8", "utf-16", "utf-32".
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specification/#textDocumentContentChangeEvent
|
|
|
|
*vim.lsp.util.character_offset()*
|
|
character_offset({buf}, {row}, {col}, {offset_encoding})
|
|
Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer.
|
|
|
|
Parameters: ~
|
|
• {buf} (`integer`) buffer number (0 for current)
|
|
• {row} (`integer`) 0-indexed line
|
|
• {col} (`integer`) 0-indexed byte offset in line
|
|
• {offset_encoding} (`string`) utf-8|utf-16|utf-32 defaults to
|
|
`offset_encoding` of first client of `buf`
|
|
|
|
Return: ~
|
|
(`integer`) `offset_encoding` index of the character in line {row}
|
|
column {col} in buffer {buf}
|
|
|
|
*vim.lsp.util.convert_input_to_markdown_lines()*
|
|
convert_input_to_markdown_lines({input}, {contents})
|
|
Converts any of `MarkedString` | `MarkedString[]` | `MarkupContent` into a
|
|
list of lines containing valid markdown. Useful to populate the hover
|
|
window for `textDocument/hover`, for parsing the result of
|
|
`textDocument/signatureHelp`, and potentially others.
|
|
|
|
Note that if the input is of type `MarkupContent` and its kind is
|
|
`plaintext`, then the corresponding value is returned without further
|
|
modifications.
|
|
|
|
Parameters: ~
|
|
• {input} (`lsp.MarkedString|lsp.MarkedString[]|lsp.MarkupContent`)
|
|
• {contents} (`table?`) List of strings to extend with converted lines.
|
|
Defaults to {}.
|
|
|
|
Return: ~
|
|
(`string[]`) extended with lines of converted markdown.
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
|
|
|
|
*vim.lsp.util.convert_signature_help_to_markdown_lines()*
|
|
convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers})
|
|
Converts `textDocument/signatureHelp` response to markdown lines.
|
|
|
|
Parameters: ~
|
|
• {signature_help} (`table`) Response of `textDocument/SignatureHelp`
|
|
• {ft} (`string?`) filetype that will be use as the `lang`
|
|
for the label markdown code block
|
|
• {triggers} (`table?`) list of trigger characters from the lsp
|
|
server. used to better determine parameter offsets
|
|
|
|
Return (multiple): ~
|
|
(`table?`) table list of lines of converted markdown.
|
|
(`table?`) table of active hl
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
|
|
|
|
get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()*
|
|
Returns indentation size.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) Buffer handle, defaults to current
|
|
|
|
Return: ~
|
|
(`integer`) indentation size
|
|
|
|
See also: ~
|
|
• 'shiftwidth'
|
|
|
|
*vim.lsp.util.jump_to_location()*
|
|
jump_to_location({location}, {offset_encoding}, {reuse_win})
|
|
Jumps to a location.
|
|
|
|
Parameters: ~
|
|
• {location} (`table`) (`Location`|`LocationLink`)
|
|
• {offset_encoding} (`string?`) utf-8|utf-16|utf-32
|
|
• {reuse_win} (`boolean?`) Jump to existing window if buffer is
|
|
already open.
|
|
|
|
Return: ~
|
|
(`boolean`) `true` if the jump succeeded
|
|
|
|
*vim.lsp.util.locations_to_items()*
|
|
locations_to_items({locations}, {offset_encoding})
|
|
Returns the items with the byte position calculated correctly and in
|
|
sorted order, for display in quickfix and location lists.
|
|
|
|
The `user_data` field of each resulting item will contain the original
|
|
`Location` or `LocationLink` it was computed from.
|
|
|
|
The result can be passed to the {list} argument of |setqflist()| or
|
|
|setloclist()|.
|
|
|
|
Parameters: ~
|
|
• {locations} (`lsp.Location[]|lsp.LocationLink[]`)
|
|
• {offset_encoding} (`string`) offset_encoding for locations
|
|
utf-8|utf-16|utf-32 default to first client of
|
|
buffer
|
|
|
|
Return: ~
|
|
(`vim.lsp.util.LocationItem[]`) list of items
|
|
|
|
*vim.lsp.util.make_floating_popup_options()*
|
|
make_floating_popup_options({width}, {height}, {opts})
|
|
Creates a table with sensible default options for a floating window. The
|
|
table can be passed to |nvim_open_win()|.
|
|
|
|
Parameters: ~
|
|
• {width} (`integer`) window width (in character cells)
|
|
• {height} (`integer`) window height (in character cells)
|
|
• {opts} (`table`) optional
|
|
• offset_x (integer) offset to add to `col`
|
|
• offset_y (integer) offset to add to `row`
|
|
• border (string or table) override `border`
|
|
• focusable (string or table) override `focusable`
|
|
• zindex (string or table) override `zindex`, defaults to 50
|
|
• relative ("mouse"|"cursor") defaults to "cursor"
|
|
• anchor_bias ("auto"|"above"|"below") defaults to "auto"
|
|
• "auto": place window based on which side of the cursor
|
|
has more lines
|
|
• "above": place the window above the cursor unless there
|
|
are not enough lines to display the full window height.
|
|
• "below": place the window below the cursor unless there
|
|
are not enough lines to display the full window height.
|
|
|
|
Return: ~
|
|
(`table`) Options
|
|
|
|
*vim.lsp.util.make_formatting_params()*
|
|
make_formatting_params({options})
|
|
Creates a `DocumentFormattingParams` object for the current buffer and
|
|
cursor position.
|
|
|
|
Parameters: ~
|
|
• {options} (`table?`) with valid `FormattingOptions` entries
|
|
|
|
Return: ~
|
|
(`lsp.DocumentFormattingParams`) object
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
|
|
|
|
*vim.lsp.util.make_given_range_params()*
|
|
make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding})
|
|
Using the given range in the current buffer, creates an object that is
|
|
similar to |vim.lsp.util.make_range_params()|.
|
|
|
|
Parameters: ~
|
|
• {start_pos} (`integer[]?`) {row,col} mark-indexed position.
|
|
Defaults to the start of the last visual selection.
|
|
• {end_pos} (`integer[]?`) {row,col} mark-indexed position.
|
|
Defaults to the end of the last visual selection.
|
|
• {bufnr} (`integer?`) buffer handle or 0 for current,
|
|
defaults to current
|
|
• {offset_encoding} (`"utf-8"|"utf-16"|"utf-32"?`) defaults to
|
|
`offset_encoding` of first client of `bufnr`
|
|
|
|
Return: ~
|
|
(`table`) { textDocument = { uri = `current_file_uri` }, range = {
|
|
start = `start_position`, end = `end_position` } }
|
|
|
|
*vim.lsp.util.make_position_params()*
|
|
make_position_params({window}, {offset_encoding})
|
|
Creates a `TextDocumentPositionParams` object for the current buffer and
|
|
cursor position.
|
|
|
|
Parameters: ~
|
|
• {window} (`integer?`) window handle or 0 for current,
|
|
defaults to current
|
|
• {offset_encoding} (`string?`) utf-8|utf-16|utf-32|nil defaults to
|
|
`offset_encoding` of first client of buffer of
|
|
`window`
|
|
|
|
Return: ~
|
|
(`table`) `TextDocumentPositionParams` object
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
|
|
|
|
*vim.lsp.util.make_range_params()*
|
|
make_range_params({window}, {offset_encoding})
|
|
Using the current position in the current buffer, creates an object that
|
|
can be used as a building block for several LSP requests, such as
|
|
`textDocument/codeAction`, `textDocument/colorPresentation`,
|
|
`textDocument/rangeFormatting`.
|
|
|
|
Parameters: ~
|
|
• {window} (`integer?`) window handle or 0 for current,
|
|
defaults to current
|
|
• {offset_encoding} (`"utf-8"|"utf-16"|"utf-32"?`) defaults to
|
|
`offset_encoding` of first client of buffer of
|
|
`window`
|
|
|
|
Return: ~
|
|
(`table`) { textDocument = { uri = `current_file_uri` }, range = {
|
|
start = `current_position`, end = `current_position` } }
|
|
|
|
*vim.lsp.util.make_text_document_params()*
|
|
make_text_document_params({bufnr})
|
|
Creates a `TextDocumentIdentifier` object for the current buffer.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (`integer?`) Buffer handle, defaults to current
|
|
|
|
Return: ~
|
|
(`table`) `TextDocumentIdentifier`
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
|
|
|
|
*vim.lsp.util.make_workspace_params()*
|
|
make_workspace_params({added}, {removed})
|
|
Create the workspace params
|
|
|
|
Parameters: ~
|
|
• {added} (`table`)
|
|
• {removed} (`table`)
|
|
|
|
*vim.lsp.util.open_floating_preview()*
|
|
open_floating_preview({contents}, {syntax}, {opts})
|
|
Shows contents in a floating window.
|
|
|
|
Parameters: ~
|
|
• {contents} (`table`) of lines to show in window
|
|
• {syntax} (`string`) of syntax to set for opened buffer
|
|
• {opts} (`table`) with optional fields (additional keys are
|
|
filtered with |vim.lsp.util.make_floating_popup_options()|
|
|
before they are passed on to |nvim_open_win()|)
|
|
• height: (integer) height of floating window
|
|
• width: (integer) width of floating window
|
|
• wrap: (boolean, default true) wrap long lines
|
|
• wrap_at: (integer) character to wrap at for computing
|
|
height when wrap is enabled
|
|
• max_width: (integer) maximal width of floating window
|
|
• max_height: (integer) maximal height of floating window
|
|
• focus_id: (string) if a popup with this id is opened,
|
|
then focus it
|
|
• close_events: (table) list of events that closes the
|
|
floating window
|
|
• focusable: (boolean, default true) Make float focusable
|
|
• focus: (boolean, default true) If `true`, and if
|
|
{focusable} is also `true`, focus an existing floating
|
|
window with the same {focus_id}
|
|
|
|
Return (multiple): ~
|
|
(`integer`) bufnr of newly created float window
|
|
(`integer`) winid of newly created float window preview window
|
|
|
|
preview_location({location}, {opts}) *vim.lsp.util.preview_location()*
|
|
Previews a location in a floating window
|
|
|
|
behavior depends on type of location:
|
|
• for Location, range is shown (e.g., function definition)
|
|
• for LocationLink, targetRange is shown (e.g., body of function
|
|
definition)
|
|
|
|
Parameters: ~
|
|
• {location} (`table`) a single `Location` or `LocationLink`
|
|
|
|
Return (multiple): ~
|
|
(`integer?`) buffer id of float window
|
|
(`integer?`) window id of float window
|
|
|
|
rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()*
|
|
Rename old_fname to new_fname
|
|
|
|
Parameters: ~
|
|
• {opts} (`table`)
|
|
|
|
*vim.lsp.util.show_document()*
|
|
show_document({location}, {offset_encoding}, {opts})
|
|
Shows document and optionally jumps to the location.
|
|
|
|
Parameters: ~
|
|
• {location} (`table`) (`Location`|`LocationLink`)
|
|
• {offset_encoding} (`string?`) utf-8|utf-16|utf-32
|
|
• {opts} (`table?`) options
|
|
• reuse_win (boolean) Jump to existing window if
|
|
buffer is already open.
|
|
• focus (boolean) Whether to focus/jump to location
|
|
if possible. Defaults to true.
|
|
|
|
Return: ~
|
|
(`boolean`) `true` if succeeded
|
|
|
|
*vim.lsp.util.stylize_markdown()*
|
|
stylize_markdown({bufnr}, {contents}, {opts})
|
|
Converts markdown into syntax highlighted regions by stripping the code
|
|
blocks and converting them into highlighted code. This will by default
|
|
insert a blank line separator after those code block regions to improve
|
|
readability.
|
|
|
|
This method configures the given buffer and returns the lines to set.
|
|
|
|
If you want to open a popup with fancy markdown, use
|
|
`open_floating_preview` instead
|
|
|
|
Parameters: ~
|
|
• {contents} (`table`) of lines to show in window
|
|
• {opts} (`table`) with optional fields
|
|
• height of floating window
|
|
• width of floating window
|
|
• wrap_at character to wrap at for computing height
|
|
• max_width maximal width of floating window
|
|
• max_height maximal height of floating window
|
|
• separator insert separator after code block
|
|
|
|
Return: ~
|
|
(`table`) stripped content
|
|
|
|
symbols_to_items({symbols}, {bufnr}) *vim.lsp.util.symbols_to_items()*
|
|
Converts symbols to quickfix list items.
|
|
|
|
Parameters: ~
|
|
• {symbols} (`table`) DocumentSymbol[] or SymbolInformation[]
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.lsp.log *lsp-log*
|
|
|
|
get_filename() *vim.lsp.log.get_filename()*
|
|
Returns the log filename.
|
|
|
|
Return: ~
|
|
(`string`) log filename
|
|
|
|
get_level() *vim.lsp.log.get_level()*
|
|
Gets the current log level.
|
|
|
|
Return: ~
|
|
(`integer`) current log level
|
|
|
|
set_format_func({handle}) *vim.lsp.log.set_format_func()*
|
|
Sets formatting function used to format logs
|
|
|
|
Parameters: ~
|
|
• {handle} (`function`) function to apply to logging arguments, pass
|
|
vim.inspect for multi-line formatting
|
|
|
|
set_level({level}) *vim.lsp.log.set_level()*
|
|
Sets the current log level.
|
|
|
|
Parameters: ~
|
|
• {level} (`string|integer`) One of `vim.lsp.log.levels`
|
|
|
|
should_log({level}) *vim.lsp.log.should_log()*
|
|
Checks whether the level is sufficient for logging.
|
|
|
|
Parameters: ~
|
|
• {level} (`integer`) log level
|
|
|
|
Return: ~
|
|
(bool) true if would log, false if not
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.lsp.rpc *lsp-rpc*
|
|
|
|
connect({host}, {port}) *vim.lsp.rpc.connect()*
|
|
Create a LSP RPC client factory that connects via TCP to the given host
|
|
and port.
|
|
|
|
Return a function that can be passed to the `cmd` field for
|
|
|vim.lsp.start_client()| or |vim.lsp.start()|.
|
|
|
|
Parameters: ~
|
|
• {host} (`string`) host to connect to
|
|
• {port} (`integer`) port to connect to
|
|
|
|
Return: ~
|
|
(`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
|
|
|
|
*vim.lsp.rpc.domain_socket_connect()*
|
|
domain_socket_connect({pipe_path})
|
|
Create a LSP RPC client factory that connects via named pipes (Windows) or
|
|
unix domain sockets (Unix) to the given pipe_path (file path on Unix and
|
|
name on Windows).
|
|
|
|
Return a function that can be passed to the `cmd` field for
|
|
|vim.lsp.start_client()| or |vim.lsp.start()|.
|
|
|
|
Parameters: ~
|
|
• {pipe_path} (`string`) file path of the domain socket (Unix) or name
|
|
of the named pipe (Windows) to connect to
|
|
|
|
Return: ~
|
|
(`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
|
|
|
|
format_rpc_error({err}) *vim.lsp.rpc.format_rpc_error()*
|
|
Constructs an error message from an LSP error object.
|
|
|
|
Parameters: ~
|
|
• {err} (`table`) The error object
|
|
|
|
Return: ~
|
|
(`string`) error_message The formatted error message
|
|
|
|
notify({method}, {params}) *vim.lsp.rpc.notify()*
|
|
Sends a notification to the LSP server.
|
|
|
|
Parameters: ~
|
|
• {method} (`string`) The invoked LSP method
|
|
• {params} (`table?`) Parameters for the invoked LSP method
|
|
|
|
Return: ~
|
|
(`boolean`) `true` if notification could be sent, `false` if not
|
|
|
|
*vim.lsp.rpc.request()*
|
|
request({method}, {params}, {callback}, {notify_reply_callback})
|
|
Sends a request to the LSP server and runs {callback} upon response.
|
|
|
|
Parameters: ~
|
|
• {method} (`string`) The invoked LSP method
|
|
• {params} (`table?`) Parameters for the invoked LSP
|
|
method
|
|
• {callback} (`fun(err: lsp.ResponseError?, result: any)`)
|
|
Callback to invoke
|
|
• {notify_reply_callback} (`fun(message_id: integer)?`) Callback to
|
|
invoke as soon as a request is no longer
|
|
pending
|
|
|
|
Return (multiple): ~
|
|
(`boolean`) success `true` if request could be sent, `false` if not
|
|
(`integer?`) message_id if request could be sent, `nil` if not
|
|
|
|
*vim.lsp.rpc.rpc_response_error()*
|
|
rpc_response_error({code}, {message}, {data})
|
|
Creates an RPC response table `error` to be sent to the LSP response.
|
|
|
|
Parameters: ~
|
|
• {code} (`integer`) RPC error code defined, see
|
|
`vim.lsp.protocol.ErrorCodes`
|
|
• {message} (`string?`) arbitrary message to send to server
|
|
• {data} (`any?`) arbitrary data to send to server
|
|
|
|
Return: ~
|
|
(`lsp.ResponseError`)
|
|
|
|
See also: ~
|
|
• lsp.ErrorCodes See `vim.lsp.protocol.ErrorCodes`
|
|
|
|
*vim.lsp.rpc.start()*
|
|
start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
|
|
Starts an LSP server process and create an LSP RPC client object to
|
|
interact with it. Communication with the spawned process happens via
|
|
stdio. For communication via TCP, spawn a process manually and use
|
|
|vim.lsp.rpc.connect()|
|
|
|
|
Parameters: ~
|
|
• {cmd} (`string`) Command to start the LSP server.
|
|
• {cmd_args} (`string[]`) List of additional string arguments
|
|
to pass to {cmd}.
|
|
• {dispatchers} (`vim.lsp.rpc.Dispatchers?`) Dispatchers for LSP
|
|
message types. Valid dispatcher names are:
|
|
• `"notification"`
|
|
• `"server_request"`
|
|
• `"on_error"`
|
|
• `"on_exit"`
|
|
• {extra_spawn_params} (`vim.lsp.rpc.ExtraSpawnParams?`) Additional
|
|
context for the LSP server process. May contain:
|
|
• {cwd} (string) Working directory for the LSP
|
|
server process
|
|
• {detached?} (boolean) Detach the LSP server
|
|
process from the current process. Defaults to
|
|
false on Windows and true otherwise.
|
|
• {env?} (table) Additional environment
|
|
variables for LSP server process
|
|
|
|
Return: ~
|
|
(`vim.lsp.rpc.PublicClient?`) Client RPC object, with these methods:
|
|
• `notify()` |vim.lsp.rpc.notify()|
|
|
• `request()` |vim.lsp.rpc.request()|
|
|
• `is_closing()` returns a boolean indicating if the RPC is closing.
|
|
• `terminate()` terminates the RPC client.
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.lsp.protocol *lsp-protocol*
|
|
|
|
*vim.lsp.protocol.make_client_capabilities()*
|
|
make_client_capabilities()
|
|
Gets a new ClientCapabilities object describing the LSP client
|
|
capabilities.
|
|
|
|
Return: ~
|
|
(`lsp.ClientCapabilities`)
|
|
|
|
Methods *vim.lsp.protocol.Methods*
|
|
LSP method names.
|
|
|
|
See also: ~
|
|
• https://microsoft.github.io/language-server-protocol/specification/#metaModel
|
|
|
|
*vim.lsp.protocol.resolve_capabilities()*
|
|
resolve_capabilities({server_capabilities})
|
|
Creates a normalized object describing LSP server capabilities.
|
|
|
|
Parameters: ~
|
|
• {server_capabilities} (`table`) Table of capabilities supported by
|
|
the server
|
|
|
|
Return: ~
|
|
(`lsp.ServerCapabilities?`) Normalized table of capabilities
|
|
|
|
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
|