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 instructions. You can find language servers here: https://microsoft.github.io/language-server-protocol/implementors/servers/

2. Use vim.lsp.config() to define a configuration for an LSP client. Example:

vim.lsp.config['luals'] = {
  -- Command and arguments to start the server.
  cmd = { 'lua-language-server' }
  -- Filetypes to automatically attach to.
  filetypes = { 'lua' },
  -- Sets the "root directory" to the parent directory of the file in the
  -- current buffer that contains either a ".luarc.json" or a
  -- ".luarc.jsonc" file. Files that share a root directory will reuse
  -- the connection to the same LSP server.
  root_markers = { '.luarc.json', '.luarc.jsonc' },
  -- Specific settings to send to the server. The schema for this is
  -- defined by the server. For example the schema for lua-language-server
  -- can be found here https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json
  settings = {
    Lua = {
      runtime = {
        version = 'LuaJIT',
      }
    }
  }
}

3. Use vim.lsp.enable() to enable a configuration. Example:

vim.lsp.enable('luals')

4. Check that the buffer is attached to the server:

:checkhealth vim.lsp

5. (Optional) Configure keymaps and autocommands to use LSP features. lsp-attach

lsp-config

Configurations for LSP clients is done via vim.lsp.config().

When an LSP client starts, it resolves a configuration by merging configurations, in increasing priority, from the following:

1. Configuration defined for the '*' name.

2. Configuration from the result of merging all tables returned by lsp/<name>.lua files in 'runtimepath' for a server of name name.

3. Configurations defined anywhere else.

Note: The merge semantics of configurations follow the behaviour of vim.tbl_deep_extend().

Example:

Given:

-- Defined in init.lua
vim.lsp.config('*', {
  capabilities = {
    textDocument = {
      semanticTokens = {
        multilineTokenSupport = true,
      }
    }
  }
  root_markers = { '.git' },
})
-- Defined in ../lsp/clangd.lua
return {
  cmd = { 'clangd' },
  root_markers = { '.clangd', 'compile_commands.json' },
  filetypes = { 'c', 'cpp' },
}
-- Defined in init.lua
vim.lsp.config('clangd', {
  filetypes = { 'c' },
})

Results in the configuration:

{
  -- From the clangd configuration in <rtp>/lsp/clangd.lua
  cmd = { 'clangd' },
  -- From the clangd configuration in <rtp>/lsp/clangd.lua
  -- Overrides the * configuration in init.lua
  root_markers = { '.clangd', 'compile_commands.json' },
  -- From the clangd configuration in init.lua
  -- Overrides the * configuration in init.lua
  filetypes = { 'c' },
  -- From the * configuration in init.lua
  capabilities = {
    textDocument = {
      semanticTokens = {
        multilineTokenSupport = true,
      }
    }
  }
}

lsp-defaults
When the Nvim 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.

grr gra grn gri i_CTRL-S Some keymaps are created unconditionally when Nvim starts:

If not wanted, these keymaps can be removed at any time using vim.keymap.del() or :unmap (see also gr-default).

lsp-defaults-disable
To override or delete any of the above defaults, set or unset the options on LspAttach:

vim.api.nvim_create_autocmd('LspAttach', {
  callback = function(args)
    -- Unset 'formatexpr'
    vim.bo[args.buf].formatexpr = nil
    -- Unset 'omnifunc'
    vim.bo[args.buf].omnifunc = nil
    -- Unmap K
    vim.keymap.del('n', 'K', { buffer = args.buf })
  end,
})

lsp-attach
To use other LSP features, set keymaps and other buffer options on LspAttach. Not all language servers provide the same capabilities. Use capability checks to ensure you only use features supported by the language server. Example:

vim.api.nvim_create_autocmd('LspAttach', {
  callback = function(args)
    local client = vim.lsp.get_client_by_id(args.data.client_id)
    if client:supports_method('textDocument/implementation') then
      -- Create a keymap for vim.lsp.buf.implementation
    end
    if client:supports_method('textDocument/completion') then
      -- Enable auto-completion
      vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true})
    end
    if client:supports_method('textDocument/formatting') then
      -- Format the current buffer on save
      vim.api.nvim_create_autocmd('BufWritePre', {
        buffer = args.buf,
        callback = function()
          vim.lsp.buf.format({bufnr = args.buf, id = client.id})
        end,
      })
    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)

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-resolution
Handlers can be set by (in increasing priority):

Example:

vim.lsp.handlers['textDocument/publishDiagnostics'] = my_custom_diagnostics_handler

Note: this only applies for requests/notifications made by the server to the client.

Example:

vim.lsp.start {
  ..., -- Other configuration omitted.
  handlers = {
    ['textDocument/publishDiagnostics'] = my_custom_server_definition
  },
}

Note: this only applies for requests/notifications made by the server to the client.

Example:

vim.lsp.buf_request_all(
  0,
  'textDocument/publishDiagnostics',
  my_request_params,
  my_handler
)

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-LspReferenceTarget
LspReferenceTarget used for highlighting reference targets (e.g. in a hover range) 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.hl.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. See lsp-attach for an example.

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)
    -- Get the detaching client
    local client = vim.lsp.get_client_by_id(args.data.client_id)
    -- Remove the autocommand to format the buffer on save, if it exists
    if client:supports_method('textDocument/formatting') then
      vim.api.nvim_clear_autocmds({
        event = 'BufWritePre',
        buffer = args.buf,
      })
    end
  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 params properties. params will contain the request params sent by the server (see lsp.ProgressParams).

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

vim.lsp.Config Extends: vim.lsp.ClientConfig

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, {error: 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 an 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

config({name}, {cfg}) vim.lsp.config()
Update the configuration for an LSP client.

Use name '*' to set default configuration for all clients.

Can also be table-assigned to redefine the configuration for a client.

Examples:

enable({name}, {enable}) vim.lsp.enable()
Enable an LSP server to automatically start when opening a buffer.

Uses configuration defined with vim.lsp.config.

Examples:

vim.lsp.enable('clangd')
vim.lsp.enable({'luals', 'pyright'})

foldclose({kind}, {winid}) vim.lsp.foldclose()
Close all {kind} of folds in the the window with {winid}.

To automatically fold imports when opening a file, you can use an autocmd:

vim.api.nvim_create_autocmd('LspNotify', {
  callback = function(args)
    if args.data.method == 'textDocument/didOpen' then
      vim.lsp.foldclose('imports', vim.fn.bufwinid(args.buf))
    end
  end,
})

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

To use, check for the "textDocument/foldingRange" capability in an LspAttach autocommand. Example:

vim.api.nvim_create_autocommand('LspAttach', {
  callback = function(args)
    local client = vim.lsp.get_client_by_id(args.data.client_id)
    if client:supports_method('textDocument/foldingRange') then
      vim.wo.foldmethod = 'expr'
      vim.wo.foldexpr = 'v:lua.vim.lsp.foldexpr()'
    end
  end,
})

foldtext() vim.lsp.foldtext()
Provides a foldtext function that shows the collapsedText retrieved, defaults to the first folded line if collapsedText is not provided.

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() or (more typically) 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.root(0, {'pyproject.toml', 'setup.py'}),
})

See vim.lsp.ClientConfig 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

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

Lua module: vim.lsp.client lsp-client

vim.lsp.Client

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

vim.lsp.ClientConfig

Client:cancel_request({id}) Client:cancel_request()
Cancels a request with a given request id.

(boolean) status indicating if the notification was successful.

Client:exec_cmd({command}, {context}, {handler}) Client:exec_cmd()
Execute a lsp command, either via client command function (if available) or via workspace/executeCommand (if supported by the server)

Client:is_stopped() Client:is_stopped()
Checks whether a client is stopped.

(boolean) true if client is stopped or in the process of being stopped; false otherwise

Client:notify({method}, {params}) Client:notify()
Sends a notification to an LSP server.

(boolean) status indicating if the notification was successful. If it is false, then the client has shutdown.

Client:on_attach({bufnr}) Client:on_attach()
Runs the on_attach function from the client's config if it was defined. Useful for buffer-local setup.

Client:request()
Client:request({method}, {params}, {handler}, {bufnr}) Sends a request to the server.

This is a thin wrapper around {client.rpc.request} with some additional checks for capabilities and handler availability.

(boolean) status indicates whether the request was successful. If it is false, then it will always be false (the client has shutdown). (integer?) request_id Can be used with Client:cancel_request(). nil is request failed.

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

({err: lsp.ResponseError?, result:any}?) result and err from the lsp-handler. nil is the request was unsuccessful (string?) err On timeout, cancel or error, where err is a string describing the failure reason.

Client:stop({force}) Client:stop()
Stops a client, optionally with force.

By default, it will just request 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.

Client:supports_method({method}, {bufnr}) Client:supports_method()
Checks if a client supports a given method. Always returns true for unknown off-spec methods.

Note: Some language server capabilities can be file specific.

Lua module: vim.lsp.buf lsp-buf

vim.lsp.ListOpts

If you prefer loclist instead of qflist:

vim.lsp.buf.definition({ loclist = true })
vim.lsp.buf.references(nil, { loclist = true })

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

vim.lsp.LocationOpts.OnList

vim.lsp.buf.hover.Opts Extends: vim.lsp.util.open_floating_preview.Opts

vim.lsp.buf.signature_help.Opts Extends: vim.lsp.util.open_floating_preview.Opts

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({opts}) vim.lsp.buf.code_action()
Selects a code action available at the current cursor position.

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

definition({opts}) 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({opts}) vim.lsp.buf.document_symbol()
Lists all symbols in the current buffer in the quickfix window.

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

hover({config}) vim.lsp.buf.hover()
Displays hover information about the symbol under the cursor in a floating window. The window will be dismissed on cursor move. Calling the function twice will jump into the floating window (thus by default, "KK" will open the hover window and focus it). In the floating window, all commands and mappings are available as usual, except that "q" dismisses the window. You can scroll the contents the same as you would any other buffer.

Note: to disable hover highlights, add the following to your config:

vim.api.nvim_create_autocmd('ColorScheme', {
  callback = function()
    vim.api.nvim_set_hl(0, 'LspReferenceTarget', {})
  end,
})

implementation({opts}) 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}, {opts}) 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}, {opts}) vim.lsp.buf.rename()
Renames all references to the symbol under the cursor.

signature_help({config}) vim.lsp.buf.signature_help()
Displays signature information about the symbol under the cursor in a floating window.

type_definition({opts}) 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}, {opts}) 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

from({diagnostics}) vim.lsp.diagnostic.from()
Converts the input vim.Diagnostics to LSP diagnostics.

(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({error}, {result}, {ctx}) lsp-handler for the method "textDocument/diagnostic"

See vim.diagnostic.config() for configuration options.

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

See vim.diagnostic.config() for configuration options.

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.completion lsp-completion

vim.lsp.completion.BufferOpts

vim.lsp.completion.enable()
enable({enable}, {client_id}, {bufnr}, {opts}) Enables or disables completions from the given language client in the given buffer.

trigger() vim.lsp.completion.trigger()
Trigger LSP completion in the current buffer.

Lua module: vim.lsp.inlay_hint lsp-inlay_hint

enable({enable}, {filter}) vim.lsp.inlay_hint.enable()
Enables or disables inlay hints for the {filter}ed scope.

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

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

Since: 0.10.0

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)
local resp = client:request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0)
local resolved_hint = assert(resp and resp.result, resp.err)
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,
})

Since: 0.10.0

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

is_enabled({filter}) vim.lsp.inlay_hint.is_enabled()
Query whether inlay hint is enabled in the {filter}ed scope

Since: 0.10.0

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

vim.lsp.util.open_floating_preview.Opts

vim.lsp.util.apply_text_document_edit()
apply_text_document_edit({text_document_edit}, {index}, {position_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}, {position_encoding}) Applies a list of text edits to a buffer.

vim.lsp.util.apply_workspace_edit()
apply_workspace_edit({workspace_edit}, {position_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}, {position_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.

(string[]?) lines of converted markdown. (Range4?) highlight range for the active parameter

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

(integer) indentation size

vim.lsp.util.locations_to_items()
locations_to_items({locations}, {position_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().

(vim.quickfix.entry[]) See setqflist() for the format

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

(vim.api.keyset.win_config)

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}, {position_encoding}) Using the given range in the current buffer, creates an object that is similar to vim.lsp.util.make_range_params().

({ textDocument: { uri: lsp.DocumentUri }, range: lsp.Range })

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

(lsp.TextDocumentPositionParams)

vim.lsp.util.make_range_params()
make_range_params({window}, {position_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.

({ textDocument: { uri: lsp.DocumentUri }, range: lsp.Range })

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

(lsp.TextDocumentIdentifier)

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

(lsp.WorkspaceFoldersChangeEvent)

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}, {position_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.

(vim.quickfix.entry[]) See setqflist() for the format

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.

(boolean) true if would log, false if not

Lua module: vim.lsp.rpc lsp-rpc

vim.lsp.rpc.PublicClient Client RPC object

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

(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) See vim.lsp.rpc.PublicClient.

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