*lsp.txt*   LSP


                            NVIM REFERENCE MANUAL


LSP client/framework                                     *lsp* *LSP*

Nvim supports the Language Server Protocol (LSP), which means it acts as
a client to LSP servers and includes a Lua framework `vim.lsp` for building
enhanced LSP tools.
  https://microsoft.github.io/language-server-protocol/

LSP facilitates features like go-to-definition, find-references, hover,
completion, rename, format, refactor, etc., using semantic whole-project
analysis (unlike |ctags|).

                                      Type |gO| to see the table of contents.

==============================================================================
QUICKSTART                                              *lsp-quickstart*

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

  1. Install the nvim-lspconfig plugin.  It provides common configuration for
     various servers so you can get started quickly.
     https://github.com/neovim/nvim-lspconfig
  2. Install a language server.  Try ":LspInstall <tab>" or use your system
     package manager to install the relevant language server:
     https://microsoft.github.io/language-server-protocol/implementors/servers/
  3. Add `nvim_lsp.xx.setup{…}` to your vimrc, where "xx" is the name of the
     relevant config.  See the nvim-lspconfig README for details.

To check LSP clients attached to the current buffer:  >

  :lua print(vim.inspect(vim.lsp.buf_get_clients()))
<
                                                        *lsp-config*
Inline diagnostics are enabled automatically, e.g. syntax errors will be
annotated in the buffer.  But you probably want to use other features like
go-to-definition, hover, etc. Full list of features in |vim.lsp.buf|. 

Example config: >

  nnoremap <silent> <c-]> <cmd>lua vim.lsp.buf.definition()<CR>
  nnoremap <silent> K     <cmd>lua vim.lsp.buf.hover()<CR>
  nnoremap <silent> gD    <cmd>lua vim.lsp.buf.implementation()<CR>
  nnoremap <silent> <c-k> <cmd>lua vim.lsp.buf.signature_help()<CR>
  nnoremap <silent> 1gD   <cmd>lua vim.lsp.buf.type_definition()<CR>
  nnoremap <silent> gr    <cmd>lua vim.lsp.buf.references()<CR>
  nnoremap <silent> g0    <cmd>lua vim.lsp.buf.document_symbol()<CR>
  nnoremap <silent> gW    <cmd>lua vim.lsp.buf.workspace_symbol()<CR>
  nnoremap <silent> gd    <cmd>lua vim.lsp.buf.declaration()<CR>

Note: Language servers may have limited support for these features.

Nvim provides the |vim.lsp.omnifunc| 'omnifunc' handler which allows
|i_CTRL-X_CTRL-O| to consume LSP completion. Example config (note the use of
|v:lua| to call Lua from Vimscript): >

  " Use LSP omni-completion in Python files.
  autocmd Filetype python setlocal omnifunc=v:lua.vim.lsp.omnifunc

If a function has a `*_sync` variant, it's primarily intended for being run
automatically on file save.  E.g. code formatting: >

  " Auto-format *.rs files prior to saving them
  autocmd BufWritePre *.rs lua vim.lsp.buf.formatting_sync(nil, 1000)

================================================================================
FAQ                                                     *lsp-faq*

- Q: How to force-reload LSP?
  A: Stop all clients, then reload the buffer. >

  :lua vim.lsp.stop_client(vim.lsp.get_active_clients())
  :edit

- Q: Why isn't completion working?
  A: In the buffer where you want to use LSP, check that 'omnifunc' is set to
  "v:lua.vim.lsp.omnifunc": >

  :verbose set omnifunc?

<  Some other plugin may be overriding the option. To avoid that, you could
  set the option in an |after-directory| ftplugin, e.g.
  "after/ftplugin/python.vim".

================================================================================
LSP API                                                 *lsp-api*

The `vim.lsp` Lua module is a framework for building LSP plugins.

  1. Start with |vim.lsp.start_client()| and |vim.lsp.buf_attach_client()|.
  2. Peek at the API: >
     :lua print(vim.inspect(vim.lsp))
<  3. See |lsp-extension-example| for a full example.

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 callbacks.
|lsp-callbacks| The `vim.lsp.callbacks` table defines default callbacks used
when creating a new client. Keys are LSP method names: >

  :lua print(vim.inspect(vim.tbl_keys(vim.lsp.callbacks)))

These LSP requests/notifications are defined by default:

  textDocument/publishDiagnostics
  window/logMessage
  window/showMessage

You can check these via `vim.tbl_keys(vim.lsp.callbacks)`.

These will be used preferentially in `vim.lsp.buf_…` methods for handling
requests. They will also be used when responding to server requests and
notifications.

Use cases:
- Users can modify this to customize to their preferences.
- UI plugins can modify this by assigning to
  `vim.lsp.callbacks[method]` so as to provide more specialized
  handling, allowing you to leverage the UI capabilities available. UIs should
  try to be conscientious of any existing changes the user may have set
  already by checking for existing values.

Any callbacks passed directly to `request` methods on a server client will
have the highest precedence, followed by the `callbacks`.

You can override the default handlers,
- globally: by modifying the `vim.lsp.callbacks` table
- per-client: by passing the {callbacks} table parameter to
  |vim.lsp.start_client|

Each handler has this signature: >

  function(err, method, params, client_id)

Callbacks are functions which are called in a variety of situations by the
client. Their signature is `function(err, method, params, client_id)` They can
be set by the {callbacks} parameter for |vim.lsp.start_client| or via the
|vim.lsp.callbacks|.

Handlers are called for:
- Notifications from the server (`err` is always `nil`).
- Requests initiated by the server (`err` is always `nil`).
  The handler can respond by returning two values: `result, err`
  where `err` must be shaped like an RPC error:
    `{ code, message, data? }`
  You can use |vim.lsp.rpc_response_error()| to create this object.
- Handling requests initiated by the client if the request doesn't explicitly
  specify a callback (such as in |vim.lsp.buf_request|).


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 HIGHLIGHT                                                    *lsp-highlight*

                                                        *hl-LspDiagnosticsError*
LspDiagnosticsError               used for "Error" diagnostic virtual text
                                                    *hl-LspDiagnosticsErrorSign*
LspDiagnosticsErrorSign           used for "Error" diagnostic signs in sign
                                  column
                                                *hl-LspDiagnosticsErrorFloating*
LspDiagnosticsErrorFloating       used for "Error" diagnostic messages in the
                                  diagnostics float
                                                      *hl-LspDiagnosticsWarning*
LspDiagnosticsWarning             used for "Warning" diagnostic virtual text
                                                  *hl-LspDiagnosticsWarningSign*
LspDiagnosticsWarningSign         used for "Warning" diagnostic signs in sign
                                  column
                                              *hl-LspDiagnosticsWarningFloating*
LspDiagnosticsWarningFloating     used for "Warning" diagnostic messages in the
                                  diagnostics float
                                                  *hl-LspDiagnosticsInformation*
LspDiagnosticsInformation         used for "Information" diagnostic virtual text
                                              *hl-LspDiagnosticsInformationSign*
LspDiagnosticsInformationSign     used for "Information" signs in sign column
                                          *hl-LspDiagnosticsInformationFloating*
LspDiagnosticsInformationFloating used for "Information" diagnostic messages in
                                  the diagnostics float
                                                         *hl-LspDiagnosticsHint*
LspDiagnosticsHint                used for "Hint" diagnostic virtual text
                                                     *hl-LspDiagnosticsHintSign*
LspDiagnosticsHintSign            used for "Hint" diagnostic signs in sign
                                  column
                                                 *hl-LspDiagnosticsHintFloating*
LspDiagnosticsHintFloating        used for "Hint" diagnostic messages in the
                                  diagnostics float
                                                           *hl-LspReferenceText*
LspReferenceText          used for highlighting "text" references
                                                           *hl-LspReferenceRead*
LspReferenceRead          used for highlighting "read" references
                                                          *hl-LspReferenceWrite*
LspReferenceWrite         used for highlighting "write" references


================================================================================
LSP EXAMPLE                                            *lsp-extension-example*

This example is for plugin authors or users who want a lot of control. If you
are just getting started see |lsp-quickstart|.

For more advanced configurations where just filtering by filetype isn't
sufficient, you can use the `vim.lsp.start_client()` and
`vim.lsp.buf_attach_client()` commands to easily customize the configuration
however you please. For example, if you want to do your own filtering, or
start a new LSP client based on the root directory for if you plan to work
with multiple projects in a single session. Below is a fully working Lua
example which can do exactly that.

The example will:
1. Check for each new buffer whether or not we want to start an LSP client.
2. Try to find a root directory by ascending from the buffer's path.
3. Create a new LSP for that root directory if one doesn't exist.
4. Attach the buffer to the client for that root directory.

>
  -- Some path manipulation utilities
  local function is_dir(filename)
    local stat = vim.loop.fs_stat(filename)
    return stat and stat.type == 'directory' or false
  end

  local path_sep = vim.loop.os_uname().sysname == "Windows" and "\\" or "/"
  -- Asumes filepath is a file.
  local function dirname(filepath)
    local is_changed = false
    local result = filepath:gsub(path_sep.."([^"..path_sep.."]+)$", function()
      is_changed = true
      return ""
    end)
    return result, is_changed
  end

  local function path_join(...)
    return table.concat(vim.tbl_flatten {...}, path_sep)
  end

  -- Ascend the buffer's path until we find the rootdir.
  -- is_root_path is a function which returns bool
  local function buffer_find_root_dir(bufnr, is_root_path)
    local bufname = vim.api.nvim_buf_get_name(bufnr)
    if vim.fn.filereadable(bufname) == 0 then
      return nil
    end
    local dir = bufname
    -- Just in case our algo is buggy, don't infinite loop.
    for _ = 1, 100 do
      local did_change
      dir, did_change = dirname(dir)
      if is_root_path(dir, bufname) then
        return dir, bufname
      end
      -- If we can't ascend further, then stop looking.
      if not did_change then
        return nil
      end
    end
  end

  -- A table to store our root_dir to client_id lookup. We want one LSP per
  -- root directory, and this is how we assert that.
  local javascript_lsps = {}
  -- Which filetypes we want to consider.
  local javascript_filetypes = {
    ["javascript.jsx"] = true;
    ["javascript"]     = true;
    ["typescript"]     = true;
    ["typescript.jsx"] = true;
  }

  -- Create a template configuration for a server to start, minus the root_dir
  -- which we will specify later.
  local javascript_lsp_config = {
    name = "javascript";
    cmd = { path_join(os.getenv("JAVASCRIPT_LANGUAGE_SERVER_DIRECTORY"), "lib", "language-server-stdio.js") };
  }

  -- This needs to be global so that we can call it from the autocmd.
  function check_start_javascript_lsp()
    local bufnr = vim.api.nvim_get_current_buf()
    -- Filter which files we are considering.
    if not javascript_filetypes[vim.api.nvim_buf_get_option(bufnr, 'filetype')] then
      return
    end
    -- Try to find our root directory. We will define this as a directory which contains
    -- node_modules. Another choice would be to check for `package.json`, or for `.git`.
    local root_dir = buffer_find_root_dir(bufnr, function(dir)
      return is_dir(path_join(dir, 'node_modules'))
      -- return vim.fn.filereadable(path_join(dir, 'package.json')) == 1
      -- return is_dir(path_join(dir, '.git'))
    end)
    -- We couldn't find a root directory, so ignore this file.
    if not root_dir then return end

    -- Check if we have a client alredy or start and store it.
    local client_id = javascript_lsps[root_dir]
    if not client_id then
      local new_config = vim.tbl_extend("error", javascript_lsp_config, {
        root_dir = root_dir;
      })
      client_id = vim.lsp.start_client(new_config)
      javascript_lsps[root_dir] = client_id
    end
    -- Finally, attach to the buffer to track changes. This will do nothing if we
    -- are already attached.
    vim.lsp.buf_attach_client(bufnr, client_id)
  end

  vim.api.nvim_command [[autocmd BufReadPost * lua check_start_javascript_lsp()]]
<


==============================================================================
AUTOCOMMANDS                                                *lsp-autocommands*

                                                       *LspDiagnosticsChanged*
LspDiagnosticsChanged           After receiving publishDiagnostics server response


==============================================================================
Lua module: vim.lsp                                                 *lsp-core*

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

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

                Parameters: ~
                    {bufnr}      (number) Buffer handle, or 0 for current
                    {client_id}  (number) Client id

buf_get_clients({bufnr})                           *vim.lsp.buf_get_clients()*
                Gets a map of client_id:client pairs for the given buffer,
                where each value is a |vim.lsp.client| object.

                Parameters: ~
                    {bufnr}  (optional, number): Buffer handle, or 0 for
                             current

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

                Parameters: ~
                    {bufnr}      (number) Buffer handle, or 0 for current
                    {client_id}  (number) the client id

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

                Parameters: ~
                    {bufnr}   [number] (optional): The number of the buffer
                    {method}  [string]: Name of the request method
                    {params}  [string]: Arguments to send to the server

                Return: ~
                    true if any client returns true; false otherwise

                                                       *vim.lsp.buf_request()*
buf_request({bufnr}, {method}, {params}, {callback})
                Sends an async request for all active clients attached to the
                buffer.

                Parameters: ~
                    {bufnr}     (number) Buffer handle, or 0 for current.
                    {method}    (string) LSP method name
                    {params}    (optional, table) Parameters to send to the
                                server
                    {callback}  (optional, functionnil) Handler

                Return: ~
                    2-tuple:
                    • Map of client-id:request-id pairs for all successful
                      requests.
                    • Function which can be used to cancel all the requests.
                      You could instead iterate all clients and call their
                      `cancel_request()` methods.

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

                Calls |vim.lsp.buf_request()| but blocks Nvim while awaiting
                the result. Parameters are the same as |vim.lsp.buf_request()|
                but the return result is different. Wait maximum of
                {timeout_ms} (default 100) ms.

                Parameters: ~
                    {bufnr}       (number) Buffer handle, or 0 for current.
                    {method}      (string) LSP method name
                    {params}      (optional, table) Parameters to send to the
                                  server
                    {timeout_ms}  (optional, number, default=100) Maximum time
                                  in milliseconds to wait for a result.

                Return: ~
                    Map of client_id:request_result. On timeout, cancel or
                    error, returns `(nil, err)` where `err` is a string
                    describing the failure reason.

client()                                                      *vim.lsp.client*
                LSP client object. You can get an active client object via
                |vim.lsp.get_client_by_id()| or
                |vim.lsp.get_active_clients()|.

                • Methods:
                  • request(method, params, [callback], bufnr) Sends a request
                    to the server. This is a thin wrapper around
                    {client.rpc.request} with some additional checking. If
                    {callback} is not specified, it will use
                    {client.callbacks} to try to find a callback. 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.
                  • notify(method, params) Sends a notification to an LSP
                    server. Returns: a boolean to indicate if the notification
                    was successful. If it is false, then it will always be
                    false (the client has shutdown).
                  • cancel_request(id) Cancels a request with a given request
                    id. Returns: same as `notify()` .
                  • stop([force]) Stops a client, optionally with force. By
                    default, it will just ask the server to shutdown without
                    force. If you request to stop a client which has
                    previously been requested to shutdown, it will
                    automatically escalate and force shutdown.
                  • is_stopped() Checks whether a client is stopped. Returns:
                    true if the client is fully stopped.
                  • on_attach(bufnr) Runs the on_attach function from the
                    client's config if it was defined.

                • Members
                  • {id} (number): The id allocated to the client.
                  • {name} (string): If a name is specified on creation, that
                    will be used. Otherwise it is just the client id. This is
                    used for logs and messages.
                  • {rpc} (table): RPC client object, for low level
                    interaction with the client. See |vim.lsp.rpc.start()|.
                  • {offset_encoding} (string): The encoding used for
                    communicating with the server. You can modify this in the
                    `config` 's `on_init` method before text is sent to the
                    server.
                  • {callbacks} (table): The callbacks used by the client as
                    described in |lsp-callbacks|.
                  • {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.
                  • {resolved_capabilities} (table): Normalized table of
                    capabilities that we have detected based on the initialize
                    response from the server in `server_capabilities` .

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

                Parameters: ~
                    {client_id}  (Number)

                Return: ~
                    true if client is stopped, false otherwise.

get_active_clients()                            *vim.lsp.get_active_clients()*
                Gets all active clients.

                Return: ~
                    Table of |vim.lsp.client| objects

get_client_by_id({client_id})                     *vim.lsp.get_client_by_id()*
                Gets an active client by id, or nil if the id is invalid or
                the client is not yet initialized.

                Parameters: ~
                    {client_id}  client id number

                Return: ~
                    |vim.lsp.client| object, or nil

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

                Return: ~
                    (String) Path to logfile.

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

                Parameters: ~
                    {findstart}  0 or 1, decides behavior
                    {base}       If findstart=0, text to match against

                Return: ~
                    (number) Decided by`findstart`:
                    • findstart=0: column where the completion starts, or -2
                      or -3
                    • findstart=1: list of matches (actually just calls
                      |complete()|)

                See also: ~
                    |complete-functions|
                    |complete-items|
                    |CompleteDone|

set_log_level({level})                               *vim.lsp.set_log_level()*
                Sets the global log level for LSP logging.

                Levels by name: "trace", "debug", "info", "warn", "error"
                Level numbers begin with "trace" at 0

                Use `lsp.log_levels` for reverse lookup.

                Parameters: ~
                    {level}  [number|string] the case insensitive level name
                             or number

                See also: ~
                    |vim.lsp.log_levels|

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

                Parameters `cmd` and `root_dir` are required.

                The following parameters describe fields in the {config}
                table.

                Parameters: ~
                    {root_dir}         (required, string) Directory where the
                                       LSP server will base its rootUri on
                                       initialization.
                    {cmd}              (required, string or list treated like
                                       |jobstart()|) Base command that
                                       initiates the LSP client.
                    {cmd_cwd}          (string, default=|getcwd()|) Directory
                                       to launch the `cmd` process. Not
                                       related to `root_dir` .
                    {cmd_env}          (table) Environment flags to pass to
                                       the LSP on spawn. Can be specified
                                       using keys like a map or as a list with `k=v` pairs or both. Non-string values are
                                       coerced to string. Example: >

                 { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
<
                    {capabilities}     Map overriding the default capabilities
                                       defined by
                                       |vim.lsp.protocol.make_client_capabilities()|,
                                       passed to the language server on
                                       initialization. Hint: use
                                       make_client_capabilities() and modify
                                       its result.
                                       • Note: To send an empty dictionary use
                                         `{[vim.type_idx]=vim.types.dictionary}`
                                         , else it will be encoded as an
                                         array.
                    {callbacks}        Map of language server method names to `function(err, method, params,
                                       client_id)` handler. Invoked for:
                                       • Notifications to the server, where
                                         `err` will always be `nil` .
                                       • Requests by the server. For these you
                                         can respond by returning two values:
                                         `result, err` where err must be
                                         shaped like a RPC error, i.e. `{
                                         code, message, data? }` . Use
                                         |vim.lsp.rpc_response_error()| to
                                         help with this.
                                       • Default callback for client requests
                                         not explicitly specifying a callback.
                    {init_options}     Values to pass in the initialization
                                       request as `initializationOptions` .
                                       See `initialize` in the LSP spec.
                    {name}             (string, default=client-id) Name in log
                                       messages.
                    {offset_encoding}  (default="utf-16") One of "utf-8",
                                       "utf-16", or "utf-32" which is the
                                       encoding that the LSP server expects.
                                       Client does not verify this is correct.
                    {on_error}         Callback with parameters (code, ...),
                                       invoked when the client operation
                                       throws an error. `code` is a number
                                       describing the error. Other arguments
                                       may be passed depending on the error
                                       kind. See |vim.lsp.client_errors| for
                                       possible errors. Use
                                       `vim.lsp.client_errors[code]` to get
                                       human-friendly name.
                    {before_init}      Callback with parameters
                                       (initialize_params, config) invoked
                                       before the LSP "initialize" phase,
                                       where `params` contains the parameters
                                       being sent to the server and `config`
                                       is the config that was passed to
                                       |vim.lsp.start_client()|. You can use
                                       this to modify parameters before they
                                       are sent.
                    {on_init}          Callback (client, initialize_result)
                                       invoked after LSP "initialize", where
                                       `result` is a table of `capabilities`
                                       and anything else the server may send.
                                       For example, clangd sends
                                       `initialize_result.offsetEncoding` if
                                       `capabilities.offsetEncoding` was sent
                                       to it. You can only modify the
                                       `client.offset_encoding` here before
                                       any notifications are sent.
                    {on_exit}          Callback (code, signal, client_id)
                                       invoked on client exit.
                                       • code: exit code of the process
                                       • signal: number describing the signal
                                         used to terminate (if any)
                                       • client_id: client handle
                    {on_attach}        Callback (client, bufnr) invoked when
                                       client attaches to a buffer.
                    {trace}            "off" | "messages" | "verbose" | nil
                                       passed directly to the language server
                                       in the initialize request.
                                       Invalid/empty values will default to
                                       "off"

                Return: ~
                    Client id. |vim.lsp.get_client_by_id()| Note: client is
                    only available after it has been initialized, which may
                    happen after a small delay (or never if there is an
                    error). Use `on_init` to do any actions once the client
                    has been initialized.

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

                You can also use the `stop()` function on a |vim.lsp.client|
                object. To stop all clients:
>

    vim.lsp.stop_client(vim.lsp.get_active_clients())
<

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

                Parameters: ~
                    {client_id}  client id or |vim.lsp.client| object, or list
                                 thereof
                    {force}      boolean (optional) shutdown forcefully


==============================================================================
Lua module: vim.lsp.protocol                                    *lsp-protocol*

                                 *vim.lsp.protocol.make_client_capabilities()*
make_client_capabilities()
                Gets a new ClientCapabilities object describing the LSP client
                capabilities.

                                     *vim.lsp.protocol.resolve_capabilities()*
resolve_capabilities({server_capabilities})
                `*` to match one or more characters in a path segment `?` to
                match on one character in a path segment `**` to match any
                number of path segments, including none `{}` to group
                conditions (e.g. `**​/*.{ts,js}` matches all TypeScript and
                JavaScript files) `[]` to declare a range of characters to
                match in a path segment (e.g., `example.[0-9]` to match on
                `example.0` , `example.1` , …) `[!...]` to negate a range of
                characters to match in a path segment (e.g., `example.[!0-9]`
                to match on `example.a` , `example.b` , but not `example.0` )


==============================================================================
Lua module: vim.lsp.buf                                              *lsp-buf*

clear_references()                            *vim.lsp.buf.clear_references()*
                Removes document highlights from current buffer.

code_action({context})                             *vim.lsp.buf.code_action()*
                Selects a code action from the input list that is available at
                the current cursor position.

                Parameters: ~
                    {context}  (table, optional) Valid `CodeActionContext`
                               object

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction

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

                Parameters: ~
                    {context}  (context support not yet implemented)
                               Additional information about the context in
                               which a completion was triggered (how it was
                               triggered, and by which trigger character, if
                               applicable)

                See also: ~
                    |vim.lsp.protocol.constants.CompletionTriggerKind|

declaration()                                      *vim.lsp.buf.declaration()*
                Jumps to the declaration of the symbol under the cursor.

definition()                                        *vim.lsp.buf.definition()*
                Jumps to the definition of the symbol under the cursor.

document_highlight()                        *vim.lsp.buf.document_highlight()*
                Send request to server to resolve document highlights for the
                current text document position. This request can be associated
                to key mapping or to events such as `CursorHold` , eg:
>
    vim.api.nvim_command [[autocmd CursorHold  <buffer> lua vim.lsp.buf.document_highlight()]]
    vim.api.nvim_command [[autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight()]]
    vim.api.nvim_command [[autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references()]]
<

document_symbol()                              *vim.lsp.buf.document_symbol()*
                Lists all symbols in the current buffer in the quickfix
                window.

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

                Parameters: ~
                    {command}  A valid `ExecuteCommandParams` object

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand

formatting({options})                               *vim.lsp.buf.formatting()*
                Formats the current buffer.

                Parameters: ~
                    {options}  (optional, table) Can be used to specify
                               FormattingOptions. Some unspecified options
                               will be automatically derived from the current
                               Neovim options.

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting

                                               *vim.lsp.buf.formatting_sync()*
formatting_sync({options}, {timeout_ms})
                Performs |vim.lsp.buf.formatting()| synchronously.

                Useful for running on save, to make sure buffer is formatted
                prior to being saved. {timeout_ms} is passed on to
                |vim.lsp.buf_request_sync()|. Example:
>

    vim.api.nvim_command[[autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_sync()]]
<

                Parameters: ~
                    {options}     Table with valid `FormattingOptions` entries
                    {timeout_ms}  (number) Request timeout

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

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

                                              *vim.lsp.buf.range_formatting()*
range_formatting({options}, {start_pos}, {end_pos})
                Formats a given range.

                Parameters: ~
                    {options}    Table with valid `FormattingOptions` entries.
                    {start_pos}  ({number, number}, optional) mark-indexed
                                 position. Defaults to the end of the last
                                 visual selection.

references({context})                               *vim.lsp.buf.references()*
                Lists all the references to the symbol under the cursor in the
                quickfix window.

                Parameters: ~
                    {context}  (table) Context for the request

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references

rename({new_name})                                      *vim.lsp.buf.rename()*
                Renames all references to the symbol under the cursor.

                Parameters: ~
                    {new_name}  (string) If not provided, the user will be
                                prompted for a new name using |input()|.

server_ready()                                    *vim.lsp.buf.server_ready()*
                Checks whether the language servers attached to the current
                buffer are ready.

                Return: ~
                    `true` if server responds.

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

type_definition()                              *vim.lsp.buf.type_definition()*
                Jumps to the definition of the type of the symbol under the
                cursor.

workspace_symbol({query})                     *vim.lsp.buf.workspace_symbol()*
                Lists all symbols in the current workspace in the quickfix
                window.

                The list is filtered against {query}; if the argument is
                omitted from the call, the user is prompted to enter a string
                on the command line. An empty string means no filtering is
                done.

                Parameters: ~
                    {query}  (string, optional)


==============================================================================
Lua module: vim.lsp.log                                              *lsp-log*

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

                Return: ~
                    (string) log filename

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

                Parameters: ~
                    {level}  (string or number) One of `vim.lsp.log.levels`

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

                Parameters: ~
                    {level}  number log level

                Return: ~
                    (bool) true if would log, false if not


==============================================================================
Lua module: vim.lsp.rpc                                              *lsp-rpc*

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

                Parameters: ~
                    {err}  (table) The error object

                Return: ~
                    (string) The formatted error message

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

                Parameters: ~
                    {method}  (string) The invoked LSP method
                    {params}  (table): Parameters for the invoked LSP method

                Return: ~
                    (bool) `true` if notification could be sent, `false` if
                    not

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

                Parameters: ~
                    {method}    (string) The invoked LSP method
                    {params}    (table) Parameters for the invoked LSP method
                    {callback}  (function) Callback to invoke

                Return: ~
                    (bool, number) `(true, message_id)` if request could be
                    sent, `false` if not

                                            *vim.lsp.rpc.rpc_response_error()*
rpc_response_error({code}, {message}, {data})
                Creates an RPC response object/table.

                Parameters: ~
                    {code}     RPC error code defined in
                               `vim.lsp.protocol.ErrorCodes`
                    {message}  (optional) arbitrary message to send to server
                    {data}     (optional) arbitrary data to send to server

                                                         *vim.lsp.rpc.start()*
start({cmd}, {cmd_args}, {handlers}, {extra_spawn_params})
                Starts an LSP server process and create an LSP RPC client
                object to interact with it.

                Parameters: ~
                    {cmd}                 (string) Command to start the LSP
                                          server.
                    {cmd_args}            (table) List of additional string
                                          arguments to pass to {cmd}.
                    {handlers}            (table, optional) Handlers for LSP
                                          message types. Valid handler names
                                          are:
                                          • `"notification"`
                                          • `"server_request"`
                                          • `"on_error"`
                                          • `"on_exit"`
                    {extra_spawn_params}  (table, optional) Additional context
                                          for the LSP server process. May
                                          contain:
                                          • {cwd} (string) Working directory
                                            for the LSP server process
                                          • {env} (table) Additional
                                            environment variables for LSP
                                            server process

                Return: ~
                    Client RPC object.
                    Methods:
                    • `notify()` |vim.lsp.rpc.notify()|
                    • `request()` |vim.lsp.rpc.request()|

                    Members:
                    • {pid} (number) The LSP server's PID.
                    • {handle} A handle for low-level interaction with the LSP
                      server process |vim.loop|.


==============================================================================
Lua module: vim.lsp.util                                            *lsp-util*

                                     *vim.lsp.util.apply_text_document_edit()*
apply_text_document_edit({text_document_edit})
                Parameters: ~
                    {text_document_edit}  (table) a `TextDocumentEdit` object

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit

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

                Parameters: ~
                    {text_edits}  (table) list of `TextEdit` objects
                    {buf_nr}      (number) Buffer id

                                         *vim.lsp.util.apply_workspace_edit()*
apply_workspace_edit({workspace_edit})
                Applies a `WorkspaceEdit` .

                Parameters: ~
                    {workspace_edit}  (table) `WorkspaceEdit`

buf_clear_diagnostics({bufnr})          *vim.lsp.util.buf_clear_diagnostics()*
                Clears diagnostics for a buffer.

                Parameters: ~
                    {bufnr}  (number) buffer id

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

                Parameters: ~
                    {bufnr}  buffer id

buf_diagnostics_count({kind})           *vim.lsp.util.buf_diagnostics_count()*
                Returns the number of diagnostics of given kind for current
                buffer.

                Useful for showing diagnostic counts in statusline. eg:
>

    function! LspStatus() abort
        let sl = ''
        if luaeval('not vim.tbl_isempty(vim.lsp.buf_get_clients(0))')
            let sl.='%#MyStatuslineLSP#E:'
            let sl.='%#MyStatuslineLSPErrors#%{luaeval("vim.lsp.util.buf_diagnostics_count([[Error]])")}'
            let sl.='%#MyStatuslineLSP# W:'
            let sl.='%#MyStatuslineLSPWarnings#%{luaeval("vim.lsp.util.buf_diagnostics_count([[Warning]])")}'
        else
            let sl.='%#MyStatuslineLSPErrors#off'
        endif
        return sl
    endfunction
    let &l:statusline = '%#MyStatuslineLSP#LSP '.LspStatus()
<

                Parameters: ~
                    {kind}  Diagnostic severity kind: See
                            |vim.lsp.protocol.DiagnosticSeverity|

                Return: ~
                    Count of diagnostics

                               *vim.lsp.util.buf_diagnostics_save_positions()*
buf_diagnostics_save_positions({bufnr}, {diagnostics})
                Saves diagnostics into
                vim.lsp.util.diagnostics_by_buf[{bufnr}].

                Parameters: ~
                    {bufnr}        (number) buffer id for which the
                                   diagnostics are for
                    {diagnostics}  list of `Diagnostic` s received from the
                                   LSP server

                                        *vim.lsp.util.buf_diagnostics_signs()*
buf_diagnostics_signs({bufnr}, {diagnostics})
                Places signs for each diagnostic in the sign column.

                Sign characters can be customized with the following commands:
>
    sign define LspDiagnosticsErrorSign text=E texthl=LspDiagnosticsError linehl= numhl=
    sign define LspDiagnosticsWarningSign text=W texthl=LspDiagnosticsWarning linehl= numhl=
    sign define LspDiagnosticsInformationSign text=I texthl=LspDiagnosticsInformation linehl= numhl=
    sign define LspDiagnosticsHintSign text=H texthl=LspDiagnosticsHint linehl= numhl=
<

                                    *vim.lsp.util.buf_diagnostics_underline()*
buf_diagnostics_underline({bufnr}, {diagnostics})
                Highlights a list of diagnostics in a buffer by underlining
                them.

                Parameters: ~
                    {bufnr}        (number) buffer id
                    {diagnostics}  (list of `Diagnostic` s)

                                 *vim.lsp.util.buf_diagnostics_virtual_text()*
buf_diagnostics_virtual_text({bufnr}, {diagnostics})
                Given a list of diagnostics, sets the corresponding virtual
                text for a buffer.

                Parameters: ~
                    {bufnr}        buffer id
                    {diagnostics}  (table) list of `Diagnostic` s

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

                Parameters: ~
                    {bufnr}       buffer id
                    {references}  List of `DocumentHighlight` objects to
                                  highlight

character_offset({buf}, {row}, {col})        *vim.lsp.util.character_offset()*
                Returns the UTF-32 and UTF-16 offsets for a position in a
                certain buffer.

                Parameters: ~
                    {buf}  buffer id (0 for current)
                    {row}  0-indexed line
                    {col}  0-indexed byte offset in line

                Return: ~
                    (number, number) UTF-32 and UTF-16 index of the character
                    in line {row} column {col} in buffer {buf}

                                        *vim.lsp.util.close_preview_autocmd()*
close_preview_autocmd({events}, {winnr})
                Creates autocommands to close a preview window when events
                happen.

                Parameters: ~
                    {events}  (table) list of events
                    {winnr}   (number) window id of preview window

                See also: ~
                    |autocmd-events|

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

                Parameters: ~
                    {input}     ( `MarkedString` | `MarkedString[]` |
                                `MarkupContent` )
                    {contents}  (table, optional, default `{}` ) List of
                                strings to extend with converted lines

                Return: ~
                    {contents}, extended with lines of converted markdown.

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover

                     *vim.lsp.util.convert_signature_help_to_markdown_lines()*
convert_signature_help_to_markdown_lines({signature_help})
                Converts `textDocument/SignatureHelp` response to markdown
                lines.

                Parameters: ~
                    {signature_help}  Response of `textDocument/SignatureHelp`

                Return: ~
                    list of lines of converted markdown.

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp

                                    *vim.lsp.util.diagnostics_group_by_line()*
diagnostics_group_by_line({diagnostics})
                Groups a list of diagnostics by line.

                Parameters: ~
                    {diagnostics}  (table) list of `Diagnostic` s

                Return: ~
                    (table) dictionary mapping lines to lists of diagnostics
                    valid on those lines

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnostic

                                     *vim.lsp.util.extract_completion_items()*
extract_completion_items({result})
                Can be used to extract the completion items from a `textDocument/completion` request, which may return one of `CompletionItem[]` , `CompletionList` or null.

                Parameters: ~
                    {result}  (table) The result of a
                              `textDocument/completion` request

                Return: ~
                    (table) List of completion items

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specification#textDocument_completion

                                      *vim.lsp.util.fancy_floating_markdown()*
fancy_floating_markdown({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. The result is shown
                in a floating preview.

                Parameters: ~
                    {contents}  table of lines to show in window
                    {opts}      dictionary with optional fields

                Return: ~
                    width,height size of float

focusable_float({unique_name}, {fn})          *vim.lsp.util.focusable_float()*
                Parameters: ~
                    {unique_name}  (string) Window variable
                    {fn}           (function) should return create a new
                                   window and return a tuple of
                                   ({focusable_buffer_id}, {window_id}). if
                                   {focusable_buffer_id} is a valid buffer id,
                                   the newly created window will be the new
                                   focus associated with the current buffer
                                   via the tag `unique_name` .

                Return: ~
                    (pbufnr, pwinnr) if `fn()` has created a new window; nil
                    otherwise

                                            *vim.lsp.util.focusable_preview()*
focusable_preview({unique_name}, {fn})
                Focuses/unfocuses the floating preview window associated with
                the current buffer via the window variable `unique_name` . If
                no such preview window exists, makes a new one.

                Parameters: ~
                    {unique_name}  (string) Window variable
                    {fn}           (function) The return values of this
                                   function will be passed directly to
                                   |vim.lsp.util.open_floating_preview()|, in
                                   the case that a new floating window should
                                   be created

get_effective_tabstop({bufnr})          *vim.lsp.util.get_effective_tabstop()*
                Returns visual width of tabstop.

                Parameters: ~
                    {bufnr}  (optional, number): Buffer handle, defaults to
                             current

                Return: ~
                    (number) tabstop visual width

                See also: ~
                    |softtabstop|

get_line_diagnostics()                   *vim.lsp.util.get_line_diagnostics()*
                Gets list of diagnostics for the current line.

                Return: ~
                    (table) list of `Diagnostic` tables

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnostic

                                  *vim.lsp.util.get_severity_highlight_name()*
get_severity_highlight_name({severity})
                Gets the name of a severity's highlight group.

                Parameters: ~
                    {severity}  A member of
                                `vim.lsp.protocol.DiagnosticSeverity`

                Return: ~
                    (string) Highlight group name

jump_to_location({location})                 *vim.lsp.util.jump_to_location()*
                Jumps to a location.

                Parameters: ~
                    {location}  ( `Location` | `LocationLink` )

                Return: ~
                    `true` if the jump succeeded

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

                Parameters: ~
                    {locations}  (table) list of `Location` s or
                                 `LocationLink` s

                Return: ~
                    (table) list of items

                                  *vim.lsp.util.make_floating_popup_options()*
make_floating_popup_options({width}, {height}, {opts})
                Creates a table with sensible default options for a floating
                window. The table can be passed to |nvim_open_win()|.

                Parameters: ~
                    {width}   (number) window width (in character cells)
                    {height}  (number) window height (in character cells)
                    {opts}    (table, optional)

                Return: ~
                    (table) Options

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

                Parameters: ~
                    {options}  Table with valid `FormattingOptions` entries

                Return: ~
                    `FormattingOptions object

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting

make_position_params()                   *vim.lsp.util.make_position_params()*
                Creates a `TextDocumentPositionParams` object for the current
                buffer and cursor position.

                Return: ~
                    `TextDocumentPositionParams` object

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams

make_range_params()                         *vim.lsp.util.make_range_params()*
                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` .

                Return: ~
                    { textDocument = { uri = `current_file_uri` }, range = {
                    start = `current_position` , end = `current_position` } }

make_text_document_params()         *vim.lsp.util.make_text_document_params()*
                Creates a `TextDocumentIdentifier` object for the current
                buffer.

                Return: ~
                    `TextDocumentIdentifier`

                See also: ~
                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier

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

                Parameters: ~
                    {contents}  table of lines to show in window
                    {filetype}  string of filetype to set for opened buffer
                    {opts}      dictionary with optional fields

                Return: ~
                    bufnr,winnr buffer and window number of the newly created
                    floating preview window

parse_snippet({input})                          *vim.lsp.util.parse_snippet()*
                Parses snippets in a completion entry.

                Parameters: ~
                    {input}  (string) unparsed snippet

                Return: ~
                    (string) parsed snippet

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

                behavior depends on type of location:
                • for Location, range is shown (e.g., function definition)
                • for LocationLink, targetRange is shown (e.g., body of
                  function definition)

                Parameters: ~
                    {location}  a single `Location` or `LocationLink`

                Return: ~
                    (bufnr,winnr) buffer and window number of floating window
                    or nil

set_lines({lines}, {A}, {B}, {new_lines})           *vim.lsp.util.set_lines()*
                Replaces text in a range with new text.

                CAUTION: Changes in-place!

                Parameters: ~
                    {lines}      (table) Original list of strings
                    {A}          (table) Start position; a 2-tuple of {line,
                                 col} numbers
                    {B}          (table) End position; a 2-tuple of {line,
                                 col} numbers
                    {new_lines}  A list of strings to replace the original

                Return: ~
                    (table) The modified {lines} object

set_loclist({items})                              *vim.lsp.util.set_loclist()*
                Fills current window's location list with given list of items.
                Can be obtained with e.g. |vim.lsp.util.locations_to_items()|.

                Parameters: ~
                    {items}  (table) list of items

set_qflist({items})                                *vim.lsp.util.set_qflist()*
                Fills quickfix list with given list of items. Can be obtained
                with e.g. |vim.lsp.util.locations_to_items()|.

                Parameters: ~
                    {items}  (table) list of items

show_line_diagnostics()                 *vim.lsp.util.show_line_diagnostics()*
                Displays the diagnostics for the current line in a floating
                hover window.

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

                Parameters: ~
                    {symbols}  DocumentSymbol[] or SymbolInformation[]

              *vim.lsp.util.text_document_completion_list_to_complete_items()*
text_document_completion_list_to_complete_items({result}, {prefix})
                Turns the result of a `textDocument/completion` request into
                vim-compatible |complete-items|.

                Parameters: ~
                    {result}  The result of a `textDocument/completion` call,
                              e.g. from |vim.lsp.buf.completion()|, which may
                              be one of `CompletionItem[]` , `CompletionList`
                              or `null`
                    {prefix}  (string) the prefix to filter the completion
                              items

                Return: ~
                    { matches = complete-items table, incomplete = bool }

                See also: ~
                    |complete-items|

trim_empty_lines({lines})                    *vim.lsp.util.trim_empty_lines()*
                Removes empty lines from the beginning and end.

                Parameters: ~
                    {lines}  (table) list of lines to trim

                Return: ~
                    (table) trimmed list of lines

                                *vim.lsp.util.try_trim_markdown_code_blocks()*
try_trim_markdown_code_blocks({lines})
                Accepts markdown lines and tries to reduce them to a filetype
                if they comprise just a single code block.

                CAUTION: Modifies the input in-place!

                Parameters: ~
                    {lines}  (table) list of lines

                Return: ~
                    (string) filetype or 'markdown' if it was unchanged.

 vim:tw=78:ts=8:ft=help:norl: