kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-29 14:41:06 -07:00
Code Issues Packages Projects Releases Wiki Activity
2c9fbe34b2
neovim/runtime/doc/lsp.txt
Mathias Fußenegger c1514d7e67
fix(lsp): fix some type annotations (#22397)
2023-02-25 18:47:05 +01:00

2041 lines
85 KiB
Plaintext
Raw Blame History

*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.
A list of language servers is available at:
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. Configure keymaps and autocmds to utilize 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|
- '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.
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
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:
- |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_active_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_active_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".
- 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|). 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-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*
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)
<
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? }`
You can use |vim.lsp.rpc.rpc_response_error()| to create this object.
For |lsp-notification|, each |lsp-handler| has this signature: >
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|
Returns: ~
The |lsp-handler|'s return value will be ignored.
*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 for |vim.lsp.start_client()|.
This will set the |lsp-handler| as the default handler for this server.
For example: >lua
vim.lsp.start_client {
..., -- 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.
For example: >lua
vim.lsp.buf_request(
0,
"textDocument/definition",
definition_params,
my_request_custom_definition
)
<
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.
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*
For the format of the response message, see:
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-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
*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()|.
==============================================================================
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
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*
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,
})
<
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()|.
LspRequest *LspRequest*
After a change to the active set of pending LSP requests. See {requests}
in |vim.lsp.client|.
Example: >vim
autocmd User LspProgressUpdate redrawstatus
autocmd User LspRequest redrawstatus
<
==============================================================================
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} (number) Buffer handle, or 0 for current
• {client_id} (number) Client id
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} (number) Buffer handle, or 0 for current
• {client_id} (number) 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
buf_notify({bufnr}, {method}, {params}) *vim.lsp.buf_notify()*
Send a notification to a server
Parameters: ~
• {bufnr} (number|nil) 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}, {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.
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. Unlike `buf_request`, this will collect all the
responses from each server instead of handling them. A map
of client_id:request_result will be provided to the
callback
Return: ~
fun() cancel A function that will cancel 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.
Parameters: ~
• {bufnr} (number) 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
result. Defaults to 1000
Return: ~
table<integer, any>|nil result, string|nil err Map of
client_id:request_result. On timeout, cancel or error, returns `(nil,
err)` where `err` is a string describing the failure reason.
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()|.
• 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.
• 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.
• {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.
client_is_stopped({client_id}) *vim.lsp.client_is_stopped()*
Checks whether a client is stopped.
Parameters: ~
• {client_id} (number)
Return: ~
(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.
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
vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr)
print(vim.inspect(client))
end)
<
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.api.nvim_buf_set_option(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.
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} (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} (number) client id
Return: ~
|vim.lsp.client| object, or nil
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} (number) 0 or 1, decides behavior
• {base} (number) findstart=0, text to match against
Return: ~
(number) 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} (number|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} nil|table 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: ~
(number|nil) 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} (table) Configuration for the server:
• cmd: (table|string|fun(dispatchers: table):table) command
string or list treated like |jobstart()|. The command must
launch the language server process. `cmd` can also be a
function that creates an RPC client. The function receives
a dispatchers table and must return a table with the
functions `request`, `notify`, `is_closing` and
`terminate` See |vim.lsp.rpc.request()| and
|vim.lsp.rpc.notify()| For TCP there is a built-in rpc
client factory: |vim.lsp.rpc.connect()|
• cmd_cwd: (string, default=|getcwd()|) Directory to launch
the `cmd` process. Not related to `root_dir`.
• cmd_env: (table) Environment flags to pass to the LSP on
spawn. Can be specified using keys like a map or as a list
with `k=v` pairs or both. Non-string values are coerced to string.
Example: >
{ "PRODUCTION=true"; "TEST=123"; 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.type_idx]=vim.types.dictionary}`, 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.
Neovim 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|nil) 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.
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_active_clients())
<
By default asks the server to shutdown, unless stop was requested already
for this client, then force-shutdown is attempted.
Parameters: ~
• {client_id} number|table id or |vim.lsp.client| object, or list
thereof
• {force} (boolean|nil) shutdown forcefully
tagfunc({...}) *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} (function) 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|nil) 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.constants.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} (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.constants.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|nil) additional options
• reuse_win: (boolean) Jump to existing window if buffer is
already open.
• on_list: (function) handler for list results. See
|lsp-on-list-handler|
definition({options}) *vim.lsp.buf.definition()*
Jumps to the definition of the symbol under the cursor.
Parameters: ~
• {options} (table|nil) additional options
• reuse_win: (boolean) Jump to existing window if buffer is
already open.
• on_list: (function) handler for list results. See
|lsp-on-list-handler|
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|nil) 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|nil 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 Neovim options.
See https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/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|nil) additional options
• on_list: (function) handler for list results. See
|lsp-on-list-handler|
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|nil) Context for the request
• {options} (table|nil) 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|nil) If not provided, the user will be prompted
for a new name using |vim.ui.input()|.
• {options} (table|nil) 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.
server_ready() *vim.lsp.buf.server_ready()*
Checks whether the language servers attached to the current buffer are
ready.
Return: ~
`true` if server responds.
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|nil) additional options
• reuse_win: (boolean) Jump to existing window if buffer is
already open.
• on_list: (function) handler for list results. See
|lsp-on-list-handler|
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|nil) additional options
• on_list: (function) handler for list results. See
|lsp-on-list-handler|
==============================================================================
Lua module: vim.lsp.diagnostic *lsp-diagnostic*
get_namespace({client_id}) *vim.lsp.diagnostic.get_namespace()*
Get the diagnostic namespace associated with an LSP client
|vim.diagnostic|.
Parameters: ~
• {client_id} (number) The id of the LSP client
*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: ~
• {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} (number|nil) filter by client_id. All clients if nil
• {bufnr} (number|nil) filter by buffer. All buffers if nil
display({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.display()*
Display the lenses using virtual text
Parameters: ~
• {lenses} (table) of lenses to display (`CodeLens[] | null`)
• {bufnr} (number)
• {client_id} (number)
get({bufnr}) *vim.lsp.codelens.get()*
Return all lenses for the given buffer
Parameters: ~
• {bufnr} (number) Buffer number. 0 can be used for the current buffer.
Return: ~
(table) (`CodeLens[]`)
*vim.lsp.codelens.on_codelens()*
on_codelens({err}, {result}, {ctx}, {_})
|lsp-handler| for the method `textDocument/codeLens`
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} (table) of lenses to store (`CodeLens[] | null`)
• {bufnr} (number)
• {client_id} (number)
==============================================================================
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} (nil|number) default: current buffer
*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} (number|nil) Buffer number (0 for current buffer, default)
• {row} (number|nil) Position row (default cursor position)
• {col} (number|nil) Position column (default cursor position)
Return: ~
(table|nil) List of tokens at position
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} (number)
• {client_id} (number)
• {opts} (nil|table) Optional keyword arguments
• debounce (number, 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} (number)
• {client_id} (number)
==============================================================================
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: ~
• {config} (table) Configuration table.
• border: (default=nil)
• Add borders to the floating window
• See |nvim_open_win()|
*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: ~
• {config} (table) Configuration table.
• border: (default=nil)
• Add borders to the floating window
• See |nvim_open_win()|
==============================================================================
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} (number) 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} (number) 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} (number) 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} (number) 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/specifications/lsp/3.17/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} (number) buffer number (0 for current)
• {row} 0-indexed line
• {col} 0-indexed byte offset in line
• {offset_encoding} (string) utf-8|utf-16|utf-32|nil defaults to
`offset_encoding` of first client of `buf`
Return: ~
(number, number) `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.
Parameters: ~
• {input} (`MarkedString` | `MarkedString[]` | `MarkupContent`)
• {contents} (table|nil) List of strings to extend with converted
lines. Defaults to {}.
Return: ~
{contents}, 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} Response of `textDocument/SignatureHelp`
• {ft} optional filetype that will be use as the `lang` for
the label markdown code block
• {triggers} optional list of trigger characters from the lsp
server. used to better determine parameter offsets
Return: ~
(list) of lines of converted markdown.
See also: ~
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
*vim.lsp.util.extract_completion_items()*
extract_completion_items({result})
Can be used to extract the completion items from a `textDocument/completion` request, which may return one of `CompletionItem[]` , `CompletionList` or null.
Parameters: ~
• {result} (table) The result of a `textDocument/completion` request
Return: ~
(table) List of completion items
See also: ~
https://microsoft.github.io/language-server-protocol/specification#textDocument_completion
get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()*
Returns indentation size.
Parameters: ~
• {bufnr} (number|nil) Buffer handle, defaults to current
Return: ~
(number) 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} "utf-8" | "utf-16" | "utf-32"
• {reuse_win} (boolean|nil) 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 result can be passed to the {list} argument of |setqflist()| or
|setloclist()|.
Parameters: ~
• {locations} (table) list of `Location`s or `LocationLink`s
• {offset_encoding} (string) offset_encoding for locations
utf-8|utf-16|utf-32
Return: ~
(table) list of items
lookup_section({settings}, {section}) *vim.lsp.util.lookup_section()*
Helper function to return nested values in language server settings
Parameters: ~
• {settings} a table of language server settings
• {section} a string indicating the field of the settings table
Return: ~
(table or string) The value of settings accessed via section
*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} (number) window width (in character cells)
• {height} (number) window height (in character cells)
• {opts} (table, optional)
• offset_x (number) offset to add to `col`
• offset_y (number) 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"
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|nil) with valid `FormattingOptions` entries
Return: ~
`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} number[]|nil {row, col} mark-indexed position.
Defaults to the start of the last visual selection.
• {end_pos} number[]|nil {row, col} mark-indexed position.
Defaults to the end of the last visual selection.
• {bufnr} (number|nil) buffer handle or 0 for current,
defaults to current
• {offset_encoding} "utf-8"|"utf-16"|"utf-32"|nil defaults to
`offset_encoding` of first client of `bufnr`
Return: ~
{ 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} (number|nil) window handle or 0 for current,
defaults to current
• {offset_encoding} (string|nil) utf-8|utf-16|utf-32|nil defaults to
`offset_encoding` of first client of buffer of
`window`
Return: ~
`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} (number|nil) window handle or 0 for current,
defaults to current
• {offset_encoding} "utf-8"|"utf-16"|"utf-32"|nil defaults to
`offset_encoding` of first client of buffer of
`window`
Return: ~
{ 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} (number|nil) Buffer handle, defaults to current
Return: ~
`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}
• {removed}
*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 passed
on to |nvim_open_win()|)
• height: (number) height of floating window
• width: (number) width of floating window
• wrap: (boolean, default true) wrap long lines
• wrap_at: (number) character to wrap at for computing
height when wrap is enabled
• max_width: (number) maximal width of floating window
• max_height: (number) maximal height of floating window
• pad_top: (number) number of lines to pad contents at top
• pad_bottom: (number) number of lines to pad contents at
bottom
• 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: ~
bufnr,winnr buffer and window number of the newly created floating
preview window
parse_snippet({input}) *vim.lsp.util.parse_snippet()*
Parses snippets in a completion entry.
Parameters: ~
• {input} (string) unparsed snippet
Return: ~
(string) parsed snippet
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} a single `Location` or `LocationLink`
Return: ~
(bufnr,winnr) buffer and window number of floating window or nil
rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()*
Rename old_fname to new_fname
Parameters: ~
• {opts} (table)
set_lines({lines}, {A}, {B}, {new_lines}) *vim.lsp.util.set_lines()*
Replaces text in a range with new text.
CAUTION: Changes in-place!
Parameters: ~
• {lines} (table) Original list of strings
• {A} (table) Start position; a 2-tuple of {line, col} numbers
• {B} (table) End position; a 2-tuple of {line, col} numbers
• {new_lines} A list of strings to replace the original
Return: ~
(table) The modified {lines} object
*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} "utf-8" | "utf-16" | "utf-32"
• {opts} (table|nil) 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} dictionary 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
• pad_top number of lines to pad contents at top
• pad_bottom number of lines to pad contents at bottom
• separator insert separator after code block
Return: ~
width,height size of float
symbols_to_items({symbols}, {bufnr}) *vim.lsp.util.symbols_to_items()*
Converts symbols to quickfix list items.
Parameters: ~
• {symbols} DocumentSymbol[] or SymbolInformation[]
*vim.lsp.util.text_document_completion_list_to_complete_items()*
text_document_completion_list_to_complete_items({result}, {prefix})
Turns the result of a `textDocument/completion` request into
vim-compatible |complete-items|.
Parameters: ~
• {result} The result of a `textDocument/completion` call, e.g. from
|vim.lsp.buf.completion()|, which may be one of
`CompletionItem[]`, `CompletionList` or `null`
• {prefix} (string) the prefix to filter the completion items
Return: ~
{ matches = complete-items table, incomplete = bool }
See also: ~
|complete-items|
trim_empty_lines({lines}) *vim.lsp.util.trim_empty_lines()*
Removes empty lines from the beginning and end.
Parameters: ~
• {lines} (table) list of lines to trim
Return: ~
(table) trimmed list of lines
*vim.lsp.util.try_trim_markdown_code_blocks()*
try_trim_markdown_code_blocks({lines})
Accepts markdown lines and tries to reduce them to a filetype if they
comprise just a single code block.
CAUTION: Modifies the input in-place!
Parameters: ~
• {lines} (table) list of lines
Return: ~
(string) filetype or "markdown" if it was unchanged.
==============================================================================
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: ~
(string) 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|number) One of `vim.lsp.log.levels`
should_log({level}) *vim.lsp.log.should_log()*
Checks whether the level is sufficient for logging.
Parameters: ~
• {level} (number) 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
Parameters: ~
• {host} (string)
• {port} (number)
Return: ~
(function)
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) 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|nil) Parameters for the invoked LSP method
Return: ~
(bool) `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|nil) Parameters for the invoked LSP
method
• {callback} fun(err: lsp.ResponseError | nil, result: any) Callback to invoke
• {notify_reply_callback} (function|nil) Callback to invoke as soon as
a request is no longer pending
Return: ~
(boolean) success, integer|nil request_id true, message_id if request
could be sent, `false` if not
*vim.lsp.rpc.rpc_response_error()*
rpc_response_error({code}, {message}, {data})
Creates an RPC response object/table.
Parameters: ~
• {code} (number) RPC error code defined in
`vim.lsp.protocol.ErrorCodes`
• {message} (string|nil) arbitrary message to send to server
• {data} any|nil arbitrary data to send to server
*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} (table) List of additional string arguments to
pass to {cmd}.
• {dispatchers} (table|nil) Dispatchers for LSP message types.
Valid dispatcher names are:
• `"notification"`
• `"server_request"`
• `"on_error"`
• `"on_exit"`
• {extra_spawn_params} (table|nil) Additional context for the LSP
server process. May contain:
• {cwd} (string) Working directory for the LSP
server process
• {env} (table) Additional environment variables
for LSP server process
Return: ~
Client RPC object.
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.sync *lsp-sync*
*vim.lsp.sync.compute_diff()*
compute_diff({___MissingCloseParenHere___})
Returns the range table for the difference between prev and curr lines
Parameters: ~
• {prev_lines} (table) list of lines
• {curr_lines} (table) list of lines
• {firstline} (number) line to begin search for first difference
• {lastline} (number) line to begin search in old_lines for last
difference
• {new_lastline} (number) line to begin search in new_lines for last
difference
• {offset_encoding} (string) encoding requested by language server
Return: ~
(table) TextDocumentContentChangeEvent see https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentContentChangeEvent
==============================================================================
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.
*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: ~
(table) Normalized table of capabilities
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
Reference in New Issue View Git Blame Copy Permalink