diff options
Diffstat (limited to 'runtime/doc/lsp.txt')
| -rw-r--r-- | runtime/doc/lsp.txt | 876 |
1 files changed, 541 insertions, 335 deletions
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index b934d2dfa0..33d65406a1 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -4,7 +4,7 @@ NVIM REFERENCE MANUAL -LSP client/framework *lsp* +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 @@ -23,14 +23,14 @@ 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-lsp plugin. It provides common configuration for + 1. Install the nvim-lspconfig plugin. It provides common configuration for various servers so you can get started quickly. - https://github.com/neovim/nvim-lsp + 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-lsp README for details. + relevant config. See the nvim-lspconfig README for details. To check LSP clients attached to the current buffer: > @@ -39,9 +39,10 @@ To check LSP clients attached to the current buffer: > *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. Example config: > +go-to-definition, hover, etc. Full list of features in |vim.lsp.buf|. + +Example config: > - nnoremap <silent> gd <cmd>lua vim.lsp.buf.declaration()<CR> 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> @@ -50,6 +51,9 @@ go-to-definition, hover, etc. Example config: > 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 @@ -353,9 +357,6 @@ buf_get_clients({bufnr}) *vim.lsp.buf_get_clients()* {bufnr} (optional, number): Buffer handle, or 0 for current -buf_get_full_text({bufnr}) *vim.lsp.buf_get_full_text()* - TODO: Documentation - buf_is_attached({bufnr}, {client_id}) *vim.lsp.buf_is_attached()* Checks if a buffer is attached for a particular client. @@ -416,71 +417,69 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) error, returns `(nil, err)` where `err` is a string describing the failure reason. -cancel_request({id}) *vim.lsp.cancel_request()* - TODO: Documentation - client() *vim.lsp.client* - LSP client object. + 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]) Send a request to the - server. If callback is not specified, it will use + • 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. This is a thin - wrapper around {client.rpc.request} with some additional - checking. Returns a boolean to indicate if the - notification was successful. If it is false, then it will - always be false (the client has shutdown). If it was - successful, then it will return the request id as the - second result. You can use this with `notify("$/cancel", { - id = request_id })` to cancel the request. This helper is - made automatically with |vim.lsp.buf_request()| Returns: - status, [client_id] - • notify(method, params) This is just {client.rpc.notify}() - Returns a boolean to indicate if the notification was - successful. If it is false, then it will always be false - (the client has shutdown). Returns: status - • cancel_request(id) This is just - {client.rpc.notify}("$/cancelRequest", { id = id }) - Returns the same as `notify()` . - • stop([force]) Stop a client, optionally with force. By + 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() Returns true if the client is fully stopped. + • 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 + • {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. - • offset_encoding (string): The encoding used for + • {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 - `on_init` method before text is sent to the server. - • callbacks (table): The callbacks used by the client as + `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 + • {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 + • {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()* - TODO: Documentation + Checks whether a client is stopped. - *vim.lsp.define_default_sign()* -define_default_sign({name}, {properties}) - TODO: Documentation - -err_message({...}) *vim.lsp.err_message()* - TODO: Documentation + Parameters: ~ + {client_id} (Number) - *vim.lsp.for_each_buffer_client()* -for_each_buffer_client({bufnr}, {callback}) - TODO: Documentation + Return: ~ + true if client is stopped, false otherwise. get_active_clients() *vim.lsp.get_active_clients()* Gets all active clients. @@ -489,8 +488,8 @@ get_active_clients() *vim.lsp.get_active_clients()* 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. + Gets a client by id, or nil if the id is invalid. + The returned client may not yet be fully initialized. Parameters: ~ {client_id} client id number @@ -499,25 +498,10 @@ get_client_by_id({client_id}) *vim.lsp.get_client_by_id()* |vim.lsp.client| object, or nil get_log_path() *vim.lsp.get_log_path()* - TODO: Documentation - -initialize() *vim.lsp.initialize()* - TODO: Documentation - -is_dir({filename}) *vim.lsp.is_dir()* - TODO: Documentation - -is_stopped() *vim.lsp.is_stopped()* - TODO: Documentation + Gets the path of the logfile used by the LSP client. -next_client_id() *vim.lsp.next_client_id()* - TODO: Documentation - -notification({method}, {params}) *vim.lsp.notification()* - TODO: Documentation - -notify({...}) *vim.lsp.notify()* - TODO: Documentation + Return: ~ + (String) Path to logfile. omnifunc({findstart}, {base}) *vim.lsp.omnifunc()* Implements 'omnifunc' compatible LSP completion. @@ -538,30 +522,6 @@ omnifunc({findstart}, {base}) *vim.lsp.omnifunc()* |complete-items| |CompleteDone| -on_error({code}, {err}) *vim.lsp.on_error()* - TODO: Documentation - -on_exit({code}, {signal}) *vim.lsp.on_exit()* - TODO: Documentation - -once({fn}) *vim.lsp.once()* - TODO: Documentation - -optional_validator({fn}) *vim.lsp.optional_validator()* - TODO: Documentation - -request({method}, {params}, {callback}, {bufnr}) *vim.lsp.request()* - TODO: Documentation - -resolve_bufnr({bufnr}) *vim.lsp.resolve_bufnr()* - TODO: Documentation - -resolve_callback({method}) *vim.lsp.resolve_callback()* - TODO: Documentation - -server_request({method}, {params}) *vim.lsp.server_request()* - TODO: Documentation - set_log_level({level}) *vim.lsp.set_log_level()* Sets the global log level for LSP logging. @@ -582,6 +542,9 @@ start_client({config}) *vim.lsp.start_client()* 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 @@ -612,13 +575,13 @@ start_client({config}) *vim.lsp.start_client()* array. {callbacks} Map of language server method names to `function(err, method, params, client_id)` handler. Invoked for: - • Notifications from the server, where + • Notifications to the server, where `err` will always be `nil` . - • Requests initiated 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 + • 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 @@ -647,8 +610,9 @@ start_client({config}) *vim.lsp.start_client()* where `params` contains the parameters being sent to the server and `config` is the config that was passed to - `start_client()` . You can use this to - modify parameters before they are sent. + |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` @@ -680,9 +644,6 @@ start_client({config}) *vim.lsp.start_client()* error). Use `on_init` to do any actions once the client has been initialized. -stop({force}) *vim.lsp.stop()* - TODO: Documentation - stop_client({client_id}, {force}) *vim.lsp.stop_client()* Stops a client(s). @@ -690,7 +651,7 @@ stop_client({client_id}, {force}) *vim.lsp.stop_client()* object. To stop all clients: > - vim.lsp.stop_client(lsp.get_active_clients()) + vim.lsp.stop_client(vim.lsp.get_active_clients()) < By default asks the server to shutdown, unless stop was @@ -702,26 +663,10 @@ stop_client({client_id}, {force}) *vim.lsp.stop_client()* thereof {force} boolean (optional) shutdown forcefully - *vim.lsp.text_document_did_open_handler()* -text_document_did_open_handler({bufnr}, {client}) - TODO: Documentation - -unsupported_method({method}) *vim.lsp.unsupported_method()* - TODO: Documentation - -validate_client_config({config}) *vim.lsp.validate_client_config()* - TODO: Documentation - -validate_encoding({encoding}) *vim.lsp.validate_encoding()* - TODO: Documentation - ============================================================================== Lua module: vim.lsp.protocol *lsp-protocol* -ifnil({a}, {b}) *vim.lsp.protocol.ifnil()* - TODO: Documentation - *vim.lsp.protocol.make_client_capabilities()* make_client_capabilities() Gets a new ClientCapabilities object describing the LSP client @@ -739,28 +684,38 @@ resolve_capabilities({server_capabilities}) characters to match in a path segment (e.g., `example.[!0-9]` to match on `example.a` , `example.b` , but not `example.0` ) - *vim.lsp.protocol.transform_schema_comments()* -transform_schema_comments() - TODO: Documentation - - *vim.lsp.protocol.transform_schema_to_table()* -transform_schema_to_table() - TODO: Documentation - ============================================================================== Lua module: vim.lsp.buf *lsp-buf* clear_references() *vim.lsp.buf.clear_references()* - TODO: Documentation + Removes document highlights from current buffer. code_action({context}) *vim.lsp.buf.code_action()* - TODO: Documentation + 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. @@ -782,22 +737,41 @@ document_symbol() *vim.lsp.buf.document_symbol()* window. execute_command({command}) *vim.lsp.buf.execute_command()* - TODO: Documentation + 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. - The optional {options} table can be used to specify - FormattingOptions, a list of which is available at https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting . Some unspecified options will be automatically derived from - the current Neovim options. + 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}) - Perform |vim.lsp.buf.formatting()| synchronously. + 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()|. + |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 @@ -808,29 +782,61 @@ implementation() *vim.lsp.buf.implementation()* Lists all the implementations for the symbol under the cursor in the quickfix window. -npcall({fn}, {...}) *vim.lsp.buf.npcall()* - TODO: Documentation +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_code_action()* +range_code_action({context}, {start_pos}, {end_pos}) + Performs |vim.lsp.buf.code_action()| for a given range. -ok_or_nil({status}, {...}) *vim.lsp.buf.ok_or_nil()* - TODO: Documentation + Parameters: ~ + {context} (table, optional) Valid `CodeActionContext` + object + {start_pos} ({number, number}, optional) mark-indexed + position. Defaults to the start of the last + visual selection. + {end_pos} ({number, number}, optional) mark-indexed + position. Defaults to the end of the last + visual selection. *vim.lsp.buf.range_formatting()* range_formatting({options}, {start_pos}, {end_pos}) - TODO: Documentation + 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. If - {new_name} is not provided, the user will be prompted for a - new name using |input()|. + Renames all references to the symbol under the cursor. -request({method}, {params}, {callback}) *vim.lsp.buf.request()* - TODO: Documentation + 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. @@ -846,115 +852,75 @@ workspace_symbol({query}) *vim.lsp.buf.workspace_symbol()* Lists all symbols in the current workspace in the quickfix window. - The list is filtered against the optional argument {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. - -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|. - - -============================================================================== -Lua module: vim.lsp.callbacks *lsp-callbacks* - -err_message({...}) *vim.lsp.callbacks.err_message()* - TODO: Documentation + 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. - *vim.lsp.callbacks.location_callback()* -location_callback({_}, {method}, {result}) - TODO: Documentation + Parameters: ~ + {query} (string, optional) ============================================================================== Lua module: vim.lsp.log *lsp-log* get_filename() *vim.lsp.log.get_filename()* - TODO: Documentation + Returns the log filename. -path_join({...}) *vim.lsp.log.path_join()* - TODO: Documentation + Return: ~ + (string) log filename set_level({level}) *vim.lsp.log.set_level()* - TODO: Documentation - -should_log({level}) *vim.lsp.log.should_log()* - TODO: Documentation - - -============================================================================== -Lua module: vim.lsp.rpc *lsp-rpc* - -convert_NIL({v}) *vim.lsp.rpc.convert_NIL()* - TODO: Documentation + Sets the current log level. - *vim.lsp.rpc.create_and_start_client()* -create_and_start_client({cmd}, {cmd_args}, {handlers}, - {extra_spawn_params}) - TODO: Documentation + Parameters: ~ + {level} (string or number) One of `vim.lsp.log.levels` -encode_and_send({payload}) *vim.lsp.rpc.encode_and_send()* - TODO: Documentation +should_log({level}) *vim.lsp.log.should_log()* + Checks whether the level is sufficient for logging. -env_merge({env}) *vim.lsp.rpc.env_merge()* - Merges current process env with the given env and returns the - result as a list of "k=v" strings. -> + Parameters: ~ + {level} number log level - Example: -< + Return: ~ + (bool) true if would log, false if not - > in: { PRODUCTION="false", PATH="/usr/bin/", PORT=123, HOST="0.0.0.0", } - out: { "PRODUCTION=false", "PATH=/usr/bin/", "PORT=123", "HOST=0.0.0.0", } -< - *vim.lsp.rpc.format_message_with_content_length()* -format_message_with_content_length({encoded_message}) - TODO: Documentation +============================================================================== +Lua module: vim.lsp.rpc *lsp-rpc* format_rpc_error({err}) *vim.lsp.rpc.format_rpc_error()* - TODO: Documentation - -handle_body({body}) *vim.lsp.rpc.handle_body()* - TODO: Documentation - -is_dir({filename}) *vim.lsp.rpc.is_dir()* - TODO: Documentation - -json_decode({data}) *vim.lsp.rpc.json_decode()* - TODO: Documentation + Constructs an error message from an LSP error object. -json_encode({data}) *vim.lsp.rpc.json_encode()* - TODO: Documentation + Parameters: ~ + {err} (table) The error object -notification({method}, {params}) *vim.lsp.rpc.notification()* - TODO: Documentation + Return: ~ + (string) The formatted error message -on_error({errkind}, {...}) *vim.lsp.rpc.on_error()* - TODO: Documentation +notify({method}, {params}) *vim.lsp.rpc.notify()* + Sends a notification to the LSP server. -on_exit({code}, {signal}) *vim.lsp.rpc.on_exit()* - TODO: Documentation + Parameters: ~ + {method} (string) The invoked LSP method + {params} (table): Parameters for the invoked LSP method -onexit({code}, {signal}) *vim.lsp.rpc.onexit()* - TODO: Documentation + Return: ~ + (bool) `true` if notification could be sent, `false` if + not -parse_headers({header}) *vim.lsp.rpc.parse_headers()* - TODO: Documentation +request({method}, {params}, {callback}) *vim.lsp.rpc.request()* + Sends a request to the LSP server and runs {callback} upon + response. - *vim.lsp.rpc.pcall_handler()* -pcall_handler({errkind}, {status}, {head}, {...}) - TODO: Documentation + Parameters: ~ + {method} (string) The invoked LSP method + {params} (table) Parameters for the invoked LSP method + {callback} (function) Callback to invoke -request_parser_loop() *vim.lsp.rpc.request_parser_loop()* - TODO: Documentation + 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}) @@ -966,48 +932,81 @@ rpc_response_error({code}, {message}, {data}) {message} (optional) arbitrary message to send to server {data} (optional) arbitrary data to send to server -send_notification({method}, {params}) *vim.lsp.rpc.send_notification()* - TODO: Documentation - - *vim.lsp.rpc.send_request()* -send_request({method}, {params}, {callback}) - TODO: Documentation + *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. - *vim.lsp.rpc.send_response()* -send_response({request_id}, {err}, {result}) - TODO: Documentation + 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 -server_request({method}, {params}) *vim.lsp.rpc.server_request()* - TODO: Documentation + Return: ~ + Client RPC object. + Methods: + • `notify()` |vim.lsp.rpc.notify()| + • `request()` |vim.lsp.rpc.request()| -try_call({errkind}, {fn}, {...}) *vim.lsp.rpc.try_call()* - TODO: Documentation + 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_syntax_to_region()* -apply_syntax_to_region({ft}, {start}, {finish}) - TODO: Documentation - *vim.lsp.util.apply_text_document_edit()* apply_text_document_edit({text_document_edit}) - TODO: Documentation + 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}) - TODO: Documentation + 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}) - TODO: Documentation + Applies a `WorkspaceEdit` . + + Parameters: ~ + {workspace_edit} (table) `WorkspaceEdit` buf_clear_diagnostics({bufnr}) *vim.lsp.util.buf_clear_diagnostics()* - TODO: Documentation + Clears diagnostics for a buffer. + + Parameters: ~ + {bufnr} (number) buffer id buf_clear_references({bufnr}) *vim.lsp.util.buf_clear_references()* - TODO: Documentation + 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 @@ -1040,16 +1039,18 @@ buf_diagnostics_count({kind}) *vim.lsp.util.buf_diagnostics_count()* *vim.lsp.util.buf_diagnostics_save_positions()* buf_diagnostics_save_positions({bufnr}, {diagnostics}) - Saves the diagnostics (Diagnostic[]) into diagnostics_by_buf + Saves diagnostics into + vim.lsp.util.diagnostics_by_buf[{bufnr}]. Parameters: ~ - {bufnr} bufnr for which the diagnostics are for. - {diagnostics} Diagnostics[] received from the language - server. + {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}) - Place signs for each diagnostic in the sign column. + Places signs for each diagnostic in the sign column. Sign characters can be customized with the following commands: > @@ -1061,47 +1062,125 @@ buf_diagnostics_signs({bufnr}, {diagnostics}) *vim.lsp.util.buf_diagnostics_underline()* buf_diagnostics_underline({bufnr}, {diagnostics}) - TODO: Documentation + 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}) - TODO: Documentation + 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}) - TODO: Documentation + 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()* - TODO: Documentation + 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}) - TODO: Documentation + 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}) - TODO: Documentation + 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}) - TODO: Documentation + 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}) - TODO: Documentation + 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}) - TODO: Documentation + 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}) - Convert markdown into syntax highlighted regions by stripping + 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 TODO: refactor to separate - stripping/converting and make use of open_floating_preview + in a floating preview. Parameters: ~ {contents} table of lines to show in window @@ -1110,25 +1189,37 @@ fancy_floating_markdown({contents}, {opts}) Return: ~ width,height size of float -find_window_by_var({name}, {value}) *vim.lsp.util.find_window_by_var()* - TODO: Documentation - focusable_float({unique_name}, {fn}) *vim.lsp.util.focusable_float()* - TODO: Documentation + 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}) - TODO: Documentation + 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. -get_completion_word({item}) *vim.lsp.util.get_completion_word()* - TODO: Documentation - - *vim.lsp.util.get_current_line_to_cursor()* -get_current_line_to_cursor() - TODO: Documentation + 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()* - Get visual width of tabstop. + Returns visual width of tabstop. Parameters: ~ {bufnr} (optional, number): Buffer handle, defaults to @@ -1140,52 +1231,125 @@ get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()* See also: ~ |softtabstop| - *vim.lsp.util.get_line_byte_from_position()* -get_line_byte_from_position({bufnr}, {position}) - TODO: Documentation - get_line_diagnostics() *vim.lsp.util.get_line_diagnostics()* - TODO: Documentation + 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}) - TODO: Documentation + 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()* - TODO: Documentation + Jumps to a location. + + Parameters: ~ + {location} ( `Location` | `LocationLink` ) + + Return: ~ + `true` if the jump succeeded locations_to_items({locations}) *vim.lsp.util.locations_to_items()* - TODO: Documentation + 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}) - TODO: Documentation + 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}) - TODO: Documentation + 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 + + *vim.lsp.util.make_given_range_params()* +make_given_range_params({start_pos}, {end_pos}) + Using the given range in the current buffer, creates an object + that is similar to |vim.lsp.util.make_range_params()|. -make_position_param() *vim.lsp.util.make_position_param()* - TODO: Documentation + Parameters: ~ + {start_pos} ({number, number}, optional) mark-indexed + position. Defaults to the start of the last + visual selection. + {end_pos} ({number, number}, optional) mark-indexed + position. Defaults to the end of the last + visual selection. + + Return: ~ + { textDocument = { uri = `current_file_uri` }, range = { + start = `start_position` , end = `end_position` } } make_position_params() *vim.lsp.util.make_position_params()* - TODO: Documentation + 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()* - TODO: Documentation + 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()* - TODO: Documentation + Creates a `TextDocumentIdentifier` object for the current + buffer. -npcall({fn}, {...}) *vim.lsp.util.npcall()* - TODO: Documentation + Return: ~ + `TextDocumentIdentifier` -ok_or_nil({status}, {...}) *vim.lsp.util.ok_or_nil()* - TODO: Documentation + 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}) - Show contents in a floating window + Shows contents in a floating window. Parameters: ~ {contents} table of lines to show in window @@ -1193,17 +1357,20 @@ open_floating_preview({contents}, {filetype}, {opts}) {opts} dictionary with optional fields Return: ~ - bufnr,winnr buffer and window number of floating window or - nil + bufnr,winnr buffer and window number of the newly created + floating preview window parse_snippet({input}) *vim.lsp.util.parse_snippet()* - TODO: Documentation + Parses snippets in a completion entry. -parse_snippet_rec({input}, {inner}) *vim.lsp.util.parse_snippet_rec()* - TODO: Documentation + Parameters: ~ + {input} (string) unparsed snippet + + Return: ~ + (string) parsed snippet preview_location({location}) *vim.lsp.util.preview_location()* - Preview a location in a floating windows + Previews a location in a floating window behavior depends on type of location: • for Location, range is shown (e.g., function definition) @@ -1211,52 +1378,91 @@ preview_location({location}) *vim.lsp.util.preview_location()* function definition) Parameters: ~ - {location} a single Location or LocationLink + {location} a single `Location` or `LocationLink` Return: ~ - bufnr,winnr buffer and window number of floating window or - nil - - *vim.lsp.util.remove_unmatch_completion_items()* -remove_unmatch_completion_items({items}, {prefix}) - TODO: Documentation + (bufnr,winnr) buffer and window number of floating window + or nil set_lines({lines}, {A}, {B}, {new_lines}) *vim.lsp.util.set_lines()* - TODO: Documentation + Replaces text in a range with new text. -set_loclist({items}) *vim.lsp.util.set_loclist()* - TODO: Documentation + CAUTION: Changes in-place! -set_qflist({items}) *vim.lsp.util.set_qflist()* - TODO: Documentation + 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 -show_line_diagnostics() *vim.lsp.util.show_line_diagnostics()* - TODO: Documentation + Return: ~ + (table) The modified {lines} object -sort_by_key({fn}) *vim.lsp.util.sort_by_key()* - TODO: Documentation +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()|. -sort_completion_items({items}) *vim.lsp.util.sort_completion_items()* - TODO: Documentation + Parameters: ~ + {items} (table) list of items -split_lines({value}) *vim.lsp.util.split_lines()* - TODO: Documentation +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()* - Convert symbols to quickfix list 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}) - TODO: Documentation + 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()* - TODO: Documentation + 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}) - TODO: Documentation + 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: |