Lsp

LSP client/framework 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).

QUICKSTART lsp-quickstart

Nvim provides an LSP client, but the servers are provided by third parties. Follow these steps to get LSP features:

1. Install language servers using your package manager or by following the upstream installation instruction. You can find language servers here: https://microsoft.github.io/language-server-protocol/implementors/servers/

2. Configure the LSP client per language server. See vim.lsp.start() or use this minimal example as a guide:

vim.lsp.start({
  name = 'my-server-name',
  cmd = {'name-of-language-server-executable'},
  root_dir = vim.fs.dirname(vim.fs.find({'setup.py', 'pyproject.toml'}, { upward = true })[1]),
})

3. Check that the server attached to the buffer:

:lua =vim.lsp.get_clients()

4. Configure keymaps and autocmds to use LSP features. See lsp-config.

lsp-config lsp-defaults When the LSP client starts it enables diagnostics vim.diagnostic (see vim.diagnostic.config() to customize). It also sets various default options, listed below, if (1) the language server supports the functionality and (2) the options are empty or were set by the builtin runtime (ftplugin) files. The options are not restored when the LSP client is stopped or detached.

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,
})

To use other LSP features like hover, rename, etc. you can set other keymaps on LspAttach. Example:

vim.api.nvim_create_autocmd('LspAttach', {
  callback = function(args)
    vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
  end,
})

The most common functions are:

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:

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:

:lua =vim.lsp.get_clients()[1].server_capabilities

Full list of features provided by default can be found in lsp-buf.

FAQ lsp-faq

lsp-vs-treesitter

Treesitter is a language parsing library that provides excellent tools for incrementally parsing text and handling errors. This makes it a great fit for editors to understand the contents of the current file for things like syntax highlighting, simple goto-definitions, scope analysis and more.

LSP and Treesitter are both great tools for editing and inspecting code.

LSP API lsp-api

LSP core API is described at lsp-core. Those are the core functions for creating and managing clients.

The vim.lsp.buf_… functions perform operations for all LSP clients attached to the given buffer. lsp-buf

LSP request/response handlers are implemented as Lua functions (see lsp-handler). lsp-method

Requests and notifications defined by the LSP specification are referred to as "LSP methods". The Nvim LSP client provides default handlers in the global vim.lsp.handlers table, you can list them with this command:

:lua vim.print(vim.tbl_keys(vim.lsp.handlers))

They are also listed below. Note that handlers depend on server support: they won't run if your server doesn't support them.

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)

Each response handler has this signature:

function(err, result, ctx, config)

Two values result, err where err is shaped like an RPC error:

{ code, message, data? }

You can use vim.lsp.rpc.rpc_response_error() to create this object.

lsp-handler-configuration

To configure the behavior of a builtin lsp-handler, the convenient method vim.lsp.with() is provided for users.

To configure the behavior of vim.lsp.diagnostic.on_publish_diagnostics(), consider the following example, where a new lsp-handler is created using vim.lsp.with() that no longer generates signs for the diagnostics:

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:

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()

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():

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:

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:

In summary, the lsp-handler will be chosen based on the current lsp-method in the following order:

1. Handler passed to vim.lsp.buf_request_all(), if any. 2. Handler defined in vim.lsp.start(), if any. 3. Handler defined in vim.lsp.handlers, if any.

vim.lsp.log_levels Log levels are defined in vim.log.levels

VIM.LSP.PROTOCOL vim.lsp.protocol

Module vim.lsp.protocol defines constants dictated by the LSP specification, and helper functions for creating protocol-related objects. https://github.com/microsoft/language-server-protocol/raw/gh-pages/_specifications/specification-3-14.md

For example vim.lsp.protocol.ErrorCodes allows reverse lookup by number or name:

vim.lsp.protocol.TextDocumentSyncKind.Full == 1
vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"

lsp-response LSP response shape: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage

lsp-notification LSP notification shape: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage

LSP HIGHLIGHT lsp-highlight

Reference Highlights:

Highlight groups that are meant to be used by vim.lsp.buf.document_highlight().

You can see more about the differences in types here: https://microsoft.github.io/language-server-protocol/specification#textDocument_documentHighlight

hl-LspReferenceText LspReferenceText used for highlighting "text" references hl-LspReferenceRead LspReferenceRead used for highlighting "read" references hl-LspReferenceWrite LspReferenceWrite used for highlighting "write" references hl-LspInlayHint LspInlayHint used for highlighting inlay hints

lsp-highlight-codelens

Highlight groups related to lsp-codelens functionality.

hl-LspCodeLens LspCodeLens Used to color the virtual text of the codelens. See nvim_buf_set_extmark().

LspCodeLensSeparator hl-LspCodeLensSeparator Used to color the separator between two or more code lenses.

lsp-highlight-signature

Highlight groups related to vim.lsp.handlers.signature_help().

hl-LspSignatureActiveParameter LspSignatureActiveParameter Used to highlight the active parameter in the signature help. See vim.lsp.handlers.signature_help().

LSP SEMANTIC HIGHLIGHTS lsp-semantic-highlight

When available, the LSP client highlights code using lsp-semantic_tokens, which are another way that LSP servers can provide information about source code. Note that this is in addition to treesitter syntax highlighting; semantic highlighting does not replace syntax highlighting.

The server will typically provide one token per identifier in the source code. The token will have a type such as "function" or "variable", and 0 or more modifiers such as "readonly" or "deprecated." The standard types and modifiers are described here: https://microsoft.github.io/language-server-protocol/specification/#textDocument_semanticTokens LSP servers may also use off-spec types and modifiers.

The LSP client adds one or more highlights for each token. The highlight groups are derived from the token's type and modifiers:

The value vim.highlight.priorities.semantic_tokens is the priority of the @lsp.type.* highlights. The @lsp.mod.* and @lsp.typemod.* highlights have priorities one and two higher, respectively.

You can disable semantic highlights by clearing the highlight groups:

-- Hide semantic highlights for functions
vim.api.nvim_set_hl(0, '@lsp.type.function', {})
-- Hide all semantic highlights
for _, group in ipairs(vim.fn.getcompletion("@lsp", "highlight")) do
  vim.api.nvim_set_hl(0, group, {})
end

You probably want these inside a ColorScheme autocommand.

Use LspTokenUpdate and vim.lsp.semantic_tokens.highlight_token() for more complex highlighting.

The following is a list of standard captures used in queries for Nvim, highlighted according to the current colorscheme (use :Inspect on one to see the exact definition):

@lsp.type.class Identifiers that declare or reference a class type @lsp.type.comment Tokens that represent a comment @lsp.type.decorator Identifiers that declare or reference decorators and annotations @lsp.type.enum Identifiers that declare or reference an enumeration type @lsp.type.enumMember Identifiers that declare or reference an enumeration property, constant, or member @lsp.type.event Identifiers that declare an event property @lsp.type.function Identifiers that declare a function @lsp.type.interface Identifiers that declare or reference an interface type @lsp.type.keyword Tokens that represent a language keyword @lsp.type.macro Identifiers that declare a macro @lsp.type.method Identifiers that declare a member function or method @lsp.type.modifier Tokens that represent a modifier @lsp.type.namespace Identifiers that declare or reference a namespace, module, or package @lsp.type.number Tokens that represent a number literal @lsp.type.operator Tokens that represent an operator @lsp.type.parameter Identifiers that declare or reference a function or method parameters @lsp.type.property Identifiers that declare or reference a member property, member field, or member variable @lsp.type.regexp Tokens that represent a regular expression literal @lsp.type.string Tokens that represent a string literal @lsp.type.struct Identifiers that declare or reference a struct type @lsp.type.type Identifiers that declare or reference a type that is not covered above @lsp.type.typeParameter Identifiers that declare or reference a type parameter @lsp.type.variable Identifiers that declare or reference a local or global variable

@lsp.mod.abstract Types and member functions that are abstract @lsp.mod.async Functions that are marked async @lsp.mod.declaration Declarations of symbols @lsp.mod.defaultLibrary Symbols that are part of the standard library @lsp.mod.definition Definitions of symbols, for example, in header files @lsp.mod.deprecated Symbols that should no longer be used @lsp.mod.documentation Occurrences of symbols in documentation @lsp.mod.modification Variable references where the variable is assigned to @lsp.mod.readonly Readonly variables and member fields (constants) @lsp.mod.static Class members (static members)

EVENTS lsp-events

LspAttach LspAttach After an LSP client attaches to a buffer. The autocmd-pattern is the name of the buffer. When used from Lua, the client ID is passed to the callback in the "data" table. Example:

vim.api.nvim_create_autocmd("LspAttach", {
  callback = function(args)
    local bufnr = args.buf
    local client = vim.lsp.get_client_by_id(args.data.client_id)
    if client.server_capabilities.completionProvider then
      vim.bo[bufnr].omnifunc = "v:lua.vim.lsp.omnifunc"
    end
    if client.server_capabilities.definitionProvider then
      vim.bo[bufnr].tagfunc = "v:lua.vim.lsp.tagfunc"
    end
  end,
})

LspDetach LspDetach Just before an LSP client detaches from a buffer. The autocmd-pattern is the name of the buffer. When used from Lua, the client ID is passed to the callback in the "data" table. Example:

vim.api.nvim_create_autocmd("LspDetach", {
  callback = function(args)
    local client = vim.lsp.get_client_by_id(args.data.client_id)
    -- Do something with the client
    vim.cmd("setlocal tagfunc< omnifunc<")
  end,
})

LspNotify LspNotify This event is triggered after each successful notification sent to an LSP server.

When used from Lua, the client_id, LSP method, and parameters are sent in the "data" table. Example:

vim.api.nvim_create_autocmd('LspNotify', {
  callback = function(args)
    local bufnr = args.buf
    local client_id = args.data.client_id
    local method = args.data.method
    local params = args.data.params
    -- do something with the notification
    if method == 'textDocument/...' then
      update_buffer(bufnr)
    end
  end,
})

LspProgress LspProgress Upon receipt of a progress notification from the server. Notifications can be polled from a progress ring buffer of a vim.lsp.Client or use vim.lsp.status() to get an aggregate message

If the server sends a "work done progress", the pattern is set to kind (one of begin, report or end).

When used from Lua, the event contains a data table with client_id and result properties. result will contain the request params sent by the server.

Example:

autocmd LspProgress * redrawstatus

LspRequest LspRequest For each request sent to an LSP server, this event is triggered for every change to the request's status. The status can be one of pending, complete, or cancel and is sent as the {type} on the "data" table passed to the callback function.

It triggers when the initial request is sent ({type} == pending) and when the LSP server responds ({type} == complete). If a cancellation is requested using client.cancel_request(request_id), then this event will trigger with {type} == cancel.

When used from Lua, the client ID, request ID, and request are sent in the "data" table. See {requests} in vim.lsp.Client for details on the {request} value. If the request type is complete, the request will be deleted from the client's pending requests table immediately after calling the event's callbacks. Example:

vim.api.nvim_create_autocmd('LspRequest', {
  callback = function(args)
    local bufnr = args.buf
    local client_id = args.data.client_id
    local request_id = args.data.request_id
    local request = args.data.request
    if request.type == 'pending' then
      -- do something with pending requests
      track_pending(client_id, bufnr, request_id, request)
    elseif request.type == 'cancel' then
      -- do something with pending cancel requests
      track_canceling(client_id, bufnr, request_id, request)
    elseif request.type == 'complete' then
      -- do something with finished requests. this pending
      -- request entry is about to be removed since it is complete
      track_finish(client_id, bufnr, request_id, request)
    end
  end,
})

LspTokenUpdate LspTokenUpdate When a visible semantic token is sent or updated by the LSP server, or when an existing token becomes visible for the first time. The autocmd-pattern is the name of the buffer. When used from Lua, the token and client ID are passed to the callback in the "data" table. The token fields are documented in vim.lsp.semantic_tokens.get_at_pos(). Example:

vim.api.nvim_create_autocmd('LspTokenUpdate', {
  callback = function(args)
    local token = args.data.token
    if token.type == 'variable' and not token.modifiers.readonly then
      vim.lsp.semantic_tokens.highlight_token(
        token, args.buf, args.data.client_id, 'MyMutableVariableHighlight'
      )
    end
  end,
})

Note: doing anything other than calling vim.lsp.semantic_tokens.highlight_token() is considered experimental.

Lua module: vim.lsp lsp-core

buf_attach_client({bufnr}, {client_id}) vim.lsp.buf_attach_client() Implements the textDocument/did… notifications required to track a buffer for any language server.

Without calling this, the server won't be notified of changes to a buffer.

(boolean) success true if client was attached successfully; false otherwise

buf_detach_client({bufnr}, {client_id}) vim.lsp.buf_detach_client() Detaches client from the specified buffer.Note: While the server is notified that the text document (buffer) was closed, it is still able to send notifications should it ignore this notification.

buf_is_attached({bufnr}, {client_id}) vim.lsp.buf_is_attached() Checks if a buffer is attached for a particular client.

buf_notify({bufnr}, {method}, {params}) vim.lsp.buf_notify() Send a notification to a server

(boolean) success true if any client returns true; false otherwise

vim.lsp.buf_request_all() buf_request_all({bufnr}, {method}, {params}, {handler}) Sends an async request for all active clients attached to the buffer and executes the handler callback with the combined result.

(function) cancel Function that cancels all requests.

vim.lsp.buf_request_sync() buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) Sends a request to all server and waits for the response of all of them.

Calls vim.lsp.buf_request_all() but blocks Nvim while awaiting the result. Parameters are the same as vim.lsp.buf_request_all() but the result is different. Waits a maximum of {timeout_ms}.

(table<integer, {err: lsp.ResponseError, result: any}>?) result Map of client_id:request_result. (string?) err On timeout, cancel, or error, err is a string describing the failure reason, and result is nil.

client_is_stopped({client_id}) vim.lsp.client_is_stopped() Checks whether a client is stopped.

(boolean) stopped true if client is stopped, false otherwise.

commands vim.lsp.commands Registry for client side commands. This is an extension point for plugins to handle custom commands which are not part of the core language server protocol specification.

The registry is a table where the key is a unique command name, and the value is a function which is called if any LSP action (code action, code lenses, ...) triggers the command.

If a LSP response contains a command for which no matching entry is available in this registry, the command will be executed via the LSP server using workspace/executeCommand.

The first argument to the function will be the Command: Command title: String command: String arguments?: any[]

The second argument is the ctx of lsp-handler

formatexpr({opts}) vim.lsp.formatexpr() Provides an interface between the built-in client and a formatexpr function.

Currently only supports a single client. This can be set via setlocal formatexpr=v:lua.vim.lsp.formatexpr() but will typically or in on_attach via vim.bo[bufnr].formatexpr = 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'.

vim.lsp.get_buffers_by_client_id() get_buffers_by_client_id({client_id}) Returns list of buffers attached to client_id.

(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.

(vim.lsp.Client?) client rpc object

get_clients({filter}) vim.lsp.get_clients() Get active clients.

(vim.lsp.Client[]) List of vim.lsp.Client objects

get_log_path() vim.lsp.get_log_path() Gets the path of the logfile used by the LSP client.

(string) path to log file

omnifunc({findstart}, {base}) vim.lsp.omnifunc() Implements 'omnifunc' compatible LSP completion.

(integer|table) Decided by {findstart}:

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.

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:

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:

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)

(integer?) client_id

start_client({config}) vim.lsp.start_client() Starts and initializes a client with the given configuration.

(integer?) client_id vim.lsp.get_client_by_id()Note: client may not be fully initialized. Use on_init to do any actions once the client has been initialized.

status() vim.lsp.status() Consumes the latest progress messages from all clients and formats them as a string. Empty if there are no clients or if no new messages

(string)

stop_client({client_id}, {force}) vim.lsp.stop_client() Stops a client(s).

You can also use the stop() function on a vim.lsp.Client object. To stop all clients:

vim.lsp.stop_client(vim.lsp.get_clients())

By default asks the server to shutdown, unless stop was requested already for this client, then force-shutdown is attempted.

tagfunc({pattern}, {flags}) vim.lsp.tagfunc() Provides an interface between the built-in client and 'tagfunc'.

When used with normal mode commands (e.g. CTRL-]) this will invoke the "textDocument/definition" LSP method to find the tag under the cursor. Otherwise, uses "workspace/symbol". If no results are returned from any LSP servers, falls back to using built-in tags.

(table[]) tags A list of matching tags

with({handler}, {override_config}) vim.lsp.with() Function to manage overriding defaults for LSP handlers.

Lua module: vim.lsp.client lsp-client

vim.lsp.Client

vim.lsp.Client.Progress Extends: vim.Ringbuf

vim.lsp.ClientConfig

Lua module: vim.lsp.buf lsp-buf

vim.lsp.ListOpts

If you prefer loclist do something like this:

local function on_list(options)
  vim.fn.setloclist(0, {}, ' ', options)
  vim.cmd.lopen()
end

vim.lsp.LocationOpts Extends: vim.lsp.ListOpts

vim.lsp.LocationOpts.OnList

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.

completion({context}) vim.lsp.buf.completion() Retrieves the completion items at the current cursor position. Can only be called in Insert mode.

declaration({options}) vim.lsp.buf.declaration() Jumps to the declaration of the symbol under the cursor.

definition({options}) vim.lsp.buf.definition() Jumps to the definition of the symbol under the cursor.

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.:

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.

execute_command({command_params}) vim.lsp.buf.execute_command() Executes an LSP server command.

format({options}) vim.lsp.buf.format() Formats a buffer using the attached (and optionally filtered) language server clients.

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.

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.

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.

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.

typehierarchy({kind}) vim.lsp.buf.typehierarchy() Lists all the subtypes or supertypes of the symbol under the cursor in the quickfix window. If the symbol can resolve to multiple items, the user can pick one using vim.ui.select().

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.

Lua module: vim.lsp.diagnostic lsp-diagnostic

vim.lsp.diagnostic.get_namespace() get_namespace({client_id}, {is_pull}) Get the diagnostic namespace associated with an LSP client vim.diagnostic for diagnostics

vim.lsp.diagnostic.on_diagnostic() on_diagnostic({_}, {result}, {ctx}, {config}) lsp-handler for the method "textDocument/diagnostic"

See vim.diagnostic.config() for configuration options. Handler-specific configuration can be set using vim.lsp.with():

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,
  }
)

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():

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,
  }
)

Lua module: vim.lsp.codelens lsp-codelens

clear({client_id}, {bufnr}) vim.lsp.codelens.clear() Clear the lenses

display({lenses}, {bufnr}, {client_id}) vim.lsp.codelens.display() Display the lenses using virtual text

get({bufnr}) vim.lsp.codelens.get() Return all lenses for the given buffer

(lsp.CodeLens[])

on_codelens({err}, {result}, {ctx}) vim.lsp.codelens.on_codelens() lsp-handler for the method textDocument/codeLens

refresh({opts}) vim.lsp.codelens.refresh() Refresh the lenses.

It is recommended to trigger this using an autocmd or via keymap.

Example:

autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh({ bufnr = 0 })

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

Lua module: vim.lsp.inlay_hint lsp-inlay_hint

enable({enable}, {filter}) vim.lsp.inlay_hint.enable() Enables or disables inlay hints for a buffer.

To "toggle", pass the inverse of is_enabled():

vim.lsp.inlay_hint.enable(not vim.lsp.inlay_hint.is_enabled())

get({filter}) vim.lsp.inlay_hint.get() Get the list of inlay hints, (optionally) restricted by buffer or range.

Example usage:

local hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer
local client = vim.lsp.get_client_by_id(hint.client_id)
resolved_hint = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0).result
vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding)
location = resolved_hint.label[1].location
client.request('textDocument/hover', {
  textDocument = { uri = location.uri },
  position = location.range.start,
})

(table[]) A list of objects with the following fields:

is_enabled({bufnr}) vim.lsp.inlay_hint.is_enabled()

(boolean)

Lua module: vim.lsp.semantic_tokens lsp-semantic_tokens

force_refresh({bufnr}) vim.lsp.semantic_tokens.force_refresh() Force a refresh of all semantic tokens

Only has an effect if the buffer is currently active for semantic token highlighting (vim.lsp.semantic_tokens.start() has been called for it)

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.

(table?) List of tokens at position. Each token has the following fields:

vim.lsp.semantic_tokens.highlight_token() highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts}) Highlight a semantic token.

Apply an extmark with a given highlight group for a semantic token. The mark will be deleted by the semantic token engine when appropriate; for example, when the LSP sends updated tokens. This function is intended for use inside LspTokenUpdate callbacks.

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:

client.server_capabilities.semanticTokensProvider = nil

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.

Lua module: vim.lsp.handlers lsp-handlers

hover({_}, {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"
  }
)

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.

vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with(
  vim.lsp.handlers.signature_help, {
    -- Use a sharp border with `FloatBorder` highlights
    border = "single"
  }
)

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.

vim.lsp.util.apply_text_edits() apply_text_edits({text_edits}, {bufnr}, {offset_encoding}) Applies a list of text edits to a buffer.

vim.lsp.util.apply_workspace_edit() apply_workspace_edit({workspace_edit}, {offset_encoding}) Applies a WorkspaceEdit.

buf_clear_references({bufnr}) vim.lsp.util.buf_clear_references() Removes document highlights from a buffer.

vim.lsp.util.buf_highlight_references() buf_highlight_references({bufnr}, {references}, {offset_encoding}) Shows a list of document highlights for a certain buffer.

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.

(integer) offset_encoding index of the character in line {row} column {col} in buffer {buf}

vim.lsp.util.convert_input_to_markdown_lines() convert_input_to_markdown_lines({input}, {contents}) Converts any of MarkedString | MarkedString[] | MarkupContent into a list of lines containing valid markdown. Useful to populate the hover window for textDocument/hover, for parsing the result of textDocument/signatureHelp, and potentially others.

Note that if the input is of type MarkupContent and its kind is plaintext, then the corresponding value is returned without further modifications.

(string[]) extended with lines of converted markdown.

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.

(table?) table list of lines of converted markdown. (table?) table of active hl

get_effective_tabstop({bufnr}) vim.lsp.util.get_effective_tabstop() Returns indentation size.

(integer) indentation size

vim.lsp.util.jump_to_location() jump_to_location({location}, {offset_encoding}, {reuse_win}) Jumps to a location.

(boolean) true if the jump succeeded

vim.lsp.util.locations_to_items() locations_to_items({locations}, {offset_encoding}) Returns the items with the byte position calculated correctly and in sorted order, for display in quickfix and location lists.

The user_data field of each resulting item will contain the original Location or LocationLink it was computed from.

The result can be passed to the {list} argument of setqflist() or setloclist().

(table[]) A list of objects with the following fields:

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().

(table) Options

vim.lsp.util.make_formatting_params() make_formatting_params({options}) Creates a DocumentFormattingParams object for the current buffer and cursor position.

(lsp.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().

(table) { textDocument = { uri = current_file_uri }, range = { start = start_position, end = end_position } }

vim.lsp.util.make_position_params() make_position_params({window}, {offset_encoding}) Creates a TextDocumentPositionParams object for the current buffer and cursor position.

(table) 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.

(table) { textDocument = { uri = current_file_uri }, range = { start = current_position, end = current_position } }

vim.lsp.util.make_text_document_params() make_text_document_params({bufnr}) Creates a TextDocumentIdentifier object for the current buffer.

(table) TextDocumentIdentifier

vim.lsp.util.make_workspace_params() make_workspace_params({added}, {removed}) Create the workspace params

vim.lsp.util.open_floating_preview() open_floating_preview({contents}, {syntax}, {opts}) Shows contents in a floating window.

(integer) bufnr of newly created float window (integer) winid of newly created float window preview window

preview_location({location}, {opts}) vim.lsp.util.preview_location() Previews a location in a floating window

behavior depends on type of location:

(integer?) buffer id of float window (integer?) window id of float window

rename({old_fname}, {new_fname}, {opts}) vim.lsp.util.rename() Rename old_fname to new_fname

Existing buffers are renamed as well, while maintaining their bufnr.

It deletes existing buffers that conflict with the renamed file name only when

vim.lsp.util.show_document() show_document({location}, {offset_encoding}, {opts}) Shows document and optionally jumps to the location.

(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

(table) stripped content

symbols_to_items({symbols}, {bufnr}) vim.lsp.util.symbols_to_items() Converts symbols to quickfix list items.

Lua module: vim.lsp.log lsp-log

get_filename() vim.lsp.log.get_filename() Returns the log filename.

(string) log filename

get_level() vim.lsp.log.get_level() Gets the current log level.

(integer) current log level

set_format_func({handle}) vim.lsp.log.set_format_func() Sets formatting function used to format logs

set_level({level}) vim.lsp.log.set_level() Sets the current log level.

should_log({level}) vim.lsp.log.should_log() Checks whether the level is sufficient for logging.

(bool) true if would log, false if not

Lua module: vim.lsp.rpc lsp-rpc

vim.lsp.rpc.PublicClient

connect({host_or_path}, {port}) vim.lsp.rpc.connect() Create a LSP RPC client factory that connects to either:

Return a function that can be passed to the cmd field for vim.lsp.start_client() or vim.lsp.start().

(fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient)

format_rpc_error({err}) vim.lsp.rpc.format_rpc_error() Constructs an error message from an LSP error object.

(string) error_message The formatted error message

notify({method}, {params}) vim.lsp.rpc.notify() Sends a notification to the LSP server.

(boolean) true if notification could be sent, false if not

vim.lsp.rpc.request() request({method}, {params}, {callback}, {notify_reply_callback}) Sends a request to the LSP server and runs {callback} upon response.

(boolean) success true if request could be sent, false if not (integer?) message_id if request could be sent, nil if not

vim.lsp.rpc.rpc_response_error() rpc_response_error({code}, {message}, {data}) Creates an RPC response table error to be sent to the LSP response.

(lsp.ResponseError)

start({cmd}, {dispatchers}, {extra_spawn_params}) vim.lsp.rpc.start() 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()

(vim.lsp.rpc.PublicClient?) Client RPC object, with these methods:

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.

(lsp.ClientCapabilities)

Methods vim.lsp.protocol.Methods LSP method names.

vim.lsp.protocol.resolve_capabilities() resolve_capabilities({server_capabilities}) Creates a normalized object describing LSP server capabilities.

(lsp.ServerCapabilities?) Normalized table of capabilities