Nvim :help pages, generated
from source
using the tree-sitter-vimdoc parser.
LSP
vim.lsp for building
enhanced LSP tools.
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]),
}):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.
K exists.
lsp-defaults-disable
To override the above defaults, set or unset the options on LspAttach: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,
})vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args)
vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
end,
})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,
}):lua =vim.lsp.get_clients()[1].server_capabilities:lua vim.lsp.stop_client(vim.lsp.get_clients())
:edit:verbose set omnifunc?
async parameter and set the value to
false. E.g. code formatting:" 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
vim.lsp.buf_… functions perform operations for all LSP clients attached
to the given buffer. lsp-buf
lsp-method
:lua vim.print(vim.tbl_keys(vim.lsp.handlers))lsp-handler
LSP handlers are functions that handle lsp-responses 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)
function(err, result, ctx, config)
{err} (table|nil) Error info dict, or nil if the request
completed.
{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
result, err where err is shaped like an RPC error:{ code, message, data? }
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
-- Disable signs
signs = false,
}
)vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
-- Enable signs
signs = true,
}
){handlers} key
for vim.lsp.start_client()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,
}
),
},
}{handlers} key of setup():
require('lspconfig').rust_analyzer.setup {
handlers = {
["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
-- Disable virtual_text
virtual_text = false
}
),
}
}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:
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:vim.lsp.handlers["textDocument/definition"] = my_custom_default_definition{handlers} parameter of vim.lsp.start(). This sets the default
lsp-handler for the server being started. Example:vim.lsp.start {
..., -- Other configuration omitted.
handlers = {
["textDocument/definition"] = my_custom_server_definition
},
}{handler} parameter of vim.lsp.buf_request_all(). This sets
the lsp-handler ONLY for the given request(s). Example:vim.lsp.buf_request_all(
0,
"textDocument/definition",
my_request_params,
my_handler
)vim.lsp.log_levels
Log levels are defined in vim.log.levels
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
vim.lsp.protocol.ErrorCodes allows reverse lookup by number or
name: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
on_list receives a table with:
items table[], structured like setqflist-what
title string, title for the list.
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})local function on_list(options)
vim.fn.setloclist(0, {}, ' ', options)
vim.api.nvim_command('lopen')
endhl-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
hl-LspCodeLens
LspCodeLens
Used to color the virtual text of the codelens. See
nvim_buf_set_extmark().
hl-LspCodeLensSeparator
Used to color the separator between two or more code lenses.
hl-LspSignatureActiveParameter
LspSignatureActiveParameter
Used to highlight the active parameter in the signature help. See
vim.lsp.handlers.signature_help().
type such as "function" or "variable", and 0 or more
modifiers such as "readonly" or "deprecated." The standard types and
modifiers are described here:
https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_semanticTokens
LSP servers may also use off-spec types 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: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.semantic_tokens is the priority of the
@lsp.type.* highlights. The @lsp.mod.* and @lsp.typemod.* highlights
have priorities one and two higher, respectively.
-- 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@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
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: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: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
This event is triggered after each successful notification sent to an
LSP server.
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
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
pattern is set to kind
(one of begin, report or end).
data table with client_id and
result properties. result will contain the request params sent by the
server.
autocmd LspProgress * redrawstatusLspRequest
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.
{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.
{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: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
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:
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,
}){bufnr}, {client_id}) vim.lsp.buf_attach_client()
Implements the textDocument/did… notifications required to track a
buffer for any language server.
{bufnr} (integer) Buffer handle, or 0 for current
{client_id} (integer) Client id
true if client was attached successfully; false
otherwise
{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.
{bufnr} (integer) Buffer handle, or 0 for current
{client_id} (integer) Client id
{bufnr}, {client_id}) vim.lsp.buf_is_attached()
Checks if a buffer is attached for a particular client.
{bufnr} (integer) Buffer handle, or 0 for current
{client_id} (integer) the client id
{bufnr} (integer|nil) The number of the buffer
{method} (string) Name of the request method
{params} (any) Arguments to send to the server
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.
{bufnr} (integer) Buffer handle, or 0 for current.
{method} (string) LSP method name
{params} (table|nil) Parameters to send to the server
{handler} (function) Handler called after all requests are completed.
Server results are passed as a client_id:result map.
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.
{timeout_ms} (default 1000) ms.
{bufnr} (integer) Buffer handle, or 0 for current.
{method} (string) LSP method name
{params} (table|nil) Parameters to send to the server
{timeout_ms} (integer|nil) Maximum time in milliseconds to wait for a
result. Defaults to 1000
err is a string
describing the failure reason, and result is nil.
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().
{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.
{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().
{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_id}) vim.lsp.client_is_stopped()
Checks whether a client is stopped.
{client_id} (integer)
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.
workspace/executeCommand.
Command: Command title:
String command: String arguments?: any[]
ctx of lsp-handler
{opts}) vim.lsp.formatexpr()
Provides an interface between the built-in client and a formatexpr
function.
on_attach viavim.bo[bufnr].formatexpr =
'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`.
{opts} (table) options for customizing the formatting expression
which takes the following optional keys:
vim.lsp.get_buffers_by_client_id()
get_buffers_by_client_id({client_id})
Returns list of buffers attached to client_id.
{client_id} (integer) client 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.
{client_id} (integer) client id
{filter}) vim.lsp.get_clients()
Get active clients.
{filter} (table|nil) A table with key-value pairs used to filter the
returned clients. The available keys are:
vim.lsp.get_log_path()
Gets the path of the logfile used by the LSP client.
{bufnr} (integer) Buffer handle, or 0 for current
{enable} (boolean|nil) true/false to enable/disable, nil to toggle
{findstart} (integer) 0 or 1, decides behavior
{base} (integer) findstart=0, text to match against
{findstart}:
{level}) vim.lsp.set_log_level()
Sets the global log level for LSP logging.
lsp.log_levels for reverse lookup.
{level} (integer|string) the case insensitive level name or number
{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.
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]),
})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.
ftplugin/<filetype_name>.lua (See ftplugin-name)
{config} (table) Same configuration as documented in
vim.lsp.start_client()
{opts} (nil|lsp.StartOpts) Optional keyword arguments:
{config}) vim.lsp.start_client()
Starts and initializes a client with the given configuration.
cmd in {config} is required.
{config} ( lsp.ClientConfig ) Configuration for the server:
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 process. Not related to root_dir.
{ PORT = 8080; HOST = "0.0.0.0"; }
workspaceFolders in
the LSP spec.
workspace/configuration. Keys are case-sensitive.
initializationOptions. See initialize in the LSP
spec.
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.
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.
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_init to do any actions once the
client has been initialized.
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
stop() function on a vim.lsp.client object. To
stop all clients:vim.lsp.stop_client(vim.lsp.get_clients()){client_id} integer|table id or vim.lsp.client object, or list
thereof
{force} (boolean|nil) shutdown forcefully
{pattern}, {flags}) vim.lsp.tagfunc()
Provides an interface between the built-in client and 'tagfunc'.
{pattern} (string) Pattern used to find a workspace symbol
{flags} (string) See tag-function
{handler}, {override_config}) vim.lsp.with()
Function to manage overriding defaults for LSP handlers.
{handler} (function) See lsp-handler
{override_config} (table) Table containing the keys to override
behavior of the {handler}
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().
vim.lsp.buf.clear_references()
Removes document highlights from current buffer.
{options}) vim.lsp.buf.code_action()
Selects a code action available at the current cursor position.
{options} (table|nil) Optional table which holds the following
optional fields:
CodeActionContext of the LSP specification:
Diagnostic[]. Inferred
from the current position if not provided.
CodeActionKinds used to
filter the code actions. Most language servers support
values like refactor or quickfix.
CodeAction
and returning a boolean.
true, and there is
just one remaining action (after filtering), the action
is applied without user query.
start and end keys with
{row,col} tuples using mark-like indexing. See
api-indexing
{context}) vim.lsp.buf.completion()
Retrieves the completion items at the current cursor position. Can only be
called in Insert mode.
{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)
{options}) vim.lsp.buf.declaration()
Jumps to the declaration of the symbol under the cursor.
{options} (table|nil) additional options
{options}) vim.lsp.buf.definition()
Jumps to the definition of the symbol under the cursor.
{options} (table|nil) additional options
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.: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(){options}) vim.lsp.buf.document_symbol()
Lists all symbols in the current buffer in the quickfix window.
{options} (table|nil) additional options
{command_params}) vim.lsp.buf.execute_command()
Executes an LSP server command.
{command_params} (table) A valid ExecuteCommandParams object
{options}) vim.lsp.buf.format()
Formats a buffer using the attached (and optionally filtered) language
server clients.
{options} (table|nil) Optional table which holds the following
optional fields:
-- Never request typescript-language-server for formatting
vim.lsp.buf.format {
filter = function(client) return client.name ~= "tsserver" end
}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
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.
{options}) vim.lsp.buf.implementation()
Lists all the implementations for the symbol under the cursor in the
quickfix window.
{options} (table|nil) additional options
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().
vim.lsp.buf.list_workspace_folders()
List workspace folders.
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().
{context}, {options}) vim.lsp.buf.references()
Lists all the references to the symbol under the cursor in the quickfix
window.
{context} (table|nil) Context for the request
{options} (table|nil) additional options
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().
{new_name}, {options}) vim.lsp.buf.rename()
Renames all references to the symbol under the cursor.
{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
vim.lsp.buf.signature_help()
Displays signature information about the symbol under the cursor in a
floating window.
{options}) vim.lsp.buf.type_definition()
Jumps to the definition of the type of the symbol under the cursor.
{options} (table|nil) additional options
{query}, {options}) vim.lsp.buf.workspace_symbol()
Lists all symbols in the current workspace in the quickfix window.
{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.
{query} (string|nil) optional
{options} (table|nil) additional options
vim.lsp.diagnostic.get_namespace()
get_namespace({client_id}, {is_pull})
Get the diagnostic namespace associated with an LSP client
vim.diagnostic for diagnostics
{client_id} (integer) The id of the LSP client
{is_pull} (boolean) Whether the namespace is for a pull or push
client
vim.lsp.diagnostic.on_diagnostic()
on_diagnostic({_}, {result}, {ctx}, {config})
lsp-handler for the method "textDocument/diagnostic"
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,
}
){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"
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,
}
){config} (table) Configuration table (see vim.diagnostic.config()).
{client_id} (integer|nil) filter by client_id. All clients if nil
{bufnr} (integer|nil) filter by buffer. All buffers if nil
{lenses}, {bufnr}, {client_id}) vim.lsp.codelens.display()
Display the lenses using virtual text
{lenses} lsp.CodeLens[]|nil lenses to display
{bufnr} (integer)
{client_id} (integer)
{bufnr}) vim.lsp.codelens.get()
Return all lenses for the given buffer
{bufnr} (integer) Buffer number. 0 can be used for the current
buffer.
vim.lsp.codelens.on_codelens()
on_codelens({err}, {result}, {ctx}, {_})
lsp-handler for the method textDocument/codeLens
vim.lsp.codelens.refresh()
Refresh the codelens for the current buffer
autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh()vim.lsp.codelens.run()
Run the code lens in the current line
{lenses}, {bufnr}, {client_id}) vim.lsp.codelens.save()
Store lenses for a specific buffer and client
{lenses} lsp.CodeLens[]|nil lenses to store
{bufnr} (integer)
{client_id} (integer)
{bufnr}) vim.lsp.semantic_tokens.force_refresh()
Force a refresh of all semantic tokens
{bufnr} (integer|nil) 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.
{bufnr} (integer|nil) Buffer number (0 for current buffer, default)
{row} (integer|nil) Position row (default cursor position)
{col} (integer|nil) Position column (default cursor position)
vim.lsp.semantic_tokens.highlight_token()
highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts})
Highlight a semantic token.
{bufnr} (integer) the buffer to highlight
{client_id} (integer) The ID of the vim.lsp.client
{hl_group} (string) Highlight group name
{opts} (table|nil) Optional parameters.
vim.highlight.priorities.semantic_tokens + 3
{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.
{server_capabilities} of your client in your LspAttach callback
or your configuration's on_attach callback:client.server_capabilities.semanticTokensProvider = nil{bufnr} (integer)
{client_id} (integer)
{opts} (nil|table) Optional keyword arguments
{bufnr}, {client_id}) vim.lsp.semantic_tokens.stop()
Stop the semantic token highlighting engine for the given buffer with the
given client.
start(), so you should only need this function to manually
disengage the semantic token engine without fully detaching the LSP client
from the buffer.
{bufnr} (integer)
{client_id} (integer)
{_}, {result}, {ctx}, {config}) vim.lsp.handlers.hover()
lsp-handler for the method "textDocument/hover"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"
}
){config} (table) Configuration table.
vim.lsp.handlers.signature_help()
signature_help({_}, {result}, {ctx}, {config})
lsp-handler for the method "textDocument/signatureHelp".
vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
vim.lsp.handlers.signature_help, {
-- Use a sharp border with `FloatBorder` highlights
border = "single"
}
){result} (table) Response from the language server
{ctx} (table) Client context
{config} (table) Configuration table.
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.
{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)
vim.lsp.util.apply_text_edits()
apply_text_edits({text_edits}, {bufnr}, {offset_encoding})
Applies a list of text edits to a buffer.
{text_edits} (table) list of TextEdit objects
{bufnr} (integer) Buffer id
{offset_encoding} (string) utf-8|utf-16|utf-32
vim.lsp.util.apply_workspace_edit()
apply_workspace_edit({workspace_edit}, {offset_encoding})
Applies a WorkspaceEdit.
{workspace_edit} (table) WorkspaceEdit
{offset_encoding} (string) utf-8|utf-16|utf-32 (required)
{bufnr}) vim.lsp.util.buf_clear_references()
Removes document highlights from a buffer.
{bufnr} (integer|nil) 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.
{bufnr} (integer) Buffer id
{references} (table) List of DocumentHighlight objects to
highlight
{offset_encoding} (string) One of "utf-8", "utf-16", "utf-32".
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.
{buf} (integer) 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 defaults to
offset_encoding of first client of buf
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.
MarkupContent and its kind is
plaintext, then the corresponding value is returned without further
modifications.
{input} (MarkedString | MarkedString[] | MarkupContent)
{contents} (table|nil) List of strings to extend with converted
lines. Defaults to {}.
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.
{signature_help} (table) Response of textDocument/SignatureHelp
{ft} (string|nil) filetype that will be use as the lang
for the label markdown code block
{triggers} (table|nil) list of trigger characters from the lsp
server. used to better determine parameter offsets
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.
{result} (table) The result of a textDocument/completion request
{bufnr}) vim.lsp.util.get_effective_tabstop()
Returns indentation size.
{bufnr} (integer|nil) Buffer handle, defaults to current
vim.lsp.util.jump_to_location()
jump_to_location({location}, {offset_encoding}, {reuse_win})
Jumps to a location.
{location} (table) (Location`LocationLink`)
{offset_encoding} (string|nil) utf-8|utf-16|utf-32
{reuse_win} (boolean|nil) Jump to existing window if buffer is
already open.
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.
user_data field of each resulting item will contain the original
Location or LocationLink it was computed from.
{locations} (table) list of Locations or LocationLinks
{offset_encoding} (string) offset_encoding for locations
utf-8|utf-16|utf-32 default to first client of
buffer
{settings}, {section}) vim.lsp.util.lookup_section()
Helper function to return nested values in language server settings
{settings} (table) language server settings
{section} string indicating the field of the settings table
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().
{width} (integer) window width (in character cells)
{height} (integer) window height (in character cells)
{opts} (table) optional
col
row
border
focusable
zindex, defaults to 50
vim.lsp.util.make_formatting_params()
make_formatting_params({options})
Creates a DocumentFormattingParams object for the current buffer and
cursor position.
{options} (table|nil) with valid FormattingOptions entries
DocumentFormattingParams object
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().
{start_pos} integer[]|nil {row,col} mark-indexed position.
Defaults to the start of the last visual selection.
{end_pos} integer[]|nil {row,col} mark-indexed position.
Defaults to the end of the last visual selection.
{bufnr} (integer|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
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.
{window} (integer|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
TextDocumentPositionParams object
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.
{window} (integer|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
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.
{bufnr} (integer|nil) Buffer handle, defaults to current
TextDocumentIdentifier
vim.lsp.util.make_workspace_params()
make_workspace_params({added}, {removed})
Create the workspace params
{added} (table)
{removed} (table)
vim.lsp.util.open_floating_preview()
open_floating_preview({contents}, {syntax}, {opts})
Shows contents in a floating window.
{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())
true, and if
{focusable} is also true, focus an existing floating
window with the same {focus_id}
{input}) vim.lsp.util.parse_snippet()
Parses snippets in a completion entry.
{input} (string) unparsed snippet
{location}, {opts}) vim.lsp.util.preview_location()
Previews a location in a floating window
{location} (table) a single Location or LocationLink
{opts} (table)
{lines}, {A}, {B}, {new_lines}) vim.lsp.util.set_lines()
Replaces text in a range with new text.
{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} (table) list of strings to replace the original
{lines} object
vim.lsp.util.show_document()
show_document({location}, {offset_encoding}, {opts})
Shows document and optionally jumps to the location.
{location} (table) (Location`LocationLink`)
{offset_encoding} (string|nil) utf-8|utf-16|utf-32
{opts} (table|nil) options
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.
open_floating_preview instead
{contents} (table) of lines to show in window
{opts} (table) with optional fields
{symbols}, {bufnr}) vim.lsp.util.symbols_to_items()
Converts symbols to quickfix list items.
{symbols} (table) 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.
{result} (table) 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
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.
{lines} (table) list of lines
vim.lsp.log.get_filename()
Returns the log filename.
vim.lsp.log.get_level()
Gets the current log level.
{handle}) vim.lsp.log.set_format_func()
Sets formatting function used to format logs
{handle} (function) function to apply to logging arguments, pass
vim.inspect for multi-line formatting
{level}) vim.lsp.log.set_level()
Sets the current log level.
{level} (string|integer) One of vim.lsp.log.levels
{level}) vim.lsp.log.should_log()
Checks whether the level is sufficient for logging.
{level} (integer) log level
{host}, {port}) vim.lsp.rpc.connect()
Create a LSP RPC client factory that connects via TCP to the given host
and port
{host} (string)
{port} (integer)
{err}) vim.lsp.rpc.format_rpc_error()
Constructs an error message from an LSP error object.
{err} (table) The error object
{method} (string) The invoked LSP method
{params} (table|nil) Parameters for the invoked LSP method
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.
{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
false if not
vim.lsp.rpc.rpc_response_error()
rpc_response_error({code}, {message}, {data})
Creates an RPC response object/table.
{code} (integer) 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()
{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
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.
vim.lsp.protocol.make_client_capabilities()
make_client_capabilities()
Gets a new ClientCapabilities object describing the LSP client
capabilities.
vim.lsp.protocol.Methods
LSP method names.
vim.lsp.protocol.resolve_capabilities()
resolve_capabilities({server_capabilities})
Creates a normalized object describing LSP server capabilities.
{server_capabilities} (table) Table of capabilities supported by the
server