mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-06 03:18:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: make Lua docstrings consistent #15255

Browse Source 
The official developer documentation in in :h dev-lua-doc specifies to
use "--@" for special/magic tokens. However, this format is not
consistent with EmmyLua notation (used by some Lua language servers) nor
with the C version of the magic docstring tokens which use three comment
characters.

Further, the code base is currently split between usage of "--@",
"---@", and "--- @". In an effort to remain consistent, change all Lua
magic tokens to use "---@" and update the developer documentation
accordingly.
This commit is contained in:
Gregory Anders
2021-08-22 14:55:28 -06:00
committed by GitHub
parent 649dbb3b15
commit c2a211b8e3
24 changed files with 689 additions and 687 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
runtime/doc/develop.txt
View File

@@ -191,8 +191,8 @@ definitions. The |lua-vim| :help is generated from the docstrings.
Docstring format:
- Lines in the main description start with `---`
- Special tokens start with `--@` followed by the token name:
`--@see`, `--@param`, `--@returns`
- Special tokens start with `---@` followed by the token name:
`---@see`, `---@param`, `---@returns`
- Limited markdown is supported.
- List-items start with `-` (useful to nest or "indent")
- Use `<pre>` for code samples.
@@ -211,11 +211,11 @@ vim.paste in src/nvim/lua/vim.lua like this: >
--- end)()
--- </pre>
---
--@see |paste|
---@see |paste|
---
--@param lines ...
--@param phase ...
--@returns false if client should cancel the paste.
---@param lines ...
---@param phase ...
---@returns false if client should cancel the paste.
LUA *dev-lua*

22
runtime/doc/lsp.txt
View File

@@ -1510,11 +1510,6 @@ reset({client_id}, {buffer_client_map}) *vim.lsp.diagnostic.reset()*
{buffer_client_map} table map of buffers to active
clients
*vim.lsp.diagnostic.restore_extmarks()*
restore_extmarks({bufnr}, {last})
Parameters: ~
{last} number last line that was changed
save({diagnostics}, {bufnr}, {client_id}) *vim.lsp.diagnostic.save()*
Save diagnostics to the current buffer.
@@ -1526,10 +1521,6 @@ save({diagnostics}, {bufnr}, {client_id}) *vim.lsp.diagnostic.save()*
{bufnr} number
{client_id} number
*vim.lsp.diagnostic.save_extmarks()*
save_extmarks({bufnr}, {client_id})
TODO: Documentation
set_loclist({opts}) *vim.lsp.diagnostic.set_loclist()*
Sets the location list
@@ -1966,7 +1957,9 @@ diagnostics_to_items({diagnostics_by_bufnr}, {predicate})
Parameters: ~
{diagnostics_by_bufnr} table bufnr -> Diagnostic []
{predicate} an optional function to filter the
diagnostics.
diagnostics. If present, only
diagnostic items matching will be
included.
Return: ~
table (A list of items)
@@ -1999,6 +1992,8 @@ get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()*
|softtabstop|
get_line({uri}, {row}) *vim.lsp.util.get_line()*
Gets the zero-indexed line from the given uri.
Parameters: ~
{uri} string uri of the resource to get the line from
{row} number zero-indexed line number
@@ -2007,6 +2002,8 @@ get_line({uri}, {row}) *vim.lsp.util.get_line()*
string the line at row in filename
get_lines({uri}, {rows}) *vim.lsp.util.get_lines()*
Gets the zero-indexed lines from the given uri.
Parameters: ~
{uri} string uri of the resource to get the lines from
{rows} number[] zero-indexed line numbers
@@ -2014,9 +2011,6 @@ get_lines({uri}, {rows}) *vim.lsp.util.get_lines()*
Return: ~
table<number string> a table mapping rows to lines
get_markdown_fences() *vim.lsp.util.get_markdown_fences()*
TODO: Documentation
get_progress_messages() *vim.lsp.util.get_progress_messages()*
TODO: Documentation
@@ -2197,6 +2191,8 @@ preview_location({location}, {opts}) *vim.lsp.util.preview_location()*
or nil
rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()*
Rename old_fname to new_fname
Parameters: ~
{opts} (table)

7
runtime/doc/lua.txt
View File

@@ -1177,7 +1177,9 @@ make_dict_accessor({scope}) *vim.make_dict_accessor()*
TODO: Documentation
notify({msg}, {log_level}, {_opts}) *vim.notify()*
Notification provider without a runtime, writes to :Messages
Notification provider
Without a runtime, writes to :Messages
Parameters: ~
{msg} Content of the notification to show to the
@@ -1186,6 +1188,9 @@ notify({msg}, {log_level}, {_opts}) *vim.notify()*
{opts} Dictionary with optional options (timeout,
etc)
See also: ~
:help nvim_notify
paste({lines}, {phase}) *vim.paste()*
Paste handler, invoked by |nvim_paste()| when a conforming UI
(such as the |TUI|) pastes text into the editor.

4
runtime/lua/vim/F.lua
View File

@@ -2,8 +2,8 @@ local F = {}
--- Returns {a} if it is not nil, otherwise returns {b}.
---
--@param a
--@param b
---@param a
---@param b
function F.if_nil(a, b)
if a == nil then return b end
return a

14
runtime/lua/vim/highlight.lua
View File

@@ -2,7 +2,7 @@ local api = vim.api
local highlight = {}
--@private
---@private
function highlight.create(higroup, hi_info, default)
local options = {}
-- TODO: Add validation
@@ -12,7 +12,7 @@ function highlight.create(higroup, hi_info, default)
vim.cmd(string.format([[highlight %s %s %s]], default and "default" or "", higroup, table.concat(options, " ")))
end
--@private
---@private
function highlight.link(higroup, link_to, force)
vim.cmd(string.format([[highlight%s link %s %s]], force and "!" or " default", higroup, link_to))
end
@@ -20,11 +20,11 @@ end
--- Highlight range between two positions
---
--@param bufnr number of buffer to apply highlighting to
--@param ns namespace to add highlight to
--@param higroup highlight group to use for highlighting
--@param rtype type of range (:help setreg, default charwise)
--@param inclusive boolean indicating whether the range is end-inclusive (default false)
---@param bufnr number of buffer to apply highlighting to
---@param ns namespace to add highlight to
---@param higroup highlight group to use for highlighting
---@param rtype type of range (:help setreg, default charwise)
---@param inclusive boolean indicating whether the range is end-inclusive (default false)
function highlight.range(bufnr, ns, higroup, start, finish, rtype, inclusive)
rtype = rtype or 'v'
inclusive = inclusive or false

296
runtime/lua/vim/lsp.lua
View File

@@ -55,21 +55,21 @@ lsp._request_name_to_capability = {
-- TODO improve handling of scratch buffers with LSP attached.
--@private
---@private
--- Concatenates and writes a list of strings to the Vim error buffer.
---
--@param {...} (List of strings) List to write to the buffer
---@param {...} (List of strings) List to write to the buffer
local function err_message(...)
nvim_err_writeln(table.concat(vim.tbl_flatten{...}))
nvim_command("redraw")
end
--@private
---@private
--- Returns the buffer number for the given {bufnr}.
---
--@param bufnr (number) Buffer number to resolve. Defaults to the current
---@param bufnr (number) Buffer number to resolve. Defaults to the current
---buffer if not given.
--@returns bufnr (number) Number of requested buffer
---@returns bufnr (number) Number of requested buffer
local function resolve_bufnr(bufnr)
validate { bufnr = { bufnr, 'n', true } }
if bufnr == nil or bufnr == 0 then
@@ -78,21 +78,21 @@ local function resolve_bufnr(bufnr)
return bufnr
end
--@private
---@private
--- Called by the client when trying to call a method that's not
--- supported in any of the servers registered for the current buffer.
--@param method (string) name of the method
---@param method (string) name of the method
function lsp._unsupported_method(method)
local msg = string.format("method %s is not supported by any of the servers registered for the current buffer", method)
log.warn(msg)
return lsp.rpc_response_error(protocol.ErrorCodes.MethodNotFound, msg)
end
--@private
---@private
--- Checks whether a given path is a directory.
---
--@param filename (string) path to check
--@returns true if {filename} exists and is a directory, false otherwise
---@param filename (string) path to check
---@returns true if {filename} exists and is a directory, false otherwise
local function is_dir(filename)
validate{filename={filename,'s'}}
local stat = uv.fs_stat(filename)
@@ -108,10 +108,10 @@ local valid_encodings = {
}
local client_index = 0
--@private
---@private
--- Returns a new, unused client id.
---
--@returns (number) client id
---@returns (number) client id
local function next_client_id()
client_index = client_index + 1
return client_index
@@ -124,11 +124,11 @@ local uninitialized_clients = {}
-- Tracks all buffers attached to a client.
local all_client_active_buffers = {}
--@private
---@private
--- Invokes a function for each LSP client attached to the buffer {bufnr}.
---
--@param bufnr (Number) of buffer
--@param fn (function({client}, {client_id}, {bufnr}) Function to run on
---@param bufnr (Number) of buffer
---@param fn (function({client}, {client_id}, {bufnr}) Function to run on
---each client attached to that buffer.
local function for_each_buffer_client(bufnr, fn)
validate {
@@ -154,11 +154,11 @@ lsp.client_errors = tbl_extend("error", lsp_rpc.client_errors, vim.tbl_add_rever
ON_INIT_CALLBACK_ERROR = table.maxn(lsp_rpc.client_errors) + 1;
})
--@private
---@private
--- Normalizes {encoding} to valid LSP encoding names.
---
--@param encoding (string) Encoding to normalize
--@returns (string) normalized encoding name
---@param encoding (string) Encoding to normalize
---@returns (string) normalized encoding name
local function validate_encoding(encoding)
validate {
encoding = { encoding, 's' };
@@ -167,13 +167,13 @@ local function validate_encoding(encoding)
or error(string.format("Invalid offset encoding %q. Must be one of: 'utf-8', 'utf-16', 'utf-32'", encoding))
end
--@internal
---@internal
--- Parses a command invocation into the command itself and its args. If there
--- are no arguments, an empty table is returned as the second argument.
---
--@param input (List)
--@returns (string) the command
--@returns (list of strings) its arguments
---@param input (List)
---@returns (string) the command
---@returns (list of strings) its arguments
function lsp._cmd_parts(input)
vim.validate{cmd={
input,
@@ -192,12 +192,12 @@ function lsp._cmd_parts(input)
return cmd, cmd_args
end
--@private
---@private
--- Augments a validator function with support for optional (nil) values.
---
--@param fn (function(v)) The original validator function; should return a
---@param fn (function(v)) The original validator function; should return a
---bool.
--@returns (function(v)) The augmented function. Also returns true if {v} is
---@returns (function(v)) The augmented function. Also returns true if {v} is
---`nil`.
local function optional_validator(fn)
return function(v)
@@ -205,14 +205,14 @@ local function optional_validator(fn)
end
end
--@private
---@private
--- Validates a client configuration as given to |vim.lsp.start_client()|.
---
--@param config (table)
--@returns (table) "Cleaned" config, containing only the command, its
---@param config (table)
---@returns (table) "Cleaned" config, containing only the command, its
---arguments, and a valid encoding.
---
--@see |vim.lsp.start_client()|
---@see |vim.lsp.start_client()|
local function validate_client_config(config)
validate {
config = { config, 't' };
@@ -253,11 +253,11 @@ local function validate_client_config(config)
}
end
--@private
---@private
--- Returns full text of buffer {bufnr} as a string.
---
--@param bufnr (number) Buffer handle, or 0 for current.
--@returns Buffer text as string.
---@param bufnr (number) Buffer handle, or 0 for current.
---@returns Buffer text as string.
local function buf_get_full_text(bufnr)
local text = table.concat(nvim_buf_get_lines(bufnr, 0, -1, true), '\n')
if nvim_buf_get_option(bufnr, 'eol') then
@@ -266,14 +266,14 @@ local function buf_get_full_text(bufnr)
return text
end
--@private
---@private
--- Memoizes a function. On first run, the function return value is saved and
--- immediately returned on subsequent runs. If the function returns a multival,
--- only the first returned value will be memoized and returned. The function will only be run once,
--- even if it has side-effects.
---
--@param fn (function) Function to run
--@returns (function) Memoized function
---@param fn (function) Function to run
---@returns (function) Memoized function
local function once(fn)
local value
local ran = false
@@ -426,11 +426,11 @@ do
end
--@private
---@private
--- Default handler for the 'textDocument/didOpen' LSP notification.
---
--@param bufnr (Number) Number of the buffer, or 0 for current
--@param client Client object
---@param bufnr (Number) Number of the buffer, or 0 for current
---@param client Client object
local function text_document_did_open_handler(bufnr, client)
changetracking.init(client, bufnr)
if not client.resolved_capabilities.text_document_open_close then
@@ -548,16 +548,16 @@ end
---
--- The following parameters describe fields in the {config} table.
---
--@param root_dir: (string) Directory where the LSP server will base
---@param root_dir: (string) Directory where the LSP server will base
--- its rootUri on initialization.
---
--@param cmd: (required, string or list treated like |jobstart()|) Base command
---@param cmd: (required, string or list treated like |jobstart()|) Base command
--- that initiates the LSP client.
---
--@param cmd_cwd: (string, default=|getcwd()|) Directory to launch
---@param cmd_cwd: (string, default=|getcwd()|) Directory to launch
--- the `cmd` process. Not related to `root_dir`.
---
--@param cmd_env: (table) Environment flags to pass to the LSP on
---@param 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:
@@ -565,7 +565,7 @@ end
--- { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
--- </pre>
---
--@param capabilities Map overriding the default capabilities defined by
---@param 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.
@@ -573,41 +573,41 @@ end
--- `{[vim.type_idx]=vim.types.dictionary}`, else it will be encoded as an
--- array.
---
--@param handlers Map of language server method names to |lsp-handler|
---@param handlers Map of language server method names to |lsp-handler|
---
--@param settings Map with language server specific settings. These are
---@param settings Map with language server specific settings. These are
--- returned to the language server if requested via `workspace/configuration`.
--- Keys are case-sensitive.
---
--@param init_options Values to pass in the initialization request
---@param init_options Values to pass in the initialization request
--- as `initializationOptions`. See `initialize` in the LSP spec.
---
--@param name (string, default=client-id) Name in log messages.
---@param name (string, default=client-id) Name in log messages.
--
--@param workspace_folders (table) List of workspace folders passed to the
---@param workspace_folders (table) List of workspace folders passed to the
--- language server. Defaults to root_dir if not set. See `workspaceFolders` in
--- the LSP spec
---
--@param get_language_id function(bufnr, filetype) -> language ID as string.
---@param get_language_id function(bufnr, filetype) -> language ID as string.
--- Defaults to the filetype.
---
--@param offset_encoding (default="utf-16") One of "utf-8", "utf-16",
---@param 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.
---
--@param on_error Callback with parameters (code, ...), invoked
---@param 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.
---
--@param before_init Callback with parameters (initialize_params, config)
---@param 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.
---
--@param on_init Callback (client, initialize_result) invoked after LSP
---@param 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
@@ -617,24 +617,24 @@ end
--- `workspace/didChangeConfiguration` notification should be sent
--- to the server during on_init.
---
--@param on_exit Callback (code, signal, client_id) invoked on client
---@param 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
---
--@param on_attach Callback (client, bufnr) invoked when client
---@param on_attach Callback (client, bufnr) invoked when client
--- attaches to a buffer.
---
--@param trace: "off" | "messages" | "verbose" | nil passed directly to the language
---@param trace: "off" | "messages" | "verbose" | nil passed directly to the language
--- server in the initialize request. Invalid/empty values will default to "off"
--@param flags: A table with flags for the client. The current (experimental) flags are:
---@param flags: A table with flags for the client. The current (experimental) flags are:
--- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits
--- - debounce_text_changes (number, default nil): Debounce didChange
--- notifications to the server by the given number in milliseconds. No debounce
--- occurs if nil
---
--@returns Client id. |vim.lsp.get_client_by_id()| Note: client may not be
---@returns Client id. |vim.lsp.get_client_by_id()| Note: client may not be
--- fully initialized. Use `on_init` to do any actions once
--- the client has been initialized.
function lsp.start_client(config)
@@ -657,22 +657,22 @@ function lsp.start_client(config)
local dispatch = {}
--@private
---@private
--- Returns the handler associated with an LSP method.
--- Returns the default handler if the user hasn't set a custom one.
---
--@param method (string) LSP method name
--@returns (fn) The handler for the given method, if defined, or the default from |vim.lsp.handlers|
---@param method (string) LSP method name
---@returns (fn) The handler for the given method, if defined, or the default from |vim.lsp.handlers|
local function resolve_handler(method)
return handlers[method] or default_handlers[method]
end
--@private
---@private
--- Handles a notification sent by an LSP server by invoking the
--- corresponding handler.
---
--@param method (string) LSP method name
--@param params (table) The parameters for that method.
---@param method (string) LSP method name
---@param params (table) The parameters for that method.
function dispatch.notification(method, params)
local _ = log.debug() and log.debug('notification', method, params)
local handler = resolve_handler(method)
@@ -682,11 +682,11 @@ function lsp.start_client(config)
end
end
--@private
---@private
--- Handles a request from an LSP server by invoking the corresponding handler.
---
--@param method (string) LSP method name
--@param params (table) The parameters for that method
---@param method (string) LSP method name
---@param params (table) The parameters for that method
function dispatch.server_request(method, params)
local _ = log.debug() and log.debug('server_request', method, params)
local handler = resolve_handler(method)
@@ -698,12 +698,12 @@ function lsp.start_client(config)
return nil, lsp.rpc_response_error(protocol.ErrorCodes.MethodNotFound)
end
--@private
---@private
--- Invoked when the client operation throws an error.
---
--@param code (number) Error code
--@param err (...) Other arguments may be passed depending on the error kind
--@see |vim.lsp.client_errors| for possible errors. Use
---@param code (number) Error code
---@param err (...) 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 a human-friendly name.
function dispatch.on_error(code, err)
local _ = log.error() and log.error(log_prefix, "on_error", { code = lsp.client_errors[code], err = err })
@@ -717,11 +717,11 @@ function lsp.start_client(config)
end
end
--@private
---@private
--- Invoked on client exit.
---
--@param code (number) exit code of the process
--@param signal (number) the signal used to terminate (if any)
---@param code (number) exit code of the process
---@param signal (number) the signal used to terminate (if any)
function dispatch.on_exit(code, signal)
active_clients[client_id] = nil
uninitialized_clients[client_id] = nil
@@ -766,7 +766,7 @@ function lsp.start_client(config)
-- Store the uninitialized_clients for cleanup in case we exit before initialize finishes.
uninitialized_clients[client_id] = client;
--@private
---@private
local function initialize()
local valid_traces = {
off = 'off'; messages = 'messages'; verbose = 'verbose';
@@ -869,23 +869,23 @@ function lsp.start_client(config)
end)
end
--@private
---@private
--- Sends a request to the server.
---
--- This is a thin wrapper around {client.rpc.request} with some additional
--- checks for capabilities and handler availability.
---
--@param method (string) LSP method name.
--@param params (table) LSP request params.
--@param handler (function, optional) Response |lsp-handler| for this method.
--@param bufnr (number) Buffer handle (0 for current).
--@returns ({status}, [request_id]): {status} is a bool indicating
---@param method (string) LSP method name.
---@param params (table) LSP request params.
---@param handler (function, optional) Response |lsp-handler| for this method.
---@param bufnr (number) Buffer handle (0 for current).
---@returns ({status}, [request_id]): {status} is a bool indicating
---whether the request was successful. If it is `false`, then it will
---always be `false` (the client has shutdown). If it was
---successful, then it will return {request_id} as the
---second result. You can use this with `client.cancel_request(request_id)`
---to cancel the-request.
--@see |vim.lsp.buf_request()|
---@see |vim.lsp.buf_request()|
function client.request(method, params, handler, bufnr)
if not handler then
handler = resolve_handler(method)
@@ -900,21 +900,21 @@ function lsp.start_client(config)
end)
end
--@private
---@private
--- Sends a request to the server and synchronously waits for the response.
---
--- This is a wrapper around {client.request}
---
--@param method (string) LSP method name.
--@param params (table) LSP request params.
--@param timeout_ms (number, optional, default=1000) Maximum time in
---@param method (string) LSP method name.
---@param params (table) LSP request params.
---@param timeout_ms (number, optional, default=1000) Maximum time in
---milliseconds to wait for a result.
--@param bufnr (number) Buffer handle (0 for current).
--@returns { err=err, result=result }, a dictionary, where `err` and `result` come from the |lsp-handler|.
---@param bufnr (number) Buffer handle (0 for current).
---@returns { err=err, result=result }, a dictionary, where `err` and `result` come from the |lsp-handler|.
---On timeout, cancel or error, returns `(nil, err)` where `err` is a
---string describing the failure reason. If the request was unsuccessful
---returns `nil`.
--@see |vim.lsp.buf_request_sync()|
---@see |vim.lsp.buf_request_sync()|
function client.request_sync(method, params, timeout_ms, bufnr)
local request_result = nil
local function _sync_handler(err, _, result)
@@ -936,25 +936,25 @@ function lsp.start_client(config)
return request_result
end
--@private
---@private
--- Sends a notification to an LSP server.
---
--@param method (string) LSP method name.
--@param params (optional, table) LSP request params.
--@param bufnr (number) Buffer handle, or 0 for current.
--@returns {status} (bool) true if the notification was successful.
---@param method (string) LSP method name.
---@param params (optional, table) LSP request params.
---@param bufnr (number) Buffer handle, or 0 for current.
---@returns {status} (bool) true if the notification was successful.
---If it is false, then it will always be false
---(the client has shutdown).
function client.notify(...)
return rpc.notify(...)
end
--@private
---@private
--- Cancels a request with a given request id.
---
--@param id (number) id of request to cancel
--@returns true if any client returns true; false otherwise
--@see |vim.lsp.client.notify()|
---@param id (number) id of request to cancel
---@returns true if any client returns true; false otherwise
---@see |vim.lsp.client.notify()|
function client.cancel_request(id)
validate{id = {id, 'n'}}
return rpc.notify("$/cancelRequest", { id = id })
@@ -963,14 +963,14 @@ function lsp.start_client(config)
-- Track this so that we can escalate automatically if we've alredy tried a
-- graceful shutdown
local graceful_shutdown_failed = false
--@private
---@private
--- 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.
---
--@param force (bool, optional)
---@param force (bool, optional)
function client.stop(force)
lsp.diagnostic.reset(client_id, all_buffer_active_clients)
@@ -1000,18 +1000,18 @@ function lsp.start_client(config)
end)
end
--@private
---@private
--- Checks whether a client is stopped.
---
--@returns (bool) true if client is stopped or in the process of being
---@returns (bool) true if client is stopped or in the process of being
---stopped; false otherwise
function client.is_stopped()
return rpc.handle:is_closing()
end
--@private
---@private
--- Runs the on_attach function from the client's config if it was defined.
--@param bufnr (number) Buffer number
---@param bufnr (number) Buffer number
function client._on_attach(bufnr)
text_document_did_open_handler(bufnr, client)
if config.on_attach then
@@ -1025,8 +1025,8 @@ function lsp.start_client(config)
return client_id
end
--@private
--@fn text_document_did_change_handler(_, bufnr, changedtick, firstline, lastline, new_lastline, old_byte_size, old_utf32_size, old_utf16_size)
---@private
---@fn text_document_did_change_handler(_, bufnr, changedtick, firstline, lastline, new_lastline, old_byte_size, old_utf32_size, old_utf16_size)
--- Notify all attached clients that a buffer has changed.
local text_document_did_change_handler
do
@@ -1076,8 +1076,8 @@ end
---
--- Without calling this, the server won't be notified of changes to a buffer.
---
--- @param bufnr (number) Buffer handle, or 0 for current
--- @param client_id (number) Client id
---@param bufnr (number) Buffer handle, or 0 for current
---@param client_id (number) Client id
function lsp.buf_attach_client(bufnr, client_id)
validate {
bufnr = {bufnr, 'n', true};
@@ -1158,17 +1158,17 @@ end
--- Gets a client by id, or nil if the id is invalid.
--- The returned client may not yet be fully initialized.
--
--@param client_id client id number
---@param client_id client id number
---
--@returns |vim.lsp.client| object, or nil
---@returns |vim.lsp.client| object, or nil
function lsp.get_client_by_id(client_id)
return active_clients[client_id] or uninitialized_clients[client_id]
end
--- Returns list of buffers attached to client_id.
--
--@param client_id client id
--@returns list of buffer ids
---@param client_id client id
---@returns list of buffer ids
function lsp.get_buffers_by_client_id(client_id)
local active_client_buffers = all_client_active_buffers[client_id]
if active_client_buffers then
@@ -1190,8 +1190,8 @@ end
--- By default asks the server to shutdown, unless stop was requested
--- already for this client, then force-shutdown is attempted.
---
--@param client_id client id or |vim.lsp.client| object, or list thereof
--@param force boolean (optional) shutdown forcefully
---@param client_id client id or |vim.lsp.client| object, or list thereof
---@param force boolean (optional) shutdown forcefully
function lsp.stop_client(client_id, force)
local ids = type(client_id) == 'table' and client_id or {client_id}
for _, id in ipairs(ids) do
@@ -1207,7 +1207,7 @@ end
--- Gets all active clients.
---
--@returns Table of |vim.lsp.client| objects
---@returns Table of |vim.lsp.client| objects
function lsp.get_active_clients()
return vim.tbl_values(active_clients)
end
@@ -1238,13 +1238,13 @@ nvim_command("autocmd VimLeavePre * lua vim.lsp._vim_exit_handler()")
--- Sends an async request for all active clients attached to the
--- buffer.
---
--@param bufnr (number) Buffer handle, or 0 for current.
--@param method (string) LSP method name
--@param params (optional, table) Parameters to send to the server
--@param handler (optional, function) See |lsp-handler|
---@param bufnr (number) Buffer handle, or 0 for current.
---@param method (string) LSP method name
---@param params (optional, table) Parameters to send to the server
---@param handler (optional, function) See |lsp-handler|
-- If nil, follows resolution strategy defined in |lsp-handler-configuration|
--
--@returns 2-tuple:
---@returns 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.
@@ -1296,14 +1296,14 @@ end
---Parameters are the same as |vim.lsp.buf_request()| but the return result and callback are
---different.
---
--@param bufnr (number) Buffer handle, or 0 for current.
--@param method (string) LSP method name
--@param params (optional, table) Parameters to send to the server
--@param callback (function) The callback to call when all requests are finished.
---@param bufnr (number) Buffer handle, or 0 for current.
---@param method (string) LSP method name
---@param params (optional, table) Parameters to send to the server
---@param callback (function) The callback to call when all requests are finished.
-- Unlike `buf_request`, this will collect all the responses from each server instead of handling them.
-- A map of client_id:request_result will be provided to the callback
--
--@returns (function) A function that will cancel all requests which is the same as the one returned from `buf_request`.
---@returns (function) A function that will cancel all requests which is the same as the one returned from `buf_request`.
function lsp.buf_request_all(bufnr, method, params, callback)
local request_results = {}
local result_count = 0
@@ -1337,13 +1337,13 @@ end
--- Parameters are the same as |vim.lsp.buf_request()| but the return result is
--- different. Wait maximum of {timeout_ms} (default 1000) ms.
---
--@param bufnr (number) Buffer handle, or 0 for current.
--@param method (string) LSP method name
--@param params (optional, table) Parameters to send to the server
--@param timeout_ms (optional, number, default=1000) Maximum time in
---@param bufnr (number) Buffer handle, or 0 for current.
---@param method (string) LSP method name
---@param params (optional, table) Parameters to send to the server
---@param timeout_ms (optional, number, default=1000) Maximum time in
--- milliseconds to wait for a result.
---
--@returns Map of client_id:request_result. On timeout, cancel or error,
---@returns Map of client_id:request_result. On timeout, cancel or error,
--- returns `(nil, err)` where `err` is a string describing the failure
--- reason.
function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
@@ -1366,11 +1366,11 @@ function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
end
--- Send a notification to a server
--@param bufnr [number] (optional): The number of the buffer
--@param method [string]: Name of the request method
--@param params [string]: Arguments to send to the server
---@param bufnr [number] (optional): The number of the buffer
---@param method [string]: Name of the request method
---@param params [string]: Arguments to send to the server
---
--@returns true if any client returns true; false otherwise
---@returns true if any client returns true; false otherwise
function lsp.buf_notify(bufnr, method, params)
validate {
bufnr = { bufnr, 'n', true };
@@ -1385,14 +1385,14 @@ end
--- Implements 'omnifunc' compatible LSP completion.
---
--@see |complete-functions|
--@see |complete-items|
--@see |CompleteDone|
---@see |complete-functions|
---@see |complete-items|
---@see |CompleteDone|
---
--@param findstart 0 or 1, decides behavior
--@param base If findstart=0, text to match against
---@param findstart 0 or 1, decides behavior
---@param base If findstart=0, text to match against
---
--@returns (number) Decided by `findstart`:
---@returns (number) Decided by `findstart`:
--- - findstart=0: column where the completion starts, or -2 or -3
--- - findstart=1: list of matches (actually just calls |complete()|)
function lsp.omnifunc(findstart, base)
@@ -1438,8 +1438,8 @@ end
---Checks whether a client is stopped.
---
--@param client_id (Number)
--@returns true if client is stopped, false otherwise.
---@param client_id (Number)
---@returns true if client is stopped, false otherwise.
function lsp.client_is_stopped(client_id)
return active_clients[client_id] == nil
end
@@ -1447,7 +1447,7 @@ end
--- Gets a map of client_id:client pairs for the given buffer, where each value
--- is a |vim.lsp.client| object.
---
--@param bufnr (optional, number): Buffer handle, or 0 for current
---@param bufnr (optional, number): Buffer handle, or 0 for current
function lsp.buf_get_clients(bufnr)
bufnr = resolve_bufnr(bufnr)
local result = {}
@@ -1472,9 +1472,9 @@ lsp.log_levels = log.levels
---
--- Use `lsp.log_levels` for reverse lookup.
---
--@see |vim.lsp.log_levels|
---@see |vim.lsp.log_levels|
---
--@param level [number|string] the case insensitive level name or number
---@param level [number|string] the case insensitive level name or number
function lsp.set_log_level(level)
if type(level) == 'string' or type(level) == 'number' then
log.set_level(level)
@@ -1484,7 +1484,7 @@ function lsp.set_log_level(level)
end
--- Gets the path of the logfile used by the LSP client.
--@returns (String) Path to logfile.
---@returns (String) Path to logfile.
function lsp.get_log_path()
return log.get_filename()
end
@@ -1495,8 +1495,8 @@ function lsp.for_each_buffer_client(bufnr, fn)
end
--- Function to manage overriding defaults for LSP handlers.
--@param handler (function) See |lsp-handler|
--@param override_config (table) Table containing the keys to override behavior of the {handler}
---@param handler (function) See |lsp-handler|
---@param override_config (table) Table containing the keys to override behavior of the {handler}
function lsp.with(handler, override_config)
return function(err, method, params, client_id, bufnr, config)
return handler(err, method, params, client_id, bufnr, vim.tbl_deep_extend("force", config or {}, override_config))

86
runtime/lua/vim/lsp/buf.lua
View File

@@ -5,7 +5,7 @@ local util = require 'vim.lsp.util'
local M = {}
--@private
---@private
--- Returns nil if {status} is false or nil, otherwise returns the rest of the
--- arguments.
local function ok_or_nil(status, ...)
@@ -13,31 +13,31 @@ local function ok_or_nil(status, ...)
return ...
end
--@private
---@private
--- Swallows errors.
---
--@param fn Function to run
--@param ... Function arguments
--@returns Result of `fn(...)` if there are no errors, otherwise nil.
---@param fn Function to run
---@param ... Function arguments
---@returns Result of `fn(...)` if there are no errors, otherwise nil.
--- Returns nil if errors occur during {fn}, otherwise returns
local function npcall(fn, ...)
return ok_or_nil(pcall(fn, ...))
end
--@private
---@private
--- Sends an async request to all active clients attached to the current
--- buffer.
---
--@param method (string) LSP method name
--@param params (optional, table) Parameters to send to the server
--@param handler (optional, functionnil) See |lsp-handler|. Follows |lsp-handler-resolution|
---@param method (string) LSP method name
---@param params (optional, table) Parameters to send to the server
---@param handler (optional, functionnil) See |lsp-handler|. Follows |lsp-handler-resolution|
--
--@returns 2-tuple:
---@returns 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.
---
--@see |vim.lsp.buf_request()|
---@see |vim.lsp.buf_request()|
local function request(method, params, handler)
validate {
method = {method, 's'};
@@ -49,7 +49,7 @@ end
--- Checks whether the language servers attached to the current buffer are
--- ready.
---
--@returns `true` if server responds.
---@returns `true` if server responds.
function M.server_ready()
return not not vim.lsp.buf_notify(0, "window/progress", {})
end
@@ -62,7 +62,7 @@ function M.hover()
end
--- Jumps to the declaration of the symbol under the cursor.
--@note Many servers do not implement this method. Generally, see |vim.lsp.buf.definition()| instead.
---@note Many servers do not implement this method. Generally, see |vim.lsp.buf.definition()| instead.
---
function M.declaration()
local params = util.make_position_params()
@@ -100,22 +100,22 @@ end
--- Retrieves the completion items at the current cursor position. Can only be
--- called in Insert mode.
---
--@param context (context support not yet implemented) Additional information
---@param 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 |vim.lsp.protocol.constants.CompletionTriggerKind|
---@see |vim.lsp.protocol.constants.CompletionTriggerKind|
function M.completion(context)
local params = util.make_position_params()
params.context = context
return request('textDocument/completion', params)
end
--@private
---@private
--- If there is more than one client that supports the given method,
--- asks the user to select one.
--
--@returns The client that the user selected or nil
---@returns The client that the user selected or nil
local function select_client(method)
local clients = vim.tbl_values(vim.lsp.buf_get_clients());
clients = vim.tbl_filter(function (client)
@@ -146,11 +146,11 @@ end
--- Formats the current buffer.
---
--@param options (optional, table) Can be used to specify FormattingOptions.
---@param options (optional, table) Can be used to specify FormattingOptions.
--- Some unspecified options will be automatically derived from the current
--- Neovim options.
--
--@see https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting
---@see https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting
function M.formatting(options)
local client = select_client("textDocument/formatting")
if client == nil then return end
@@ -168,9 +168,9 @@ end
--- vim.api.nvim_command[[autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_sync()]]
--- </pre>
---
--@param options Table with valid `FormattingOptions` entries
--@param timeout_ms (number) Request timeout
--@see |vim.lsp.buf.formatting_seq_sync|
---@param options Table with valid `FormattingOptions` entries
---@param timeout_ms (number) Request timeout
---@see |vim.lsp.buf.formatting_seq_sync|
function M.formatting_sync(options, timeout_ms)
local client = select_client("textDocument/formatting")
if client == nil then return end
@@ -195,9 +195,9 @@ end
--- vim.api.nvim_command[[autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_seq_sync()]]
--- </pre>
---
--@param options (optional, table) `FormattingOptions` entries
--@param timeout_ms (optional, number) Request timeout
--@param order (optional, table) List of client names. Formatting is requested from clients
---@param options (optional, table) `FormattingOptions` entries
---@param timeout_ms (optional, number) Request timeout
---@param order (optional, table) List of client names. Formatting is requested from clients
---in the following order: first all clients that are not in the `order` list, then
---the remaining clients in the order as they occur in the `order` list.
function M.formatting_seq_sync(options, timeout_ms, order)
@@ -230,10 +230,10 @@ end
--- Formats a given range.
---
--@param options Table with valid `FormattingOptions` entries.
--@param start_pos ({number, number}, optional) mark-indexed position.
---@param options Table with valid `FormattingOptions` entries.
---@param start_pos ({number, number}, optional) mark-indexed position.
---Defaults to the start of the last visual selection.
--@param end_pos ({number, number}, optional) mark-indexed position.
---@param end_pos ({number, number}, optional) mark-indexed position.
---Defaults to the end of the last visual selection.
function M.range_formatting(options, start_pos, end_pos)
local client = select_client("textDocument/rangeFormatting")
@@ -246,7 +246,7 @@ end
--- Renames all references to the symbol under the cursor.
---
--@param new_name (string) If not provided, the user will be prompted for a new
---@param new_name (string) If not provided, the user will be prompted for a new
---name using |input()|.
function M.rename(new_name)
-- TODO(ashkan) use prepareRename
@@ -260,8 +260,8 @@ end
--- Lists all the references to the symbol under the cursor in the quickfix window.
---
--@param context (table) Context for the request
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
---@param context (table) Context for the request
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
function M.references(context)
validate { context = { context, 't', true } }
local params = util.make_position_params()
@@ -279,7 +279,7 @@ function M.document_symbol()
request('textDocument/documentSymbol', params)
end
--@private
---@private
local function pick_call_hierarchy_item(call_hierarchy_items)
if not call_hierarchy_items then return end
if #call_hierarchy_items == 1 then
@@ -297,7 +297,7 @@ local function pick_call_hierarchy_item(call_hierarchy_items)
return choice
end
--@private
---@private
local function call_hierarchy(method)
local params = util.make_position_params()
request('textDocument/prepareCallHierarchy', params, function(err, _, result)
@@ -389,7 +389,7 @@ end
--- call, the user is prompted to enter a string on the command line. An empty
--- string means no filtering is done.
---
--@param query (string, optional)
---@param query (string, optional)
function M.workspace_symbol(query)
query = query or npcall(vfn.input, "Query: ")
local params = {query = query}
@@ -424,7 +424,7 @@ end
--- Requests code actions from all clients and calls the handler exactly once
--- with all aggregated results
--@private
---@private
local function code_action_request(params)
local bufnr = vim.api.nvim_get_current_buf()
local method = 'textDocument/codeAction'
@@ -439,9 +439,9 @@ end
--- Selects a code action from the input list that is available at the current
--- cursor position.
--
--@param context: (table, optional) Valid `CodeActionContext` object
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
---
---@param context: (table, optional) Valid `CodeActionContext` object
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
function M.code_action(context)
validate { context = { context, 't', true } }
context = context or { diagnostics = vim.lsp.diagnostic.get_line_diagnostics() }
@@ -452,10 +452,10 @@ end
--- Performs |vim.lsp.buf.code_action()| for a given range.
---
--@param context: (table, optional) Valid `CodeActionContext` object
--@param start_pos ({number, number}, optional) mark-indexed position.
---@param context: (table, optional) Valid `CodeActionContext` object
---@param start_pos ({number, number}, optional) mark-indexed position.
---Defaults to the start of the last visual selection.
--@param end_pos ({number, number}, optional) mark-indexed position.
---@param end_pos ({number, number}, optional) mark-indexed position.
---Defaults to the end of the last visual selection.
function M.range_code_action(context, start_pos, end_pos)
validate { context = { context, 't', true } }
@@ -467,8 +467,8 @@ end
--- Executes an LSP server command.
---
--@param command A valid `ExecuteCommandParams` object
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
---@param command A valid `ExecuteCommandParams` object
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
function M.execute_command(command)
validate {
command = { command.command, 's' },

8
runtime/lua/vim/lsp/codelens.lua
View File

@@ -22,11 +22,11 @@ local namespaces = setmetatable({}, {
end;
})
--@private
---@private
M.__namespaces = namespaces
--@private
---@private
local function execute_lens(lens, bufnr, client_id)
local line = lens.range.start.line
api.nvim_buf_clear_namespace(bufnr, namespaces[client_id], line, line + 1)
@@ -151,7 +151,7 @@ function M.save(lenses, bufnr, client_id)
end
--@private
---@private
local function resolve_lenses(lenses, bufnr, client_id, callback)
lenses = lenses or {}
local num_lens = vim.tbl_count(lenses)
@@ -160,7 +160,7 @@ local function resolve_lenses(lenses, bufnr, client_id, callback)
return
end
--@private
---@private
local function countdown()
num_lens = num_lens - 1
if num_lens == 0 then

70
runtime/lua/vim/lsp/diagnostic.lua
View File

@@ -8,7 +8,7 @@ local util = require('vim.lsp.util')
local if_nil = vim.F.if_nil
--@class DiagnosticSeverity
---@class DiagnosticSeverity
local DiagnosticSeverity = protocol.DiagnosticSeverity
local to_severity = function(severity)
@@ -46,14 +46,14 @@ end
---@brief lsp-diagnostic
---
--@class Diagnostic
--@field range Range
--@field message string
--@field severity DiagnosticSeverity|nil
--@field code number | string
--@field source string
--@field tags DiagnosticTag[]
--@field relatedInformation DiagnosticRelatedInformation[]
---@class Diagnostic
---@field range Range
---@field message string
---@field severity DiagnosticSeverity|nil
---@field code number | string
---@field source string
---@field tags DiagnosticTag[]
---@field relatedInformation DiagnosticRelatedInformation[]
local M = {}
@@ -167,12 +167,12 @@ end
local _diagnostic_namespaces = _make_namespace_table("vim_lsp_diagnostics", true)
local _sign_namespaces = _make_namespace_table("vim_lsp_signs", false)
--@private
---@private
function M._get_diagnostic_namespace(client_id)
return _diagnostic_namespaces[client_id]
end
--@private
---@private
function M._get_sign_namespace(client_id)
return _sign_namespaces[client_id]
end
@@ -255,7 +255,7 @@ local _diagnostic_counts = function(diagnostics)
return counts
end
--@private
---@private
--- Set the different diagnostic cache after `textDocument/publishDiagnostics`
---@param diagnostics Diagnostic[]
---@param bufnr number
@@ -291,7 +291,7 @@ local function set_diagnostic_cache(diagnostics, bufnr, client_id)
end
--@private
---@private
--- Clear the cached diagnostics
---@param bufnr number
---@param client_id number
@@ -512,7 +512,7 @@ local _next_diagnostic = function(position, search_forward, bufnr, opts, client_
end
end
--@private
---@private
--- Helper function to return a position from a diagnostic
---
---@return table {row, col}
@@ -527,7 +527,7 @@ local function _diagnostic_pos(opts, diagnostic)
return to_position(diagnostic.range.start, bufnr)
end
--@private
---@private
-- Move to the diagnostic position
local function _diagnostic_move_pos(name, opts, pos)
opts = opts or {}
@@ -858,7 +858,7 @@ end
--- Callback scheduled for after leaving insert mode
---
--- Used to handle
--@private
---@private
function M._execute_scheduled_display(bufnr, client_id)
local args = _bufs_waiting_to_update[bufnr][client_id]
if not args then
@@ -924,20 +924,20 @@ end
-- Diagnostic Private Highlight Utilies {{{
--- Get the severity highlight name
--@private
---@private
function M._get_severity_highlight_name(severity)
return virtual_text_highlight_map[severity]
end
--- Get floating severity highlight name
--@private
---@private
function M._get_floating_severity_highlight_name(severity)
return floating_highlight_map[severity]
end
--- This should be called to update the highlights for the LSP client.
function M._define_default_signs_and_highlights()
--@private
---@private
local function define_default_sign(name, properties)
if vim.tbl_isempty(vim.fn.sign_getdefined(name)) then
vim.fn.sign_define(name, properties)
@@ -1054,8 +1054,8 @@ function M.on_publish_diagnostics(_, _, params, client_id, _, config)
end
-- restores the extmarks set by M.display
--- @param last number last line that was changed
-- @private
---@param last number last line that was changed
---@private
local function restore_extmarks(bufnr, last)
for client_id, extmarks in pairs(diagnostic_cache_extmarks[bufnr]) do
local ns = M._get_diagnostic_namespace(client_id)
@@ -1084,7 +1084,7 @@ local function restore_extmarks(bufnr, last)
end
-- caches the extmarks set by M.display
-- @private
---@private
local function save_extmarks(bufnr, client_id)
bufnr = bufnr == 0 and api.nvim_get_current_buf() or bufnr
if not diagnostic_attached_buffers[bufnr] then
@@ -1101,7 +1101,7 @@ local function save_extmarks(bufnr, client_id)
diagnostic_cache_extmarks[bufnr][client_id] = api.nvim_buf_get_extmarks(bufnr, ns, 0, -1, {details = true})
end
--@private
---@private
--- Display diagnostics for the buffer, given a configuration.
function M.display(diagnostics, bufnr, client_id, config)
if diagnostic_disabled[bufnr][client_id] then
@@ -1187,10 +1187,10 @@ end
--- for redrawing diagnostics after making changes in diagnostics
--- configuration. |lsp-handler-configuration|
---
--- @param bufnr (optional, number): Buffer handle, defaults to current
--- @param client_id (optional, number): Redraw diagnostics for the given
--- client. The default is to redraw diagnostics for all attached
--- clients.
---@param bufnr (optional, number): Buffer handle, defaults to current
---@param client_id (optional, number): Redraw diagnostics for the given
--- client. The default is to redraw diagnostics for all attached
--- clients.
function M.redraw(bufnr, client_id)
bufnr = get_bufnr(bufnr)
if not client_id then
@@ -1410,10 +1410,10 @@ function M.set_loclist(opts)
end
--- Disable diagnostics for the given buffer and client
--- @param bufnr (optional, number): Buffer handle, defaults to current
--- @param client_id (optional, number): Disable diagnostics for the given
--- client. The default is to disable diagnostics for all attached
--- clients.
---@param bufnr (optional, number): Buffer handle, defaults to current
---@param client_id (optional, number): Disable diagnostics for the given
--- client. The default is to disable diagnostics for all attached
--- clients.
-- Note that when diagnostics are disabled for a buffer, the server will still
-- send diagnostic information and the client will still process it. The
-- diagnostics are simply not displayed to the user.
@@ -1429,10 +1429,10 @@ function M.disable(bufnr, client_id)
end
--- Enable diagnostics for the given buffer and client
--- @param bufnr (optional, number): Buffer handle, defaults to current
--- @param client_id (optional, number): Enable diagnostics for the given
--- client. The default is to enable diagnostics for all attached
--- clients.
---@param bufnr (optional, number): Buffer handle, defaults to current
---@param client_id (optional, number): Enable diagnostics for the given
--- client. The default is to enable diagnostics for all attached
--- clients.
function M.enable(bufnr, client_id)
if not client_id then
return vim.lsp.for_each_buffer_client(bufnr, function(client)

28
runtime/lua/vim/lsp/handlers.lua
View File

@@ -9,9 +9,9 @@ local M = {}
-- FIXME: DOC: Expose in vimdocs
--@private
---@private
--- Writes to error buffer.
--@param ... (table of strings) Will be concatenated before being written
---@param ... (table of strings) Will be concatenated before being written
local function err_message(...)
vim.notify(table.concat(vim.tbl_flatten{...}), vim.log.levels.ERROR)
api.nvim_command("redraw")
@@ -22,7 +22,7 @@ M['workspace/executeCommand'] = function()
-- Error handling is done implicitly by wrapping all handlers; see end of this file
end
--@private
---@private
local function progress_handler(_, _, params, client_id)
local client = vim.lsp.get_client_by_id(client_id)
local client_name = client and client.name or string.format("id=%d", client_id)
@@ -189,7 +189,7 @@ end
--@private
---@private
--- Return a function that converts LSP responses to list items and opens the list
---
--- The returned function has an optional {config} parameter that accepts a table
@@ -197,8 +197,8 @@ end
---
--- loclist: (boolean) use the location list (default is to use the quickfix list)
---
--- @param map_result function `((resp, bufnr) -> list)` to convert the response
--- @param entity name of the resource used in a `not found` error message
---@param map_result function `((resp, bufnr) -> list)` to convert the response
---@param entity name of the resource used in a `not found` error message
local function response_to_list(map_result, entity)
return function(_, _, result, _, bufnr, config)
if not result or vim.tbl_isempty(result) then
@@ -289,11 +289,11 @@ end
--see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
M['textDocument/hover'] = M.hover
--@private
---@private
--- Jumps to a location. Used as a handler for multiple LSP methods.
--@param _ (not used)
--@param method (string) LSP method name
--@param result (table) result of LSP method; a location or a list of locations.
---@param _ (not used)
---@param method (string) LSP method name
---@param result (table) result of LSP method; a location or a list of locations.
---(`textDocument/definition` can return `Location` or `Location[]`
local function location_handler(_, method, result)
if result == nil or vim.tbl_isempty(result) then
@@ -377,13 +377,13 @@ M['textDocument/documentHighlight'] = function(_, _, result, _, bufnr, _)
util.buf_highlight_references(bufnr, result)
end
--@private
---@private
---
--- Displays call hierarchy in the quickfix window.
---
--@param direction `"from"` for incoming calls and `"to"` for outgoing calls
--@returns `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
--@returns `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,
---@param direction `"from"` for incoming calls and `"to"` for outgoing calls
---@returns `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
---@returns `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,
local make_call_hierarchy_handler = function(direction)
return function(_, _, result)
if not result then return end

10
runtime/lua/vim/lsp/log.lua
View File

@@ -18,14 +18,14 @@ local log_date_format = "%FT%H:%M:%S%z"
do
local path_sep = vim.loop.os_uname().version:match("Windows") and "\\" or "/"
--@private
---@private
local function path_join(...)
return table.concat(vim.tbl_flatten{...}, path_sep)
end
local logfilename = path_join(vim.fn.stdpath('cache'), 'lsp.log')
--- Returns the log filename.
--@returns (string) log filename
---@returns (string) log filename
function log.get_filename()
return logfilename
end
@@ -77,7 +77,7 @@ end
vim.tbl_add_reverse_lookup(log.levels)
--- Sets the current log level.
--@param level (string or number) One of `vim.lsp.log.levels`
---@param level (string or number) One of `vim.lsp.log.levels`
function log.set_level(level)
if type(level) == 'string' then
current_log_level = assert(log.levels[level:upper()], string.format("Invalid log level: %q", level))
@@ -89,8 +89,8 @@ function log.set_level(level)
end
--- Checks whether the level is sufficient for logging.
--@param level number log level
--@returns (bool) true if would log, false if not
---@param level number log level
---@returns (bool) true if would log, false if not
function log.should_log(level)
return level >= current_log_level
end

4
runtime/lua/vim/lsp/protocol.lua
View File

@@ -5,14 +5,14 @@ local if_nil = vim.F.if_nil
local protocol = {}
--[=[
--@private
---@private
--- Useful for interfacing with:
--- https://github.com/microsoft/language-server-protocol/raw/gh-pages/_specifications/specification-3-14.md
function transform_schema_comments()
nvim.command [[silent! '<,'>g/\/\*\*\|\*\/\|^$/d]]
nvim.command [[silent! '<,'>s/^\(\s*\) \* \=\(.*\)/\1--\2/]]
end
--@private
---@private
function transform_schema_to_table()
transform_schema_comments()
nvim.command [[silent! '<,'>s/: \S\+//]]

132
runtime/lua/vim/lsp/rpc.lua
View File

@@ -5,11 +5,11 @@ local protocol = require('vim.lsp.protocol')
local validate, schedule, schedule_wrap = vim.validate, vim.schedule, vim.schedule_wrap
-- TODO replace with a better implementation.
--@private
---@private
--- Encodes to JSON.
---
--@param data (table) Data to encode
--@returns (string) Encoded object
---@param data (table) Data to encode
---@returns (string) Encoded object
local function json_encode(data)
local status, result = pcall(vim.fn.json_encode, data)
if status then
@@ -18,11 +18,11 @@ local function json_encode(data)
return nil, result
end
end
--@private
---@private
--- Decodes from JSON.
---
--@param data (string) Data to decode
--@returns (table) Decoded JSON object
---@param data (string) Data to decode
---@returns (table) Decoded JSON object
local function json_decode(data)
local status, result = pcall(vim.fn.json_decode, data)
if status then
@@ -32,10 +32,10 @@ local function json_decode(data)
end
end
--@private
---@private
--- Checks whether a given path exists and is a directory.
--@param filename (string) path to check
--@returns (bool)
---@param filename (string) path to check
---@returns (bool)
local function is_dir(filename)
local stat = vim.loop.fs_stat(filename)
return stat and stat.type == 'directory' or false
@@ -43,7 +43,7 @@ end
local NIL = vim.NIL
--@private
---@private
local recursive_convert_NIL
recursive_convert_NIL = function(v, tbl_processed)
if v == NIL then
@@ -63,15 +63,15 @@ recursive_convert_NIL = function(v, tbl_processed)
return v
end
--@private
---@private
--- Returns its argument, but converts `vim.NIL` to Lua `nil`.
--@param v (any) Argument
--@returns (any)
---@param v (any) Argument
---@returns (any)
local function convert_NIL(v)
return recursive_convert_NIL(v, {})
end
--@private
---@private
--- Merges current process env with the given env and returns the result as
--- a list of "k=v" strings.
---
@@ -81,8 +81,8 @@ end
--- 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", }
--- </pre>
--@param env (table) table of environment variable assignments
--@returns (table) list of `"k=v"` strings
---@param env (table) table of environment variable assignments
---@returns (table) list of `"k=v"` strings
local function env_merge(env)
if env == nil then
return env
@@ -97,11 +97,11 @@ local function env_merge(env)
return final_env
end
--@private
---@private
--- Embeds the given string into a table and correctly computes `Content-Length`.
---
--@param encoded_message (string)
--@returns (table) table containing encoded message and `Content-Length` attribute
---@param encoded_message (string)
---@returns (table) table containing encoded message and `Content-Length` attribute
local function format_message_with_content_length(encoded_message)
return table.concat {
'Content-Length: '; tostring(#encoded_message); '\r\n\r\n';
@@ -109,11 +109,11 @@ local function format_message_with_content_length(encoded_message)
}
end
--@private
---@private
--- Parses an LSP Message's header
---
--@param header: The header to parse.
--@returns Parsed headers
---@param header: The header to parse.
---@returns Parsed headers
local function parse_headers(header)
if type(header) ~= 'string' then
return nil
@@ -141,7 +141,7 @@ end
-- case insensitive pattern.
local header_start_pattern = ("content"):gsub("%w", function(c) return "["..c..c:upper().."]" end)
--@private
---@private
--- The actual workhorse.
local function request_parser_loop()
local buffer = '' -- only for header part
@@ -203,8 +203,8 @@ local client_errors = vim.tbl_add_reverse_lookup {
--- Constructs an error message from an LSP error object.
---
--@param err (table) The error object
--@returns (string) The formatted error message
---@param err (table) The error object
---@returns (string) The formatted error message
local function format_rpc_error(err)
validate {
err = { err, 't' };
@@ -233,9 +233,9 @@ end
--- Creates an RPC response object/table.
---
--@param code RPC error code defined in `vim.lsp.protocol.ErrorCodes`
--@param message (optional) arbitrary message to send to server
--@param data (optional) arbitrary data to send to server
---@param code RPC error code defined in `vim.lsp.protocol.ErrorCodes`
---@param message (optional) arbitrary message to send to server
---@param data (optional) arbitrary data to send to server
local function rpc_response_error(code, message, data)
-- TODO should this error or just pick a sane error (like InternalError)?
local code_name = assert(protocol.ErrorCodes[code], 'Invalid RPC error code')
@@ -250,38 +250,38 @@ end
local default_dispatchers = {}
--@private
---@private
--- Default dispatcher for notifications sent to an LSP server.
---
--@param method (string) The invoked LSP method
--@param params (table): Parameters for the invoked LSP method
---@param method (string) The invoked LSP method
---@param params (table): Parameters for the invoked LSP method
function default_dispatchers.notification(method, params)
local _ = log.debug() and log.debug('notification', method, params)
end
--@private
---@private
--- Default dispatcher for requests sent to an LSP server.
---
--@param method (string) The invoked LSP method
--@param params (table): Parameters for the invoked LSP method
--@returns `nil` and `vim.lsp.protocol.ErrorCodes.MethodNotFound`.
---@param method (string) The invoked LSP method
---@param params (table): Parameters for the invoked LSP method
---@returns `nil` and `vim.lsp.protocol.ErrorCodes.MethodNotFound`.
function default_dispatchers.server_request(method, params)
local _ = log.debug() and log.debug('server_request', method, params)
return nil, rpc_response_error(protocol.ErrorCodes.MethodNotFound)
end
--@private
---@private
--- Default dispatcher for when a client exits.
---
--@param code (number): Exit code
--@param signal (number): Number describing the signal used to terminate (if
---@param code (number): Exit code
---@param signal (number): Number describing the signal used to terminate (if
---any)
function default_dispatchers.on_exit(code, signal)
local _ = log.info() and log.info("client_exit", { code = code, signal = signal })
end
--@private
---@private
--- Default dispatcher for client errors.
---
--@param code (number): Error code
--@param err (any): Details about the error
---@param code (number): Error code
---@param err (any): Details about the error
---any)
function default_dispatchers.on_error(code, err)
local _ = log.error() and log.error('client_error:', client_errors[code], err)
@@ -290,25 +290,25 @@ end
--- Starts an LSP server process and create an LSP RPC client object to
--- interact with it.
---
--@param cmd (string) Command to start the LSP server.
--@param cmd_args (table) List of additional string arguments to pass to {cmd}.
--@param dispatchers (table, optional) Dispatchers for LSP message types. Valid
---@param cmd (string) Command to start the LSP server.
---@param cmd_args (table) List of additional string arguments to pass to {cmd}.
---@param dispatchers (table, optional) Dispatchers for LSP message types. Valid
---dispatcher names are:
--- - `"notification"`
--- - `"server_request"`
--- - `"on_error"`
--- - `"on_exit"`
--@param extra_spawn_params (table, optional) Additional context for the LSP
---@param 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
--@returns Client RPC object.
---@returns Client RPC object.
---
--@returns Methods:
---@returns Methods:
--- - `notify()` |vim.lsp.rpc.notify()|
--- - `request()` |vim.lsp.rpc.request()|
---
--@returns Members:
---@returns Members:
--- - {pid} (number) The LSP server's PID.
--- - {handle} A handle for low-level interaction with the LSP server process
--- |vim.loop|.
@@ -358,10 +358,10 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
local handle, pid
do
--@private
---@private
--- Callback for |vim.loop.spawn()| Closes all streams and runs the `on_exit` dispatcher.
--@param code (number) Exit code
--@param signal (number) Signal that was used to terminate (if any)
---@param code (number) Exit code
---@param signal (number) Signal that was used to terminate (if any)
local function onexit(code, signal)
stdin:close()
stdout:close()
@@ -385,12 +385,12 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
end
end
--@private
---@private
--- Encodes {payload} into a JSON-RPC message and sends it to the remote
--- process.
---
--@param payload (table) Converted into a JSON string, see |json_encode()|
--@returns true if the payload could be scheduled, false if the main event-loop is in the process of closing.
---@param payload (table) Converted into a JSON string, see |json_encode()|
---@returns true if the payload could be scheduled, false if the main event-loop is in the process of closing.
local function encode_and_send(payload)
local _ = log.debug() and log.debug("rpc.send.payload", payload)
if handle == nil or handle:is_closing() then return false end
@@ -406,9 +406,9 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
-- `start()`
--
--- Sends a notification to the LSP server.
--@param method (string) The invoked LSP method
--@param params (table): Parameters for the invoked LSP method
--@returns (bool) `true` if notification could be sent, `false` if not
---@param method (string) The invoked LSP method
---@param params (table): Parameters for the invoked LSP method
---@returns (bool) `true` if notification could be sent, `false` if not
local function notify(method, params)
return encode_and_send {
jsonrpc = "2.0";
@@ -417,7 +417,7 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
}
end
--@private
---@private
--- sends an error object to the remote LSP process.
local function send_response(request_id, err, result)
return encode_and_send {
@@ -433,10 +433,10 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
--
--- Sends a request to the LSP server and runs {callback} upon response.
---
--@param method (string) The invoked LSP method
--@param params (table) Parameters for the invoked LSP method
--@param callback (function) Callback to invoke
--@returns (bool, number) `(true, message_id)` if request could be sent, `false` if not
---@param method (string) The invoked LSP method
---@param params (table) Parameters for the invoked LSP method
---@param callback (function) Callback to invoke
---@returns (bool, number) `(true, message_id)` if request could be sent, `false` if not
local function request(method, params, callback)
validate {
callback = { callback, 'f' };
@@ -463,13 +463,13 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
end
end)
--@private
---@private
local function on_error(errkind, ...)
assert(client_errors[errkind])
-- TODO what to do if this fails?
pcall(dispatchers.on_error, errkind, ...)
end
--@private
---@private
local function pcall_handler(errkind, status, head, ...)
if not status then
on_error(errkind, head, ...)
@@ -477,7 +477,7 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
end
return status, head, ...
end
--@private
---@private
local function try_call(errkind, fn, ...)
return pcall_handler(errkind, pcall(fn, ...))
end
@@ -486,7 +486,7 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
-- time and log them. This would require storing the timestamp. I could call
-- them with an error then, perhaps.
--@private
---@private
local function handle_body(body)
local decoded, err = json_decode(body)
if not decoded then

314
runtime/lua/vim/lsp/util.lua
View File

@@ -40,10 +40,10 @@ local loclist_type_map = {
}
--@private
-- Check the border given by opts or the default border for the additional
-- size it adds to a float.
--@returns size of border in height and width
---@private
--- Check the border given by opts or the default border for the additional
--- size it adds to a float.
---@returns size of border in height and width
local function get_border_size(opts)
local border = opts and opts.border or default_border
local height = 0
@@ -86,7 +86,7 @@ local function get_border_size(opts)
return { height = height, width = width }
end
--@private
---@private
local function split_lines(value)
return split(value, '\n', true)
end
@@ -95,11 +95,11 @@ end
---
--- CAUTION: Changes in-place!
---
--@param lines (table) Original list of strings
--@param A (table) Start position; a 2-tuple of {line, col} numbers
--@param B (table) End position; a 2-tuple of {line, col} numbers
--@param new_lines A list of strings to replace the original
--@returns (table) The modified {lines} object
---@param lines (table) Original list of strings
---@param A (table) Start position; a 2-tuple of {line, col} numbers
---@param B (table) End position; a 2-tuple of {line, col} numbers
---@param new_lines A list of strings to replace the original
---@returns (table) The modified {lines} object
function M.set_lines(lines, A, B, new_lines)
-- 0-indexing to 1-indexing
local i_0 = A[1] + 1
@@ -133,7 +133,7 @@ function M.set_lines(lines, A, B, new_lines)
return lines
end
--@private
---@private
local function sort_by_key(fn)
return function(a,b)
local ka, kb = fn(a), fn(b)
@@ -147,12 +147,12 @@ local function sort_by_key(fn)
return false
end
end
--@private
---@private
local edit_sort_key = sort_by_key(function(e)
return {e.A[1], e.A[2], e.i}
end)
--@private
---@private
--- Position is a https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position
--- Returns a zero-indexed column, since set_lines() does the conversion to
--- 1-indexed
@@ -238,8 +238,8 @@ function M.get_progress_messages()
end
--- Applies a list of text edits to a buffer.
--@param text_edits (table) list of `TextEdit` objects
--@param buf_nr (number) Buffer id
---@param text_edits (table) list of `TextEdit` objects
---@param buf_nr (number) Buffer id
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit
function M.apply_text_edits(text_edits, bufnr)
if not next(text_edits) then return end
@@ -295,11 +295,11 @@ end
-- function M.glob_to_regex(glob)
-- end
--@private
---@private
--- Finds the first line and column of the difference between old and new lines
--@param old_lines table list of lines
--@param new_lines table list of lines
--@returns (int, int) start_line_idx and start_col_idx of range
---@param old_lines table list of lines
---@param new_lines table list of lines
---@returns (int, int) start_line_idx and start_col_idx of range
local function first_difference(old_lines, new_lines, start_line_idx)
local line_count = math.min(#old_lines, #new_lines)
if line_count == 0 then return 1, 1 end
@@ -325,12 +325,12 @@ local function first_difference(old_lines, new_lines, start_line_idx)
end
--@private
---@private
--- Finds the last line and column of the differences between old and new lines
--@param old_lines table list of lines
--@param new_lines table list of lines
--@param start_char integer First different character idx of range
--@returns (int, int) end_line_idx and end_col_idx of range
---@param old_lines table list of lines
---@param new_lines table list of lines
---@param start_char integer First different character idx of range
---@returns (int, int) end_line_idx and end_col_idx of range
local function last_difference(old_lines, new_lines, start_char, end_line_idx)
local line_count = math.min(#old_lines, #new_lines)
if line_count == 0 then return 0,0 end
@@ -369,14 +369,14 @@ local function last_difference(old_lines, new_lines, start_char, end_line_idx)
end
--@private
---@private
--- Get the text of the range defined by start and end line/column
--@param lines table list of lines
--@param start_char integer First different character idx of range
--@param end_char integer Last different character idx of range
--@param start_line integer First different line idx of range
--@param end_line integer Last different line idx of range
--@returns string text extracted from defined region
---@param lines table list of lines
---@param start_char integer First different character idx of range
---@param end_char integer Last different character idx of range
---@param start_line integer First different line idx of range
---@param end_line integer Last different line idx of range
---@returns string text extracted from defined region
local function extract_text(lines, start_line, start_char, end_line, end_char)
if start_line == #lines + end_line + 1 then
if end_line == 0 then return '' end
@@ -396,14 +396,14 @@ local function extract_text(lines, start_line, start_char, end_line, end_char)
return result
end
--@private
---@private
--- Compute the length of the substituted range
--@param lines table list of lines
--@param start_char integer First different character idx of range
--@param end_char integer Last different character idx of range
--@param start_line integer First different line idx of range
--@param end_line integer Last different line idx of range
--@returns (int, int) end_line_idx and end_col_idx of range
---@param lines table list of lines
---@param start_char integer First different character idx of range
---@param end_char integer Last different character idx of range
---@param start_line integer First different line idx of range
---@param end_line integer Last different line idx of range
---@returns (int, int) end_line_idx and end_col_idx of range
local function compute_length(lines, start_line, start_char, end_line, end_char)
local adj_end_line = #lines + end_line + 1
local adj_end_char
@@ -424,12 +424,12 @@ local function compute_length(lines, start_line, start_char, end_line, end_char)
end
--- Returns the range table for the difference between old and new lines
--@param old_lines table list of lines
--@param new_lines table list of lines
--@param start_line_idx int line to begin search for first difference
--@param end_line_idx int line to begin search for last difference
--@param offset_encoding string encoding requested by language server
--@returns table start_line_idx and start_col_idx of range
---@param old_lines table list of lines
---@param new_lines table list of lines
---@param start_line_idx int line to begin search for first difference
---@param end_line_idx int line to begin search for last difference
---@param offset_encoding string encoding requested by language server
---@returns table start_line_idx and start_col_idx of range
function M.compute_diff(old_lines, new_lines, start_line_idx, end_line_idx, offset_encoding)
local start_line, start_char = first_difference(old_lines, new_lines, start_line_idx)
local end_line, end_char = last_difference(vim.list_slice(old_lines, start_line, #old_lines),
@@ -469,9 +469,9 @@ end
--- Can be used to extract the completion items from a
--- `textDocument/completion` request, which may return one of
--- `CompletionItem[]`, `CompletionList` or null.
--@param result (table) The result of a `textDocument/completion` request
--@returns (table) List of completion items
--@see https://microsoft.github.io/language-server-protocol/specification#textDocument_completion
---@param result (table) The result of a `textDocument/completion` request
---@returns (table) List of completion items
---@see https://microsoft.github.io/language-server-protocol/specification#textDocument_completion
function M.extract_completion_items(result)
if type(result) == 'table' and result.items then
-- result is a `CompletionList`
@@ -515,12 +515,12 @@ function M.apply_text_document_edit(text_document_edit, index)
M.apply_text_edits(text_document_edit.edits, bufnr)
end
--@private
---@private
--- Recursively parses snippets in a completion entry.
---
--@param input (string) Snippet text to parse for snippets
--@param inner (bool) Whether this function is being called recursively
--@returns 2-tuple of strings: The first is the parsed result, the second is the
---@param input (string) Snippet text to parse for snippets
---@param inner (bool) Whether this function is being called recursively
---@returns 2-tuple of strings: The first is the parsed result, the second is the
---unparsed rest of the input
local function parse_snippet_rec(input, inner)
local res = ""
@@ -577,28 +577,28 @@ end
--- Parses snippets in a completion entry.
---
--@param input (string) unparsed snippet
--@returns (string) parsed snippet
---@param input (string) unparsed snippet
---@returns (string) parsed snippet
function M.parse_snippet(input)
local res, _ = parse_snippet_rec(input, false)
return res
end
--@private
---@private
--- Sorts by CompletionItem.sortText.
---
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
--see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
local function sort_completion_items(items)
table.sort(items, function(a, b)
return (a.sortText or a.label) < (b.sortText or b.label)
end)
end
--@private
---@private
--- Returns text that should be inserted when selecting completion item. The
--- precedence is as follows: textEdit.newText > insertText > label
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
--see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
local function get_completion_word(item)
if item.textEdit ~= nil and item.textEdit.newText ~= nil and item.textEdit.newText ~= "" then
local insert_text_format = protocol.InsertTextFormat[item.insertTextFormat]
@@ -618,7 +618,7 @@ local function get_completion_word(item)
return item.label
end
--@private
---@private
--- Some language servers return complementary candidates whose prefixes do not
--- match are also returned. So we exclude completion candidates whose prefix
--- does not match.
@@ -633,9 +633,9 @@ end
--- the client must handle it properly even if it receives a value outside the
--- specification.
---
--@param completion_item_kind (`vim.lsp.protocol.completionItemKind`)
--@returns (`vim.lsp.protocol.completionItemKind`)
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
---@param completion_item_kind (`vim.lsp.protocol.completionItemKind`)
---@returns (`vim.lsp.protocol.completionItemKind`)
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_completion
function M._get_completion_item_kind_name(completion_item_kind)
return protocol.CompletionItemKind[completion_item_kind] or "Unknown"
end
@@ -643,12 +643,12 @@ end
--- Turns the result of a `textDocument/completion` request into vim-compatible
--- |complete-items|.
---
--@param result The result of a `textDocument/completion` call, e.g. from
---@param result The result of a `textDocument/completion` call, e.g. from
---|vim.lsp.buf.completion()|, which may be one of `CompletionItem[]`,
--- `CompletionList` or `null`
--@param prefix (string) the prefix to filter the completion items
--@returns { matches = complete-items table, incomplete = bool }
--@see |complete-items|
---@param prefix (string) the prefix to filter the completion items
---@returns { matches = complete-items table, incomplete = bool }
---@see |complete-items|
function M.text_document_completion_list_to_complete_items(result, prefix)
local items = M.extract_completion_items(result)
if vim.tbl_isempty(items) then
@@ -698,8 +698,8 @@ end
--- Rename old_fname to new_fname
--
--@param opts (table)
---
---@param opts (table)
-- overwrite? bool
-- ignoreIfExists? bool
function M.rename(old_fname, new_fname, opts)
@@ -754,8 +754,8 @@ end
--- Applies a `WorkspaceEdit`.
---
--@param workspace_edit (table) `WorkspaceEdit`
-- @see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit
---@param workspace_edit (table) `WorkspaceEdit`
--see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit
function M.apply_workspace_edit(workspace_edit)
if workspace_edit.documentChanges then
for idx, change in ipairs(workspace_edit.documentChanges) do
@@ -794,10 +794,10 @@ end
--- window for `textDocument/hover`, for parsing the result of
--- `textDocument/signatureHelp`, and potentially others.
---
--@param input (`MarkedString` | `MarkedString[]` | `MarkupContent`)
--@param contents (table, optional, default `{}`) List of strings to extend with converted lines
--@returns {contents}, extended with lines of converted markdown.
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
---@param input (`MarkedString` | `MarkedString[]` | `MarkupContent`)
---@param contents (table, optional, default `{}`) List of strings to extend with converted lines
---@returns {contents}, extended with lines of converted markdown.
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
function M.convert_input_to_markdown_lines(input, contents)
contents = contents or {}
-- MarkedString variation 1
@@ -844,11 +844,11 @@ end
--- Converts `textDocument/SignatureHelp` response to markdown lines.
---
--@param signature_help Response of `textDocument/SignatureHelp`
--@param ft optional filetype that will be use as the `lang` for the label markdown code block
--@param triggers optional list of trigger characters from the lsp server. used to better determine parameter offsets
--@returns list of lines of converted markdown.
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
---@param signature_help Response of `textDocument/SignatureHelp`
---@param ft optional filetype that will be use as the `lang` for the label markdown code block
---@param triggers optional list of trigger characters from the lsp server. used to better determine parameter offsets
---@returns list of lines of converted markdown.
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
function M.convert_signature_help_to_markdown_lines(signature_help, ft, triggers)
if not signature_help.signatures then
return
@@ -943,10 +943,10 @@ end
--- Creates a table with sensible default options for a floating window. The
--- table can be passed to |nvim_open_win()|.
---
--@param width (number) window width (in character cells)
--@param height (number) window height (in character cells)
--@param opts (table, optional)
--@returns (table) Options
---@param width (number) window width (in character cells)
---@param height (number) window height (in character cells)
---@param opts (table, optional)
---@returns (table) Options
function M.make_floating_popup_options(width, height, opts)
validate {
opts = { opts, 't', true };
@@ -997,8 +997,8 @@ end
--- Jumps to a location.
---
--@param location (`Location`|`LocationLink`)
--@returns `true` if the jump succeeded
---@param location (`Location`|`LocationLink`)
---@returns `true` if the jump succeeded
function M.jump_to_location(location)
-- location may be Location or LocationLink
local uri = location.uri or location.targetUri
@@ -1028,8 +1028,8 @@ end
--- - for Location, range is shown (e.g., function definition)
--- - for LocationLink, targetRange is shown (e.g., body of function definition)
---
--@param location a single `Location` or `LocationLink`
--@returns (bufnr,winnr) buffer and window number of floating window or nil
---@param location a single `Location` or `LocationLink`
---@returns (bufnr,winnr) buffer and window number of floating window or nil
function M.preview_location(location, opts)
-- location may be LocationLink or Location (more useful for the former)
local uri = location.targetUri or location.uri
@@ -1052,7 +1052,7 @@ function M.preview_location(location, opts)
return M.open_floating_preview(contents, syntax, opts)
end
--@private
---@private
local function find_window_by_var(name, value)
for _, win in ipairs(api.nvim_list_wins()) do
if npcall(api.nvim_win_get_var, win, name) == value then
@@ -1088,10 +1088,10 @@ function M._trim(contents, opts)
return contents
end
-- Generates a table mapping markdown code block lang to vim syntax,
-- based on g:markdown_fenced_languages
-- @return a table of lang -> syntax mappings
-- @private
--- Generates a table mapping markdown code block lang to vim syntax,
--- based on g:markdown_fenced_languages
---@return a table of lang -> syntax mappings
---@private
local function get_markdown_fences()
local fences = {}
for _, fence in pairs(vim.g.markdown_fenced_languages or {}) do
@@ -1227,7 +1227,7 @@ function M.stylize_markdown(bufnr, contents, opts)
vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, stripped)
local idx = 1
--@private
---@private
-- keep track of syntaxes we already inlcuded.
-- no need to include the same syntax more than once
local langs = {}
@@ -1276,26 +1276,26 @@ end
--- Creates autocommands to close a preview window when events happen.
---
--@param events (table) list of events
--@param winnr (number) window id of preview window
--@see |autocmd-events|
---@param events (table) list of events
---@param winnr (number) window id of preview window
---@see |autocmd-events|
function M.close_preview_autocmd(events, winnr)
if #events > 0 then
api.nvim_command("autocmd "..table.concat(events, ',').." <buffer> ++once lua pcall(vim.api.nvim_win_close, "..winnr..", true)")
end
end
--@internal
---@internal
--- Computes size of float needed to show contents (with optional wrapping)
---
--@param contents table of lines to show in window
--@param opts dictionary with optional fields
-- - height of floating window
-- - width of floating window
-- - wrap_at character to wrap at for computing height
-- - max_width maximal width of floating window
-- - max_height maximal height of floating window
--@returns width,height size of float
---@param contents table of lines to show in window
---@param opts dictionary with optional fields
--- - height of floating window
--- - width of floating window
--- - wrap_at character to wrap at for computing height
--- - max_width maximal width of floating window
--- - max_height maximal height of floating window
---@returns width,height size of float
function M._make_floating_popup_size(contents, opts)
validate {
contents = { contents, 't' };
@@ -1362,9 +1362,9 @@ end
--- Shows contents in a floating window.
---
--@param contents table of lines to show in window
--@param syntax string of syntax to set for opened buffer
--@param opts dictionary with optional fields
---@param contents table of lines to show in window
---@param syntax string of syntax to set for opened buffer
---@param opts dictionary with optional fields
--- - height of floating window
--- - width of floating window
--- - wrap boolean enable wrapping of long lines (defaults to true)
@@ -1378,7 +1378,7 @@ end
--- - focus_id if a popup with this id is opened, then focus it
--- - close_events list of events that closes the floating window
--- - focusable (boolean, default true): Make float focusable
--@returns bufnr,winnr buffer and window number of the newly created floating
---@returns bufnr,winnr buffer and window number of the newly created floating
---preview window
function M.open_floating_preview(contents, syntax, opts)
validate {
@@ -1474,7 +1474,7 @@ do --[[ References ]]
--- Removes document highlights from a buffer.
---
--@param bufnr buffer id
---@param bufnr buffer id
function M.buf_clear_references(bufnr)
validate { bufnr = {bufnr, 'n', true} }
api.nvim_buf_clear_namespace(bufnr, reference_ns, 0, -1)
@@ -1482,8 +1482,8 @@ do --[[ References ]]
--- Shows a list of document highlights for a certain buffer.
---
--@param bufnr buffer id
--@param references List of `DocumentHighlight` objects to highlight
---@param bufnr buffer id
---@param references List of `DocumentHighlight` objects to highlight
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#documentHighlight
function M.buf_highlight_references(bufnr, references)
validate { bufnr = {bufnr, 'n', true} }
@@ -1505,24 +1505,24 @@ local position_sort = sort_by_key(function(v)
return {v.start.line, v.start.character}
end)
-- Gets the zero-indexed line from the given uri.
--- Gets the zero-indexed line from the given uri.
---@param uri string uri of the resource to get the line from
---@param row number zero-indexed line number
---@return string the line at row in filename
-- For non-file uris, we load the buffer and get the line.
-- If a loaded buffer exists, then that is used.
-- Otherwise we get the line using libuv which is a lot faster than loading the buffer.
--@param uri string uri of the resource to get the line from
--@param row number zero-indexed line number
--@return string the line at row in filename
function M.get_line(uri, row)
return M.get_lines(uri, { row })[row]
end
-- Gets the zero-indexed lines from the given uri.
--- Gets the zero-indexed lines from the given uri.
---@param uri string uri of the resource to get the lines from
---@param rows number[] zero-indexed line numbers
---@return table<number string> a table mapping rows to lines
-- For non-file uris, we load the buffer and get the lines.
-- If a loaded buffer exists, then that is used.
-- Otherwise we get the lines using libuv which is a lot faster than loading the buffer.
--@param uri string uri of the resource to get the lines from
--@param rows number[] zero-indexed line numbers
--@return table<number string> a table mapping rows to lines
function M.get_lines(uri, rows)
rows = type(rows) == "table" and rows or { rows }
@@ -1590,8 +1590,8 @@ end
--- Returns the items with the byte position calculated correctly and in sorted
--- order, for display in quickfix and location lists.
---
--@param locations (table) list of `Location`s or `LocationLink`s
--@returns (table) list of items
---@param locations (table) list of `Location`s or `LocationLink`s
---@returns (table) list of items
function M.locations_to_items(locations)
local items = {}
local grouped = setmetatable({}, {
@@ -1648,7 +1648,7 @@ end
--- Can be obtained with e.g. |vim.lsp.util.locations_to_items()|.
--- Defaults to current window.
---
--@param items (table) list of items
---@param items (table) list of items
function M.set_loclist(items, win_id)
vim.fn.setloclist(win_id or 0, {}, ' ', {
title = 'Language Server';
@@ -1659,7 +1659,7 @@ end
--- Fills quickfix list with given list of items.
--- Can be obtained with e.g. |vim.lsp.util.locations_to_items()|.
---
--@param items (table) list of items
---@param items (table) list of items
function M.set_qflist(items)
vim.fn.setqflist({}, ' ', {
title = 'Language Server';
@@ -1676,9 +1676,9 @@ end
--- Converts symbols to quickfix list items.
---
--@param symbols DocumentSymbol[] or SymbolInformation[]
---@param symbols DocumentSymbol[] or SymbolInformation[]
function M.symbols_to_items(symbols, bufnr)
--@private
---@private
local function _symbols_to_items(_symbols, _items, _bufnr)
for _, symbol in ipairs(_symbols) do
if symbol.location then -- SymbolInformation type
@@ -1714,8 +1714,8 @@ function M.symbols_to_items(symbols, bufnr)
end
--- Removes empty lines from the beginning and end.
--@param lines (table) list of lines to trim
--@returns (table) trimmed list of lines
---@param lines (table) list of lines to trim
---@returns (table) trimmed list of lines
function M.trim_empty_lines(lines)
local start = 1
for i = 1, #lines do
@@ -1739,8 +1739,8 @@ end
---
--- CAUTION: Modifies the input in-place!
---
--@param lines (table) list of lines
--@returns (string) filetype or 'markdown' if it was unchanged.
---@param lines (table) list of lines
---@returns (string) filetype or 'markdown' if it was unchanged.
function M.try_trim_markdown_code_blocks(lines)
local language_id = lines[1]:match("^```(.*)")
if language_id then
@@ -1763,7 +1763,7 @@ function M.try_trim_markdown_code_blocks(lines)
end
local str_utfindex = vim.str_utfindex
--@private
---@private
local function make_position_param()
local row, col = unpack(api.nvim_win_get_cursor(0))
row = row - 1
@@ -1777,8 +1777,8 @@ end
--- Creates a `TextDocumentPositionParams` object for the current buffer and cursor position.
---
--@returns `TextDocumentPositionParams` object
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
---@returns `TextDocumentPositionParams` object
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
function M.make_position_params()
return {
textDocument = M.make_text_document_params();
@@ -1791,7 +1791,7 @@ end
--- `textDocument/codeAction`, `textDocument/colorPresentation`,
--- `textDocument/rangeFormatting`.
---
--@returns { textDocument = { uri = `current_file_uri` }, range = { start =
---@returns { textDocument = { uri = `current_file_uri` }, range = { start =
---`current_position`, end = `current_position` } }
function M.make_range_params()
local position = make_position_param()
@@ -1804,11 +1804,11 @@ end
--- Using the given range in the current buffer, creates an object that
--- is similar to |vim.lsp.util.make_range_params()|.
---
--@param start_pos ({number, number}, optional) mark-indexed position.
---@param start_pos ({number, number}, optional) mark-indexed position.
---Defaults to the start of the last visual selection.
--@param end_pos ({number, number}, optional) mark-indexed position.
---@param end_pos ({number, number}, optional) mark-indexed position.
---Defaults to the end of the last visual selection.
--@returns { textDocument = { uri = `current_file_uri` }, range = { start =
---@returns { textDocument = { uri = `current_file_uri` }, range = { start =
---`start_position`, end = `end_position` } }
function M.make_given_range_params(start_pos, end_pos)
validate {
@@ -1844,23 +1844,23 @@ end
--- Creates a `TextDocumentIdentifier` object for the current buffer.
---
--@returns `TextDocumentIdentifier`
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
---@returns `TextDocumentIdentifier`
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
function M.make_text_document_params()
return { uri = vim.uri_from_bufnr(0) }
end
--- Create the workspace params
--@param added
--@param removed
---@param added
---@param removed
function M.make_workspace_params(added, removed)
return { event = { added = added; removed = removed; } }
end
--- Returns visual width of tabstop.
---
--@see |softtabstop|
--@param bufnr (optional, number): Buffer handle, defaults to current
--@returns (number) tabstop visual width
---@see |softtabstop|
---@param bufnr (optional, number): Buffer handle, defaults to current
---@returns (number) tabstop visual width
function M.get_effective_tabstop(bufnr)
validate { bufnr = {bufnr, 'n', true} }
local bo = bufnr and vim.bo[bufnr] or vim.bo
@@ -1870,9 +1870,9 @@ end
--- Creates a `DocumentFormattingParams` object for the current buffer and cursor position.
---
--@param options Table with valid `FormattingOptions` entries
--@returns `DocumentFormattingParams` object
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
---@param options Table with valid `FormattingOptions` entries
---@returns `DocumentFormattingParams` object
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
function M.make_formatting_params(options)
validate { options = {options, 't', true} }
options = vim.tbl_extend('keep', options or {}, {
@@ -1887,10 +1887,10 @@ end
--- Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer.
---
--@param buf buffer id (0 for current)
--@param row 0-indexed line
--@param col 0-indexed byte offset in line
--@returns (number, number) UTF-32 and UTF-16 index of the character in line {row} column {col} in buffer {buf}
---@param buf buffer id (0 for current)
---@param row 0-indexed line
---@param col 0-indexed byte offset in line
---@returns (number, number) UTF-32 and UTF-16 index of the character in line {row} column {col} in buffer {buf}
function M.character_offset(bufnr, row, col)
local uri = vim.uri_from_bufnr(bufnr)
local line = M.get_line(uri, row)
@@ -1903,9 +1903,9 @@ end
--- Helper function to return nested values in language server settings
---
--@param settings a table of language server settings
--@param section a string indicating the field of the settings table
--@returns (table or string) The value of settings accessed via section
---@param settings a table of language server settings
---@param section a string indicating the field of the settings table
---@returns (table or string) The value of settings accessed via section
function M.lookup_section(settings, section)
for part in vim.gsplit(section, '.', true) do
settings = settings[part]
@@ -1920,10 +1920,10 @@ end
--- Convert diagnostics grouped by bufnr to a list of items for use in the
--- quickfix or location list.
---
--@param diagnostics_by_bufnr table bufnr -> Diagnostic[]
--@param predicate an optional function to filter the diagnostics.
-- If present, only diagnostic items matching will be included.
--@return table (A list of items)
---@param diagnostics_by_bufnr table bufnr -> Diagnostic[]
---@param predicate an optional function to filter the diagnostics.
--- If present, only diagnostic items matching will be included.
---@return table (A list of items)
function M.diagnostics_to_items(diagnostics_by_bufnr, predicate)
local items = {}
for bufnr, diagnostics in pairs(diagnostics_by_bufnr or {}) do

138
runtime/lua/vim/shared.lua
View File

@@ -12,8 +12,8 @@ local vim = vim or {}
--- same functions as those in the input table. Userdata and threads are not
--- copied and will throw an error.
---
--@param orig Table to copy
--@returns New table of copied keys and (nested) values.
---@param orig Table to copy
---@returns New table of copied keys and (nested) values.
function vim.deepcopy(orig) end -- luacheck: no unused
vim.deepcopy = (function()
local function _id(v)
@@ -52,14 +52,14 @@ end)()
--- Splits a string at each instance of a separator.
---
--@see |vim.split()|
--@see https://www.lua.org/pil/20.2.html
--@see http://lua-users.org/wiki/StringLibraryTutorial
---@see |vim.split()|
---@see https://www.lua.org/pil/20.2.html
---@see http://lua-users.org/wiki/StringLibraryTutorial
---
--@param s String to split
--@param sep Separator string or pattern
--@param plain If `true` use `sep` literally (passed to String.find)
--@returns Iterator over the split components
---@param s String to split
---@param sep Separator string or pattern
---@param plain If `true` use `sep` literally (passed to String.find)
---@returns Iterator over the split components
function vim.gsplit(s, sep, plain)
vim.validate{s={s,'s'},sep={sep,'s'},plain={plain,'b',true}}
@@ -101,12 +101,12 @@ end
--- split(x*yz*o, "*", true) --> {'x','yz','o'}
--- </pre>
--
--@see |vim.gsplit()|
---@see |vim.gsplit()|
---
--@param s String to split
--@param sep Separator string or pattern
--@param plain If `true` use `sep` literally (passed to String.find)
--@returns List-like table of the split components.
---@param s String to split
---@param sep Separator string or pattern
---@param plain If `true` use `sep` literally (passed to String.find)
---@returns List-like table of the split components.
function vim.split(s,sep,plain)
local t={} for c in vim.gsplit(s, sep, plain) do table.insert(t,c) end
return t
@@ -115,10 +115,10 @@ end
--- Return a list of all keys used in a table.
--- However, the order of the return table of keys is not guaranteed.
---
--@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
---
--@param t Table
--@returns list of keys
---@param t Table
---@returns list of keys
function vim.tbl_keys(t)
assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
@@ -132,8 +132,8 @@ end
--- Return a list of all values used in a table.
--- However, the order of the return table of values is not guaranteed.
---
--@param t Table
--@returns list of values
---@param t Table
---@returns list of values
function vim.tbl_values(t)
assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
@@ -146,8 +146,8 @@ end
--- Apply a function to all values of a table.
---
--@param func function or callable table
--@param t table
---@param func function or callable table
---@param t table
function vim.tbl_map(func, t)
vim.validate{func={func,'c'},t={t,'t'}}
@@ -160,8 +160,8 @@ end
--- Filter a table using a predicate function
---
--@param func function or callable table
--@param t table
---@param func function or callable table
---@param t table
function vim.tbl_filter(func, t)
vim.validate{func={func,'c'},t={t,'t'}}
@@ -176,9 +176,9 @@ end
--- Checks if a list-like (vector) table contains `value`.
---
--@param t Table to check
--@param value Value to compare
--@returns true if `t` contains `value`
---@param t Table to check
---@param value Value to compare
---@returns true if `t` contains `value`
function vim.tbl_contains(t, value)
vim.validate{t={t,'t'}}
@@ -192,16 +192,16 @@ end
--- Checks if a table is empty.
---
--@see https://github.com/premake/premake-core/blob/master/src/base/table.lua
---@see https://github.com/premake/premake-core/blob/master/src/base/table.lua
---
--@param t Table to check
---@param t Table to check
function vim.tbl_isempty(t)
assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
return next(t) == nil
end
--- we only merge empty tables or tables that are not a list
--@private
---@private
local function can_merge(v)
return type(v) == "table" and (vim.tbl_isempty(v) or not vim.tbl_islist(v))
end
@@ -242,26 +242,26 @@ end
--- Merges two or more map-like tables.
---
--@see |extend()|
---@see |extend()|
---
--@param behavior Decides what to do if a key is found in more than one map:
---@param behavior Decides what to do if a key is found in more than one map:
--- - "error": raise an error
--- - "keep": use value from the leftmost map
--- - "force": use value from the rightmost map
--@param ... Two or more map-like tables.
---@param ... Two or more map-like tables.
function vim.tbl_extend(behavior, ...)
return tbl_extend(behavior, false, ...)
end
--- Merges recursively two or more map-like tables.
---
--@see |tbl_extend()|
---@see |tbl_extend()|
---
--@param behavior Decides what to do if a key is found in more than one map:
---@param behavior Decides what to do if a key is found in more than one map:
--- - "error": raise an error
--- - "keep": use value from the leftmost map
--- - "force": use value from the rightmost map
--@param ... Two or more map-like tables.
---@param ... Two or more map-like tables.
function vim.tbl_deep_extend(behavior, ...)
return tbl_extend(behavior, true, ...)
end
@@ -292,7 +292,7 @@ end
--- `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }`
--
--Do note that it *modifies* the input.
--@param o table The table to add the reverse to.
---@param o table The table to add the reverse to.
function vim.tbl_add_reverse_lookup(o)
local keys = vim.tbl_keys(o)
for _, k in ipairs(keys) do
@@ -309,13 +309,13 @@ end
---
--- NOTE: This mutates dst!
---
--@see |vim.tbl_extend()|
---@see |vim.tbl_extend()|
---
--@param dst list which will be modified and appended to.
--@param src list from which values will be inserted.
--@param start Start index on src. defaults to 1
--@param finish Final index on src. defaults to #src
--@returns dst
---@param dst list which will be modified and appended to.
---@param src list from which values will be inserted.
---@param start Start index on src. defaults to 1
---@param finish Final index on src. defaults to #src
---@returns dst
function vim.list_extend(dst, src, start, finish)
vim.validate {
dst = {dst, 't'};
@@ -332,10 +332,10 @@ end
--- Creates a copy of a list-like table such that any nested tables are
--- "unrolled" and appended to the result.
---
--@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
---
--@param t List-like table
--@returns Flattened copy of the given list-like table.
---@param t List-like table
---@returns Flattened copy of the given list-like table.
function vim.tbl_flatten(t)
local result = {}
local function _tbl_flatten(_t)
@@ -359,8 +359,8 @@ end
--- |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
--- for example from |rpcrequest()| or |vim.fn|.
---
--@param t Table
--@returns `true` if array-like table, else `false`.
---@param t Table
---@returns `true` if array-like table, else `false`.
function vim.tbl_islist(t)
if type(t) ~= 'table' then
return false
@@ -395,9 +395,9 @@ end
--- vim.tbl_count({ 1, 2 }) => 2
--- </pre>
---
--@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
--@param t Table
--@returns Number that is the number of the value in table
---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
---@param t Table
---@returns Number that is the number of the value in table
function vim.tbl_count(t)
vim.validate{t={t,'t'}}
@@ -408,10 +408,10 @@ end
--- Creates a copy of a table containing only elements from start to end (inclusive)
---
--@param list table table
--@param start integer Start range of slice
--@param finish integer End range of slice
--@returns Copy of table sliced from start to finish (inclusive)
---@param list table table
---@param start integer Start range of slice
---@param finish integer End range of slice
---@returns Copy of table sliced from start to finish (inclusive)
function vim.list_slice(list, start, finish)
local new_list = {}
for i = start or 1, finish or #list do
@@ -422,9 +422,9 @@ end
--- Trim whitespace (Lua pattern "%s") from both sides of a string.
---
--@see https://www.lua.org/pil/20.2.html
--@param s String to trim
--@returns String with whitespace removed from its beginning and end
---@see https://www.lua.org/pil/20.2.html
---@param s String to trim
---@returns String with whitespace removed from its beginning and end
function vim.trim(s)
vim.validate{s={s,'s'}}
return s:match('^%s*(.*%S)') or ''
@@ -432,9 +432,9 @@ end
--- Escapes magic chars in a Lua pattern.
---
--@see https://github.com/rxi/lume
--@param s String to escape
--@returns %-escaped pattern string
---@see https://github.com/rxi/lume
---@param s String to escape
---@returns %-escaped pattern string
function vim.pesc(s)
vim.validate{s={s,'s'}}
return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
@@ -442,9 +442,9 @@ end
--- Tests if `s` starts with `prefix`.
---
--@param s (string) a string
--@param prefix (string) a prefix
--@return (boolean) true if `prefix` is a prefix of s
---@param s (string) a string
---@param prefix (string) a prefix
---@return (boolean) true if `prefix` is a prefix of s
function vim.startswith(s, prefix)
vim.validate { s = {s, 's'}; prefix = {prefix, 's'}; }
return s:sub(1, #prefix) == prefix
@@ -452,9 +452,9 @@ end
--- Tests if `s` ends with `suffix`.
---
--@param s (string) a string
--@param suffix (string) a suffix
--@return (boolean) true if `suffix` is a suffix of s
---@param s (string) a string
---@param suffix (string) a suffix
---@return (boolean) true if `suffix` is a suffix of s
function vim.endswith(s, suffix)
vim.validate { s = {s, 's'}; suffix = {suffix, 's'}; }
return #suffix == 0 or s:sub(-#suffix) == suffix
@@ -486,7 +486,7 @@ end
--- => error('arg1: expected even number, got 3')
--- </pre>
---
--@param opt Map of parameter names to validations. Each key is a parameter
---@param opt Map of parameter names to validations. Each key is a parameter
--- name; each value is a tuple in one of these forms:
--- 1. (arg_value, type_name, optional)
--- - arg_value: argument value
@@ -570,8 +570,8 @@ do
end
--- Returns true if object `f` can be called as a function.
---
--@param f Any object
--@return true if `f` is callable, else false
---@param f Any object
---@return true if `f` is callable, else false
function vim.is_callable(f)
if type(f) == 'function' then return true end
local m = getmetatable(f)

20
runtime/lua/vim/treesitter.lua
View File

@@ -28,9 +28,9 @@ setmetatable(M, {
---
--- It is not recommended to use this, use vim.treesitter.get_parser() instead.
---
--- @param bufnr The buffer the parser will be tied to
--- @param lang The language of the parser
--- @param opts Options to pass to the created language tree
---@param bufnr The buffer the parser will be tied to
---@param lang The language of the parser
---@param opts Options to pass to the created language tree
function M._create_parser(bufnr, lang, opts)
language.require_language(lang)
if bufnr == 0 then
@@ -71,11 +71,11 @@ end
--- If needed this will create the parser.
--- Unconditionnally attach the provided callback
---
--- @param bufnr The buffer the parser should be tied to
--- @param lang The filetype of this parser
--- @param opts Options object to pass to the created language tree
---@param bufnr The buffer the parser should be tied to
---@param lang The filetype of this parser
---@param opts Options object to pass to the created language tree
---
--- @returns The parser
---@returns The parser
function M.get_parser(bufnr, lang, opts)
opts = opts or {}
@@ -97,9 +97,9 @@ end
--- Gets a string parser
---
--- @param str The string to parse
--- @param lang The language of this string
--- @param opts Options to pass to the created language tree
---@param str The string to parse
---@param lang The language of this string
---@param opts Options to pass to the created language tree
function M.get_string_parser(str, lang, opts)
vim.validate {
str = { str, 'string' },

6
runtime/lua/vim/treesitter/highlighter.lua
View File

@@ -122,8 +122,8 @@ end
--- Creates a new highlighter using @param tree
---
--- @param tree The language tree to use for highlighting
--- @param opts Table used to configure the highlighter
---@param tree The language tree to use for highlighting
---@param opts Table used to configure the highlighter
--- - queries: Table to overwrite queries used by the highlighter
function TSHighlighter.new(tree, opts)
local self = setmetatable({}, TSHighlighter)
@@ -217,7 +217,7 @@ end
--- Gets the query used for @param lang
---
--- @param lang A language used by the highlighter.
---@param lang A language used by the highlighter.
function TSHighlighter:get_query(lang)
if not self._queries[lang] then
self._queries[lang] = TSHighlighterQuery.new(lang)

8
runtime/lua/vim/treesitter/language.lua
View File

@@ -6,9 +6,9 @@ local M = {}
---
--- Parsers are searched in the `parser` runtime directory.
---
--- @param lang The language the parser should parse
--- @param path Optional path the parser is located at
--- @param silent Don't throw an error if language not found
---@param lang The language the parser should parse
---@param path Optional path the parser is located at
---@param silent Don't throw an error if language not found
function M.require_language(lang, path, silent)
if vim._ts_has_language(lang) then
return true
@@ -40,7 +40,7 @@ end
---
--- Inspecting provides some useful informations on the language like node names, ...
---
--- @param lang The language.
---@param lang The language.
function M.inspect_language(lang)
M.require_language(lang)
return vim._ts_inspect_language(lang)

34
runtime/lua/vim/treesitter/languagetree.lua
View File

@@ -9,12 +9,12 @@ LanguageTree.__index = LanguageTree
--- The language can contain child languages with in its range,
--- hence the tree.
---
--- @param source Can be a bufnr or a string of text to parse
--- @param lang The language this tree represents
--- @param opts Options table
--- @param opts.injections A table of language to injection query strings.
--- This is useful for overriding the built-in runtime file
--- searching for the injection language query per language.
---@param source Can be a bufnr or a string of text to parse
---@param lang The language this tree represents
---@param opts Options table
---@param opts.injections A table of language to injection query strings.
--- This is useful for overriding the built-in runtime file
--- searching for the injection language query per language.
function LanguageTree.new(source, lang, opts)
language.require_language(lang)
opts = opts or {}
@@ -171,8 +171,8 @@ end
--- Invokes the callback for each LanguageTree and it's children recursively
---
--- @param fn The function to invoke. This is invoked with arguments (tree: LanguageTree, lang: string)
--- @param include_self Whether to include the invoking tree in the results.
---@param fn The function to invoke. This is invoked with arguments (tree: LanguageTree, lang: string)
---@param include_self Whether to include the invoking tree in the results.
function LanguageTree:for_each_child(fn, include_self)
if include_self then
fn(self, self._lang)
@@ -187,8 +187,8 @@ end
---
--- Note, this includes the invoking language tree's trees as well.
---
--- @param fn The callback to invoke. The callback is invoked with arguments
--- (tree: TSTree, languageTree: LanguageTree)
---@param fn The callback to invoke. The callback is invoked with arguments
--- (tree: TSTree, languageTree: LanguageTree)
function LanguageTree:for_each_tree(fn)
for _, tree in ipairs(self._trees) do
fn(tree, self)
@@ -203,7 +203,7 @@ end
---
--- If the language already exists as a child, it will first be removed.
---
--- @param lang The language to add.
---@param lang The language to add.
function LanguageTree:add_child(lang)
if self._children[lang] then
self:remove_child(lang)
@@ -219,7 +219,7 @@ end
--- Removes a child language from this tree.
---
--- @param lang The language to remove.
---@param lang The language to remove.
function LanguageTree:remove_child(lang)
local child = self._children[lang]
@@ -259,7 +259,7 @@ end
---
--- Note, this call invalidates the tree and requires it to be parsed again.
---
--- @param regions A list of regions this tree should manage and parse.
---@param regions A list of regions this tree should manage and parse.
function LanguageTree:set_included_regions(regions)
-- TODO(vigoux): I don't think string parsers are useful for now
if type(self._source) == "number" then
@@ -299,7 +299,7 @@ end
---
--- TODO: Allow for an offset predicate to tailor the injection range
--- instead of using the entire nodes range.
--- @private
---@private
function LanguageTree:_get_injections()
if not self._injection_query then return {} end
@@ -449,7 +449,7 @@ function LanguageTree:_on_detach(...)
end
--- Registers callbacks for the parser
--- @param cbs An `nvim_buf_attach`-like table argument with the following keys :
---@param cbs An `nvim_buf_attach`-like table argument with the following keys :
--- `on_bytes` : see `nvim_buf_attach`, but this will be called _after_ the parsers callback.
--- `on_changedtree` : a callback that will be called every time the tree has syntactical changes.
--- it will only be passed one argument, that is a table of the ranges (as node ranges) that
@@ -497,7 +497,7 @@ end
---
--- This goes down the tree to recursively check childs.
---
--- @param range A range, that is a `{ start_line, start_col, end_line, end_col }` table.
---@param range A range, that is a `{ start_line, start_col, end_line, end_col }` table.
function LanguageTree:contains(range)
for _, tree in pairs(self._trees) do
if tree_contains(tree, range) then
@@ -510,7 +510,7 @@ end
--- Gets the appropriate language that contains @param range
---
--- @param range A text range, see |LanguageTree:contains|
---@param range A text range, see |LanguageTree:contains|
function LanguageTree:language_for_range(range)
for _, child in pairs(self._children) do
if child:contains(range) then

68
runtime/lua/vim/treesitter/query.lua
View File

@@ -36,9 +36,9 @@ end
--- Gets the list of files used to make up a query
---
--- @param lang The language
--- @param query_name The name of the query to load
--- @param is_included Internal parameter, most of the time left as `nil`
---@param lang The language
---@param query_name The name of the query to load
---@param is_included Internal parameter, most of the time left as `nil`
function M.get_query_files(lang, query_name, is_included)
local query_path = string.format('queries/%s/%s.scm', lang, query_name)
local lang_files = dedupe_files(a.nvim_get_runtime_file(query_path, true))
@@ -112,19 +112,19 @@ local explicit_queries = setmetatable({}, {
--- This allows users to override any runtime files and/or configuration
--- set by plugins.
---
--- @param lang string: The language to use for the query
--- @param query_name string: The name of the query (i.e. "highlights")
--- @param text string: The query text (unparsed).
---@param lang string: The language to use for the query
---@param query_name string: The name of the query (i.e. "highlights")
---@param text string: The query text (unparsed).
function M.set_query(lang, query_name, text)
explicit_queries[lang][query_name] = M.parse_query(lang, text)
end
--- Returns the runtime query {query_name} for {lang}.
---
--- @param lang The language to use for the query
--- @param query_name The name of the query (i.e. "highlights")
---@param lang The language to use for the query
---@param query_name The name of the query (i.e. "highlights")
---
--- @return The corresponding query, parsed.
---@return The corresponding query, parsed.
function M.get_query(lang, query_name)
if explicit_queries[lang][query_name] then
return explicit_queries[lang][query_name]
@@ -151,10 +151,10 @@ end
--- -` info.captures` also points to `captures`.
--- - `info.patterns` contains information about predicates.
---
--- @param lang The language
--- @param query A string containing the query (s-expr syntax)
---@param lang The language
---@param query A string containing the query (s-expr syntax)
---
--- @returns The query
---@returns The query
function M.parse_query(lang, query)
language.require_language(lang)
local self = setmetatable({}, Query)
@@ -168,8 +168,8 @@ end
--- Gets the text corresponding to a given node
---
--- @param node the node
--- @param bsource The buffer or string from which the node is extracted
---@param node the node
---@param bsource The buffer or string from which the node is extracted
function M.get_node_text(node, source)
local start_row, start_col, start_byte = node:start()
local end_row, end_col, end_byte = node:end_()
@@ -327,9 +327,9 @@ local directive_handlers = {
--- Adds a new predicate to be used in queries
---
--- @param name the name of the predicate, without leading #
--- @param handler the handler function to be used
--- signature will be (match, pattern, bufnr, predicate)
---@param name the name of the predicate, without leading #
---@param handler the handler function to be used
--- signature will be (match, pattern, bufnr, predicate)
function M.add_predicate(name, handler, force)
if predicate_handlers[name] and not force then
error(string.format("Overriding %s", name))
@@ -340,9 +340,9 @@ end
--- Adds a new directive to be used in queries
---
--- @param name the name of the directive, without leading #
--- @param handler the handler function to be used
--- signature will be (match, pattern, bufnr, predicate)
---@param name the name of the directive, without leading #
---@param handler the handler function to be used
--- signature will be (match, pattern, bufnr, predicate)
function M.add_directive(name, handler, force)
if directive_handlers[name] and not force then
error(string.format("Overriding %s", name))
@@ -351,12 +351,12 @@ function M.add_directive(name, handler, force)
directive_handlers[name] = handler
end
--- @return The list of supported directives.
---@return The list of supported directives.
function M.list_directives()
return vim.tbl_keys(directive_handlers)
end
--- @return The list of supported predicates.
---@return The list of supported predicates.
function M.list_predicates()
return vim.tbl_keys(predicate_handlers)
end
@@ -465,13 +465,13 @@ end
--- end
--- </pre>
---
--- @param node The node under which the search will occur
--- @param source The source buffer or string to exctract text from
--- @param start The starting line of the search
--- @param stop The stopping line of the search (end-exclusive)
---@param node The node under which the search will occur
---@param source The source buffer or string to exctract text from
---@param start The starting line of the search
---@param stop The stopping line of the search (end-exclusive)
---
--- @returns The matching capture id
--- @returns The captured node
---@returns The matching capture id
---@returns The captured node
function Query:iter_captures(node, source, start, stop)
if type(source) == "number" and source == 0 then
source = vim.api.nvim_get_current_buf()
@@ -522,13 +522,13 @@ end
--- end
--- </pre>
---
--- @param node The node under which the search will occur
--- @param source The source buffer or string to search
--- @param start The starting line of the search
--- @param stop The stopping line of the search (end-exclusive)
---@param node The node under which the search will occur
---@param source The source buffer or string to search
---@param start The starting line of the search
---@param stop The stopping line of the search (end-exclusive)
---
--- @returns The matching pattern id
--- @returns The matching match
---@returns The matching pattern id
---@returns The matching match
function Query:iter_matches(node, source, start, stop)
if type(source) == "number" and source == 0 then
source = vim.api.nvim_get_current_buf()

24
runtime/lua/vim/uri.lua
View File

@@ -9,7 +9,7 @@ do
local schar = string.char
--- Convert hex to char
--@private
---@private
local function hex_to_char(hex)
return schar(tonumber(hex, 16))
end
@@ -38,7 +38,7 @@ do
tohex = function(b) return string.format("%02x", b) end
end
--@private
---@private
local function percent_encode_char(char)
return "%"..tohex(sbyte(char), 2)
end
@@ -50,14 +50,14 @@ do
end
--@private
---@private
local function is_windows_file_uri(uri)
return uri:match('^file:/+[a-zA-Z]:') ~= nil
end
--- Get a URI from a file path.
--@param path (string): Path to file
--@return URI
---@param path (string): Path to file
---@return URI
local function uri_from_fname(path)
local volume_path, fname = path:match("^([a-zA-Z]:)(.*)")
local is_windows = volume_path ~= nil
@@ -77,8 +77,8 @@ end
local URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9+-.]*):.*'
--- Get a URI from a bufnr
--@param bufnr (number): Buffer number
--@return URI
---@param bufnr (number): Buffer number
---@return URI
local function uri_from_bufnr(bufnr)
local fname = vim.api.nvim_buf_get_name(bufnr)
local scheme = fname:match(URI_SCHEME_PATTERN)
@@ -90,8 +90,8 @@ local function uri_from_bufnr(bufnr)
end
--- Get a filename from a URI
--@param uri (string): The URI
--@return Filename
---@param uri (string): The URI
---@return Filename
local function uri_to_fname(uri)
local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
if scheme ~= 'file' then
@@ -109,9 +109,9 @@ local function uri_to_fname(uri)
end
--- Return or create a buffer for a uri.
--@param uri (string): The URI
--@return bufnr.
--@note Creates buffer but does not load it
---@param uri (string): The URI
---@return bufnr.
---@note Creates buffer but does not load it
local function uri_to_bufnr(uri)
local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
if scheme == 'file' then

57
src/nvim/lua/vim.lua
View File

@@ -178,8 +178,8 @@ end
--- Return a human-readable representation of the given object.
---
--@see https://github.com/kikito/inspect.lua
--@see https://github.com/mpeterv/vinspect
---@see https://github.com/kikito/inspect.lua
---@see https://github.com/mpeterv/vinspect
local function inspect(object, options) -- luacheck: no unused
error(object, options) -- Stub for gen_vimdoc.py
end
@@ -203,15 +203,15 @@ do
--- end)(vim.paste)
--- </pre>
---
--@see |paste|
---@see |paste|
---
--@param lines |readfile()|-style list of lines to paste. |channel-lines|
--@param phase -1: "non-streaming" paste: the call contains all lines.
---@param lines |readfile()|-style list of lines to paste. |channel-lines|
---@param phase -1: "non-streaming" paste: the call contains all lines.
--- If paste is "streamed", `phase` indicates the stream state:
--- - 1: starts the paste (exactly once)
--- - 2: continues the paste (zero or more times)
--- - 3: ends the paste (exactly once)
--@returns false if client should cancel the paste.
---@returns false if client should cancel the paste.
function vim.paste(lines, phase)
local call = vim.api.nvim_call_function
local now = vim.loop.now()
@@ -279,7 +279,7 @@ function vim.schedule_wrap(cb)
end
--- <Docs described in |vim.empty_dict()| >
--@private
---@private
function vim.empty_dict()
return setmetatable({}, vim._empty_dict_mt)
end
@@ -338,12 +338,12 @@ end
--- Get a table of lines with start, end columns for a region marked by two points
---
--@param bufnr number of buffer
--@param pos1 (line, column) tuple marking beginning of region
--@param pos2 (line, column) tuple marking end of region
--@param regtype type of selection (:help setreg)
--@param inclusive boolean indicating whether the selection is end-inclusive
--@return region lua table of the form {linenr = {startcol,endcol}}
---@param bufnr number of buffer
---@param pos1 (line, column) tuple marking beginning of region
---@param pos2 (line, column) tuple marking end of region
---@param regtype type of selection (:help setreg)
---@param inclusive boolean indicating whether the selection is end-inclusive
---@return region lua table of the form {linenr = {startcol,endcol}}
function vim.region(bufnr, pos1, pos2, regtype, inclusive)
if not vim.api.nvim_buf_is_loaded(bufnr) then
vim.fn.bufload(bufnr)
@@ -390,9 +390,9 @@ end
--- Use to do a one-shot timer that calls `fn`
--- Note: The {fn} is |schedule_wrap|ped automatically, so API functions are
--- safe to call.
--@param fn Callback to call once `timeout` expires
--@param timeout Number of milliseconds to wait before calling `fn`
--@return timer luv timer object
---@param fn Callback to call once `timeout` expires
---@param timeout Number of milliseconds to wait before calling `fn`
---@return timer luv timer object
function vim.defer_fn(fn, timeout)
vim.validate { fn = { fn, 'c', true}; }
local timer = vim.loop.new_timer()
@@ -408,11 +408,12 @@ end
--- Notification provider
--- without a runtime, writes to :Messages
-- see :help nvim_notify
--@param msg Content of the notification to show to the user
--@param log_level Optional log level
--@param opts Dictionary with optional options (timeout, etc)
---
--- Without a runtime, writes to :Messages
---@see :help nvim_notify
---@param msg Content of the notification to show to the user
---@param log_level Optional log level
---@param opts Dictionary with optional options (timeout, etc)
function vim.notify(msg, log_level, _opts)
if log_level == vim.log.levels.ERROR then
@@ -429,21 +430,21 @@ local on_keystroke_callbacks = {}
--- Register a lua {fn} with an {id} to be run after every keystroke.
---
--@param fn function: Function to call. It should take one argument, which is a string.
---@param fn function: Function to call. It should take one argument, which is a string.
--- The string will contain the literal keys typed.
--- See |i_CTRL-V|
---
--- If {fn} is nil, it removes the callback for the associated {ns_id}
--@param ns_id number? Namespace ID. If not passed or 0, will generate and return a new
---@param ns_id number? Namespace ID. If not passed or 0, will generate and return a new
--- namespace ID from |nvim_create_namesapce()|
---
--@return number Namespace ID associated with {fn}
---@return number Namespace ID associated with {fn}
---
--@note {fn} will be automatically removed if an error occurs while calling.
---@note {fn} will be automatically removed if an error occurs while calling.
--- This is to prevent the annoying situation of every keystroke erroring
--- while trying to remove a broken callback.
--@note {fn} will not be cleared from |nvim_buf_clear_namespace()|
--@note {fn} will receive the keystrokes after mappings have been evaluated
---@note {fn} will not be cleared from |nvim_buf_clear_namespace()|
---@note {fn} will receive the keystrokes after mappings have been evaluated
function vim.register_keystroke_callback(fn, ns_id)
vim.validate {
fn = { fn, 'c', true},
@@ -459,7 +460,7 @@ function vim.register_keystroke_callback(fn, ns_id)
end
--- Function that executes the keystroke callbacks.
--@private
---@private
function vim._log_keystroke(char)
local failed_ns_ids = {}
local failed_messages = {}

4
test/functional/helpers.lua
View File

@@ -422,7 +422,7 @@ end
-- Builds an argument list for use in clear().
--
--@see clear() for parameters.
---@see clear() for parameters.
function module.new_argv(...)
local args = {unpack(module.nvim_argv)}
table.insert(args, '--headless')
@@ -573,7 +573,7 @@ function module.buf_lines(bufnr)
return module.exec_lua("return vim.api.nvim_buf_get_lines((...), 0, -1, false)", bufnr)
end
--@see buf_lines()
---@see buf_lines()
function module.curbuf_contents()
module.poke_eventloop() -- Before inspecting the buffer, do whatever.
return table.concat(module.curbuf('get_lines', 0, -1, true), '\n')

10
test/helpers.lua
View File

@@ -58,9 +58,9 @@ local check_logs_useless_lines = {
--- Invokes `fn` and includes the tail of `logfile` in the error message if it
--- fails.
---
--@param logfile Log file, defaults to $NVIM_LOG_FILE or '.nvimlog'
--@param fn Function to invoke
--@param ... Function arguments
---@param logfile Log file, defaults to $NVIM_LOG_FILE or '.nvimlog'
---@param fn Function to invoke
---@param ... Function arguments
local function dumplog(logfile, fn, ...)
-- module.validate({
-- logfile={logfile,'s',true},
@@ -102,8 +102,8 @@ end
--- Asserts that `pat` matches one or more lines in the tail of $NVIM_LOG_FILE.
---
--@param pat (string) Lua pattern to search for in the log file.
--@param logfile (string, default=$NVIM_LOG_FILE) full path to log file.
---@param pat (string) Lua pattern to search for in the log file.
---@param logfile (string, default=$NVIM_LOG_FILE) full path to log file.
function module.assert_log(pat, logfile)
logfile = logfile or os.getenv('NVIM_LOG_FILE') or '.nvimlog'
local nrlines = 10