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: Docstring format:
- Lines in the main description start with `---` - Lines in the main description start with `---`
- Special tokens start with `--@` followed by the token name: - Special tokens start with `---@` followed by the token name:
`--@see`, `--@param`, `--@returns` `---@see`, `---@param`, `---@returns`
- Limited markdown is supported. - Limited markdown is supported.
- List-items start with `-` (useful to nest or "indent") - List-items start with `-` (useful to nest or "indent")
- Use `<pre>` for code samples. - Use `<pre>` for code samples.
@@ -211,11 +211,11 @@ vim.paste in src/nvim/lua/vim.lua like this: >
--- end)() --- end)()
--- </pre> --- </pre>
--- ---
--@see |paste| ---@see |paste|
--- ---
--@param lines ... ---@param lines ...
--@param phase ... ---@param phase ...
--@returns false if client should cancel the paste. ---@returns false if client should cancel the paste.
LUA *dev-lua* 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 {buffer_client_map} table map of buffers to active
clients 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}, {bufnr}, {client_id}) *vim.lsp.diagnostic.save()*
Save diagnostics to the current buffer. Save diagnostics to the current buffer.
@@ -1526,10 +1521,6 @@ save({diagnostics}, {bufnr}, {client_id}) *vim.lsp.diagnostic.save()*
{bufnr} number {bufnr} number
{client_id} number {client_id} number
*vim.lsp.diagnostic.save_extmarks()*
save_extmarks({bufnr}, {client_id})
TODO: Documentation
set_loclist({opts}) *vim.lsp.diagnostic.set_loclist()* set_loclist({opts}) *vim.lsp.diagnostic.set_loclist()*
Sets the location list Sets the location list
@@ -1966,7 +1957,9 @@ diagnostics_to_items({diagnostics_by_bufnr}, {predicate})
Parameters: ~ Parameters: ~
{diagnostics_by_bufnr} table bufnr -> Diagnostic [] {diagnostics_by_bufnr} table bufnr -> Diagnostic []
{predicate} an optional function to filter the {predicate} an optional function to filter the
diagnostics. diagnostics. If present, only
diagnostic items matching will be
included.
Return: ~ Return: ~
table (A list of items) table (A list of items)
@@ -1999,6 +1992,8 @@ get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()*
|softtabstop| |softtabstop|
get_line({uri}, {row}) *vim.lsp.util.get_line()* get_line({uri}, {row}) *vim.lsp.util.get_line()*
Gets the zero-indexed line from the given uri.
Parameters: ~ Parameters: ~
{uri} string uri of the resource to get the line from {uri} string uri of the resource to get the line from
{row} number zero-indexed line number {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 string the line at row in filename
get_lines({uri}, {rows}) *vim.lsp.util.get_lines()* get_lines({uri}, {rows}) *vim.lsp.util.get_lines()*
Gets the zero-indexed lines from the given uri.
Parameters: ~ Parameters: ~
{uri} string uri of the resource to get the lines from {uri} string uri of the resource to get the lines from
{rows} number[] zero-indexed line numbers {rows} number[] zero-indexed line numbers
@@ -2014,9 +2011,6 @@ get_lines({uri}, {rows}) *vim.lsp.util.get_lines()*
Return: ~ Return: ~
table<number string> a table mapping rows to lines 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()* get_progress_messages() *vim.lsp.util.get_progress_messages()*
TODO: Documentation TODO: Documentation
@@ -2197,6 +2191,8 @@ preview_location({location}, {opts}) *vim.lsp.util.preview_location()*
or nil or nil
rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()* rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()*
Rename old_fname to new_fname
Parameters: ~ Parameters: ~
{opts} (table) {opts} (table)

7
runtime/doc/lua.txt
View File

@@ -1177,7 +1177,9 @@ make_dict_accessor({scope}) *vim.make_dict_accessor()*
TODO: Documentation TODO: Documentation
notify({msg}, {log_level}, {_opts}) *vim.notify()* notify({msg}, {log_level}, {_opts}) *vim.notify()*
Notification provider without a runtime, writes to :Messages Notification provider
Without a runtime, writes to :Messages
Parameters: ~ Parameters: ~
{msg} Content of the notification to show to the {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, {opts} Dictionary with optional options (timeout,
etc) etc)
See also: ~
:help nvim_notify
paste({lines}, {phase}) *vim.paste()* paste({lines}, {phase}) *vim.paste()*
Paste handler, invoked by |nvim_paste()| when a conforming UI Paste handler, invoked by |nvim_paste()| when a conforming UI
(such as the |TUI|) pastes text into the editor. (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}. --- Returns {a} if it is not nil, otherwise returns {b}.
--- ---
--@param a ---@param a
--@param b ---@param b
function F.if_nil(a, b) function F.if_nil(a, b)
if a == nil then return b end if a == nil then return b end
return a return a

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

@@ -2,7 +2,7 @@ local api = vim.api
local highlight = {} local highlight = {}
--@private ---@private
function highlight.create(higroup, hi_info, default) function highlight.create(higroup, hi_info, default)
local options = {} local options = {}
-- TODO: Add validation -- 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, " "))) vim.cmd(string.format([[highlight %s %s %s]], default and "default" or "", higroup, table.concat(options, " ")))
end end
--@private ---@private
function highlight.link(higroup, link_to, force) function highlight.link(higroup, link_to, force)
vim.cmd(string.format([[highlight%s link %s %s]], force and "!" or " default", higroup, link_to)) vim.cmd(string.format([[highlight%s link %s %s]], force and "!" or " default", higroup, link_to))
end end
@@ -20,11 +20,11 @@ end
--- Highlight range between two positions --- Highlight range between two positions
--- ---
--@param bufnr number of buffer to apply highlighting to ---@param bufnr number of buffer to apply highlighting to
--@param ns namespace to add highlight to ---@param ns namespace to add highlight to
--@param higroup highlight group to use for highlighting ---@param higroup highlight group to use for highlighting
--@param rtype type of range (:help setreg, default charwise) ---@param rtype type of range (:help setreg, default charwise)
--@param inclusive boolean indicating whether the range is end-inclusive (default false) ---@param inclusive boolean indicating whether the range is end-inclusive (default false)
function highlight.range(bufnr, ns, higroup, start, finish, rtype, inclusive) function highlight.range(bufnr, ns, higroup, start, finish, rtype, inclusive)
rtype = rtype or 'v' rtype = rtype or 'v'
inclusive = inclusive or false 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. -- TODO improve handling of scratch buffers with LSP attached.
--@private ---@private
--- Concatenates and writes a list of strings to the Vim error buffer. --- 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(...) local function err_message(...)
nvim_err_writeln(table.concat(vim.tbl_flatten{...})) nvim_err_writeln(table.concat(vim.tbl_flatten{...}))
nvim_command("redraw") nvim_command("redraw")
end end
--@private ---@private
--- Returns the buffer number for the given {bufnr}. --- 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. ---buffer if not given.
--@returns bufnr (number) Number of requested buffer ---@returns bufnr (number) Number of requested buffer
local function resolve_bufnr(bufnr) local function resolve_bufnr(bufnr)
validate { bufnr = { bufnr, 'n', true } } validate { bufnr = { bufnr, 'n', true } }
if bufnr == nil or bufnr == 0 then if bufnr == nil or bufnr == 0 then
@@ -78,21 +78,21 @@ local function resolve_bufnr(bufnr)
return bufnr return bufnr
end end
--@private ---@private
--- Called by the client when trying to call a method that's not --- Called by the client when trying to call a method that's not
--- supported in any of the servers registered for the current buffer. --- 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) 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) local msg = string.format("method %s is not supported by any of the servers registered for the current buffer", method)
log.warn(msg) log.warn(msg)
return lsp.rpc_response_error(protocol.ErrorCodes.MethodNotFound, msg) return lsp.rpc_response_error(protocol.ErrorCodes.MethodNotFound, msg)
end end
--@private ---@private
--- Checks whether a given path is a directory. --- Checks whether a given path is a directory.
--- ---
--@param filename (string) path to check ---@param filename (string) path to check
--@returns true if {filename} exists and is a directory, false otherwise ---@returns true if {filename} exists and is a directory, false otherwise
local function is_dir(filename) local function is_dir(filename)
validate{filename={filename,'s'}} validate{filename={filename,'s'}}
local stat = uv.fs_stat(filename) local stat = uv.fs_stat(filename)
@@ -108,10 +108,10 @@ local valid_encodings = {
} }
local client_index = 0 local client_index = 0
--@private ---@private
--- Returns a new, unused client id. --- Returns a new, unused client id.
--- ---
--@returns (number) client id ---@returns (number) client id
local function next_client_id() local function next_client_id()
client_index = client_index + 1 client_index = client_index + 1
return client_index return client_index
@@ -124,11 +124,11 @@ local uninitialized_clients = {}
-- Tracks all buffers attached to a client. -- Tracks all buffers attached to a client.
local all_client_active_buffers = {} local all_client_active_buffers = {}
--@private ---@private
--- Invokes a function for each LSP client attached to the buffer {bufnr}. --- Invokes a function for each LSP client attached to the buffer {bufnr}.
--- ---
--@param bufnr (Number) of buffer ---@param bufnr (Number) of buffer
--@param fn (function({client}, {client_id}, {bufnr}) Function to run on ---@param fn (function({client}, {client_id}, {bufnr}) Function to run on
---each client attached to that buffer. ---each client attached to that buffer.
local function for_each_buffer_client(bufnr, fn) local function for_each_buffer_client(bufnr, fn)
validate { 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; ON_INIT_CALLBACK_ERROR = table.maxn(lsp_rpc.client_errors) + 1;
}) })
--@private ---@private
--- Normalizes {encoding} to valid LSP encoding names. --- Normalizes {encoding} to valid LSP encoding names.
--- ---
--@param encoding (string) Encoding to normalize ---@param encoding (string) Encoding to normalize
--@returns (string) normalized encoding name ---@returns (string) normalized encoding name
local function validate_encoding(encoding) local function validate_encoding(encoding)
validate { validate {
encoding = { encoding, 's' }; 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)) or error(string.format("Invalid offset encoding %q. Must be one of: 'utf-8', 'utf-16', 'utf-32'", encoding))
end end
--@internal ---@internal
--- Parses a command invocation into the command itself and its args. If there --- 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. --- are no arguments, an empty table is returned as the second argument.
--- ---
--@param input (List) ---@param input (List)
--@returns (string) the command ---@returns (string) the command
--@returns (list of strings) its arguments ---@returns (list of strings) its arguments
function lsp._cmd_parts(input) function lsp._cmd_parts(input)
vim.validate{cmd={ vim.validate{cmd={
input, input,
@@ -192,12 +192,12 @@ function lsp._cmd_parts(input)
return cmd, cmd_args return cmd, cmd_args
end end
--@private ---@private
--- Augments a validator function with support for optional (nil) values. --- 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. ---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`. ---`nil`.
local function optional_validator(fn) local function optional_validator(fn)
return function(v) return function(v)
@@ -205,14 +205,14 @@ local function optional_validator(fn)
end end
end end
--@private ---@private
--- Validates a client configuration as given to |vim.lsp.start_client()|. --- Validates a client configuration as given to |vim.lsp.start_client()|.
--- ---
--@param config (table) ---@param config (table)
--@returns (table) "Cleaned" config, containing only the command, its ---@returns (table) "Cleaned" config, containing only the command, its
---arguments, and a valid encoding. ---arguments, and a valid encoding.
--- ---
--@see |vim.lsp.start_client()| ---@see |vim.lsp.start_client()|
local function validate_client_config(config) local function validate_client_config(config)
validate { validate {
config = { config, 't' }; config = { config, 't' };
@@ -253,11 +253,11 @@ local function validate_client_config(config)
} }
end end
--@private ---@private
--- Returns full text of buffer {bufnr} as a string. --- Returns full text of buffer {bufnr} as a string.
--- ---
--@param bufnr (number) Buffer handle, or 0 for current. ---@param bufnr (number) Buffer handle, or 0 for current.
--@returns Buffer text as string. ---@returns Buffer text as string.
local function buf_get_full_text(bufnr) local function buf_get_full_text(bufnr)
local text = table.concat(nvim_buf_get_lines(bufnr, 0, -1, true), '\n') local text = table.concat(nvim_buf_get_lines(bufnr, 0, -1, true), '\n')
if nvim_buf_get_option(bufnr, 'eol') then if nvim_buf_get_option(bufnr, 'eol') then
@@ -266,14 +266,14 @@ local function buf_get_full_text(bufnr)
return text return text
end end
--@private ---@private
--- Memoizes a function. On first run, the function return value is saved and --- Memoizes a function. On first run, the function return value is saved and
--- immediately returned on subsequent runs. If the function returns a multival, --- 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, --- only the first returned value will be memoized and returned. The function will only be run once,
--- even if it has side-effects. --- even if it has side-effects.
--- ---
--@param fn (function) Function to run ---@param fn (function) Function to run
--@returns (function) Memoized function ---@returns (function) Memoized function
local function once(fn) local function once(fn)
local value local value
local ran = false local ran = false
@@ -426,11 +426,11 @@ do
end end
--@private ---@private
--- Default handler for the 'textDocument/didOpen' LSP notification. --- Default handler for the 'textDocument/didOpen' LSP notification.
--- ---
--@param bufnr (Number) Number of the buffer, or 0 for current ---@param bufnr (Number) Number of the buffer, or 0 for current
--@param client Client object ---@param client Client object
local function text_document_did_open_handler(bufnr, client) local function text_document_did_open_handler(bufnr, client)
changetracking.init(client, bufnr) changetracking.init(client, bufnr)
if not client.resolved_capabilities.text_document_open_close then if not client.resolved_capabilities.text_document_open_close then
@@ -548,16 +548,16 @@ end
--- ---
--- The following parameters describe fields in the {config} table. --- 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. --- 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. --- 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`. --- 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` --- 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. --- pairs or both. Non-string values are coerced to string.
--- Example: --- Example:
@@ -565,7 +565,7 @@ end
--- { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; } --- { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; }
--- </pre> --- </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 --- |vim.lsp.protocol.make_client_capabilities()|, passed to the language
--- server on initialization. Hint: use make_client_capabilities() and modify --- server on initialization. Hint: use make_client_capabilities() and modify
--- its result. --- its result.
@@ -573,41 +573,41 @@ end
--- `{[vim.type_idx]=vim.types.dictionary}`, else it will be encoded as an --- `{[vim.type_idx]=vim.types.dictionary}`, else it will be encoded as an
--- array. --- 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`. --- returned to the language server if requested via `workspace/configuration`.
--- Keys are case-sensitive. --- 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. --- 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 --- language server. Defaults to root_dir if not set. See `workspaceFolders` in
--- the LSP spec --- 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. --- 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 --- or "utf-32" which is the encoding that the LSP server expects. Client does
--- not verify this is correct. --- 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 --- 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 --- the error. Other arguments may be passed depending on the error kind. See
--- |vim.lsp.client_errors| for possible errors. --- |vim.lsp.client_errors| for possible errors.
--- Use `vim.lsp.client_errors[code]` to get human-friendly name. --- 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 --- invoked before the LSP "initialize" phase, where `params` contains the
--- parameters being sent to the server and `config` is the config that was --- 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 --- passed to |vim.lsp.start_client()|. You can use this to modify parameters before
--- they are sent. --- 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 --- "initialize", where `result` is a table of `capabilities` and anything else
--- the server may send. For example, clangd sends --- the server may send. For example, clangd sends
--- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was --- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was
@@ -617,24 +617,24 @@ end
--- `workspace/didChangeConfiguration` notification should be sent --- `workspace/didChangeConfiguration` notification should be sent
--- to the server during on_init. --- 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. --- exit.
--- - code: exit code of the process --- - code: exit code of the process
--- - signal: number describing the signal used to terminate (if any) --- - signal: number describing the signal used to terminate (if any)
--- - client_id: client handle --- - 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. --- 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" --- 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 --- - allow_incremental_sync (bool, default true): Allow using incremental sync for buffer edits
--- - debounce_text_changes (number, default nil): Debounce didChange --- - debounce_text_changes (number, default nil): Debounce didChange
--- notifications to the server by the given number in milliseconds. No debounce --- notifications to the server by the given number in milliseconds. No debounce
--- occurs if nil --- 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 --- fully initialized. Use `on_init` to do any actions once
--- the client has been initialized. --- the client has been initialized.
function lsp.start_client(config) function lsp.start_client(config)
@@ -657,22 +657,22 @@ function lsp.start_client(config)
local dispatch = {} local dispatch = {}
--@private ---@private
--- Returns the handler associated with an LSP method. --- Returns the handler associated with an LSP method.
--- Returns the default handler if the user hasn't set a custom one. --- Returns the default handler if the user hasn't set a custom one.
--- ---
--@param method (string) LSP method name ---@param method (string) LSP method name
--@returns (fn) The handler for the given method, if defined, or the default from |vim.lsp.handlers| ---@returns (fn) The handler for the given method, if defined, or the default from |vim.lsp.handlers|
local function resolve_handler(method) local function resolve_handler(method)
return handlers[method] or default_handlers[method] return handlers[method] or default_handlers[method]
end end
--@private ---@private
--- Handles a notification sent by an LSP server by invoking the --- Handles a notification sent by an LSP server by invoking the
--- corresponding handler. --- corresponding handler.
--- ---
--@param method (string) LSP method name ---@param method (string) LSP method name
--@param params (table) The parameters for that method. ---@param params (table) The parameters for that method.
function dispatch.notification(method, params) function dispatch.notification(method, params)
local _ = log.debug() and log.debug('notification', method, params) local _ = log.debug() and log.debug('notification', method, params)
local handler = resolve_handler(method) local handler = resolve_handler(method)
@@ -682,11 +682,11 @@ function lsp.start_client(config)
end end
end end
--@private ---@private
--- Handles a request from an LSP server by invoking the corresponding handler. --- Handles a request from an LSP server by invoking the corresponding handler.
--- ---
--@param method (string) LSP method name ---@param method (string) LSP method name
--@param params (table) The parameters for that method ---@param params (table) The parameters for that method
function dispatch.server_request(method, params) function dispatch.server_request(method, params)
local _ = log.debug() and log.debug('server_request', method, params) local _ = log.debug() and log.debug('server_request', method, params)
local handler = resolve_handler(method) local handler = resolve_handler(method)
@@ -698,12 +698,12 @@ function lsp.start_client(config)
return nil, lsp.rpc_response_error(protocol.ErrorCodes.MethodNotFound) return nil, lsp.rpc_response_error(protocol.ErrorCodes.MethodNotFound)
end end
--@private ---@private
--- Invoked when the client operation throws an error. --- Invoked when the client operation throws an error.
--- ---
--@param code (number) Error code ---@param code (number) Error code
--@param err (...) Other arguments may be passed depending on the error kind ---@param err (...) Other arguments may be passed depending on the error kind
--@see |vim.lsp.client_errors| for possible errors. Use ---@see |vim.lsp.client_errors| for possible errors. Use
---`vim.lsp.client_errors[code]` to get a human-friendly name. ---`vim.lsp.client_errors[code]` to get a human-friendly name.
function dispatch.on_error(code, err) function dispatch.on_error(code, err)
local _ = log.error() and log.error(log_prefix, "on_error", { code = lsp.client_errors[code], err = 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
end end
--@private ---@private
--- Invoked on client exit. --- Invoked on client exit.
--- ---
--@param code (number) exit code of the process ---@param code (number) exit code of the process
--@param signal (number) the signal used to terminate (if any) ---@param signal (number) the signal used to terminate (if any)
function dispatch.on_exit(code, signal) function dispatch.on_exit(code, signal)
active_clients[client_id] = nil active_clients[client_id] = nil
uninitialized_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. -- Store the uninitialized_clients for cleanup in case we exit before initialize finishes.
uninitialized_clients[client_id] = client; uninitialized_clients[client_id] = client;
--@private ---@private
local function initialize() local function initialize()
local valid_traces = { local valid_traces = {
off = 'off'; messages = 'messages'; verbose = 'verbose'; off = 'off'; messages = 'messages'; verbose = 'verbose';
@@ -869,23 +869,23 @@ function lsp.start_client(config)
end) end)
end end
--@private ---@private
--- Sends a request to the server. --- Sends a request to the server.
--- ---
--- This is a thin wrapper around {client.rpc.request} with some additional --- This is a thin wrapper around {client.rpc.request} with some additional
--- checks for capabilities and handler availability. --- checks for capabilities and handler availability.
--- ---
--@param method (string) LSP method name. ---@param method (string) LSP method name.
--@param params (table) LSP request params. ---@param params (table) LSP request params.
--@param handler (function, optional) Response |lsp-handler| for this method. ---@param handler (function, optional) Response |lsp-handler| for this method.
--@param bufnr (number) Buffer handle (0 for current). ---@param bufnr (number) Buffer handle (0 for current).
--@returns ({status}, [request_id]): {status} is a bool indicating ---@returns ({status}, [request_id]): {status} is a bool indicating
---whether the request was successful. If it is `false`, then it will ---whether the request was successful. If it is `false`, then it will
---always be `false` (the client has shutdown). If it was ---always be `false` (the client has shutdown). If it was
---successful, then it will return {request_id} as the ---successful, then it will return {request_id} as the
---second result. You can use this with `client.cancel_request(request_id)` ---second result. You can use this with `client.cancel_request(request_id)`
---to cancel the-request. ---to cancel the-request.
--@see |vim.lsp.buf_request()| ---@see |vim.lsp.buf_request()|
function client.request(method, params, handler, bufnr) function client.request(method, params, handler, bufnr)
if not handler then if not handler then
handler = resolve_handler(method) handler = resolve_handler(method)
@@ -900,21 +900,21 @@ function lsp.start_client(config)
end) end)
end end
--@private ---@private
--- Sends a request to the server and synchronously waits for the response. --- Sends a request to the server and synchronously waits for the response.
--- ---
--- This is a wrapper around {client.request} --- This is a wrapper around {client.request}
--- ---
--@param method (string) LSP method name. ---@param method (string) LSP method name.
--@param params (table) LSP request params. ---@param params (table) LSP request params.
--@param timeout_ms (number, optional, default=1000) Maximum time in ---@param timeout_ms (number, optional, default=1000) Maximum time in
---milliseconds to wait for a result. ---milliseconds to wait for a result.
--@param bufnr (number) Buffer handle (0 for current). ---@param bufnr (number) Buffer handle (0 for current).
--@returns { err=err, result=result }, a dictionary, where `err` and `result` come from the |lsp-handler|. ---@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 ---On timeout, cancel or error, returns `(nil, err)` where `err` is a
---string describing the failure reason. If the request was unsuccessful ---string describing the failure reason. If the request was unsuccessful
---returns `nil`. ---returns `nil`.
--@see |vim.lsp.buf_request_sync()| ---@see |vim.lsp.buf_request_sync()|
function client.request_sync(method, params, timeout_ms, bufnr) function client.request_sync(method, params, timeout_ms, bufnr)
local request_result = nil local request_result = nil
local function _sync_handler(err, _, result) local function _sync_handler(err, _, result)
@@ -936,25 +936,25 @@ function lsp.start_client(config)
return request_result return request_result
end end
--@private ---@private
--- Sends a notification to an LSP server. --- Sends a notification to an LSP server.
--- ---
--@param method (string) LSP method name. ---@param method (string) LSP method name.
--@param params (optional, table) LSP request params. ---@param params (optional, table) LSP request params.
--@param bufnr (number) Buffer handle, or 0 for current. ---@param bufnr (number) Buffer handle, or 0 for current.
--@returns {status} (bool) true if the notification was successful. ---@returns {status} (bool) true if the notification was successful.
---If it is false, then it will always be false ---If it is false, then it will always be false
---(the client has shutdown). ---(the client has shutdown).
function client.notify(...) function client.notify(...)
return rpc.notify(...) return rpc.notify(...)
end end
--@private ---@private
--- Cancels a request with a given request id. --- Cancels a request with a given request id.
--- ---
--@param id (number) id of request to cancel ---@param id (number) id of request to cancel
--@returns true if any client returns true; false otherwise ---@returns true if any client returns true; false otherwise
--@see |vim.lsp.client.notify()| ---@see |vim.lsp.client.notify()|
function client.cancel_request(id) function client.cancel_request(id)
validate{id = {id, 'n'}} validate{id = {id, 'n'}}
return rpc.notify("$/cancelRequest", { id = id }) 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 -- Track this so that we can escalate automatically if we've alredy tried a
-- graceful shutdown -- graceful shutdown
local graceful_shutdown_failed = false local graceful_shutdown_failed = false
--@private ---@private
--- Stops a client, optionally with force. --- Stops a client, optionally with force.
--- ---
---By default, it will just ask the - server to shutdown without force. If ---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 --- you request to stop a client which has previously been requested to
--- shutdown, it will automatically escalate and force shutdown. --- shutdown, it will automatically escalate and force shutdown.
--- ---
--@param force (bool, optional) ---@param force (bool, optional)
function client.stop(force) function client.stop(force)
lsp.diagnostic.reset(client_id, all_buffer_active_clients) lsp.diagnostic.reset(client_id, all_buffer_active_clients)
@@ -1000,18 +1000,18 @@ function lsp.start_client(config)
end) end)
end end
--@private ---@private
--- Checks whether a client is stopped. --- 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 ---stopped; false otherwise
function client.is_stopped() function client.is_stopped()
return rpc.handle:is_closing() return rpc.handle:is_closing()
end end
--@private ---@private
--- Runs the on_attach function from the client's config if it was defined. --- 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) function client._on_attach(bufnr)
text_document_did_open_handler(bufnr, client) text_document_did_open_handler(bufnr, client)
if config.on_attach then if config.on_attach then
@@ -1025,8 +1025,8 @@ function lsp.start_client(config)
return client_id return client_id
end end
--@private ---@private
--@fn text_document_did_change_handler(_, bufnr, changedtick, firstline, lastline, new_lastline, old_byte_size, old_utf32_size, old_utf16_size) ---@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. --- Notify all attached clients that a buffer has changed.
local text_document_did_change_handler local text_document_did_change_handler
do do
@@ -1076,8 +1076,8 @@ end
--- ---
--- Without calling this, the server won't be notified of changes to a buffer. --- Without calling this, the server won't be notified of changes to a buffer.
--- ---
--- @param bufnr (number) Buffer handle, or 0 for current ---@param bufnr (number) Buffer handle, or 0 for current
--- @param client_id (number) Client id ---@param client_id (number) Client id
function lsp.buf_attach_client(bufnr, client_id) function lsp.buf_attach_client(bufnr, client_id)
validate { validate {
bufnr = {bufnr, 'n', true}; bufnr = {bufnr, 'n', true};
@@ -1158,17 +1158,17 @@ end
--- Gets a client by id, or nil if the id is invalid. --- Gets a client by id, or nil if the id is invalid.
--- The returned client may not yet be fully initialized. --- 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) function lsp.get_client_by_id(client_id)
return active_clients[client_id] or uninitialized_clients[client_id] return active_clients[client_id] or uninitialized_clients[client_id]
end end
--- Returns list of buffers attached to client_id. --- Returns list of buffers attached to client_id.
-- --
--@param client_id client id ---@param client_id client id
--@returns list of buffer ids ---@returns list of buffer ids
function lsp.get_buffers_by_client_id(client_id) function lsp.get_buffers_by_client_id(client_id)
local active_client_buffers = all_client_active_buffers[client_id] local active_client_buffers = all_client_active_buffers[client_id]
if active_client_buffers then if active_client_buffers then
@@ -1190,8 +1190,8 @@ end
--- By default asks the server to shutdown, unless stop was requested --- By default asks the server to shutdown, unless stop was requested
--- already for this client, then force-shutdown is attempted. --- already for this client, then force-shutdown is attempted.
--- ---
--@param client_id client id or |vim.lsp.client| object, or list thereof ---@param client_id client id or |vim.lsp.client| object, or list thereof
--@param force boolean (optional) shutdown forcefully ---@param force boolean (optional) shutdown forcefully
function lsp.stop_client(client_id, force) function lsp.stop_client(client_id, force)
local ids = type(client_id) == 'table' and client_id or {client_id} local ids = type(client_id) == 'table' and client_id or {client_id}
for _, id in ipairs(ids) do for _, id in ipairs(ids) do
@@ -1207,7 +1207,7 @@ end
--- Gets all active clients. --- Gets all active clients.
--- ---
--@returns Table of |vim.lsp.client| objects ---@returns Table of |vim.lsp.client| objects
function lsp.get_active_clients() function lsp.get_active_clients()
return vim.tbl_values(active_clients) return vim.tbl_values(active_clients)
end 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 --- Sends an async request for all active clients attached to the
--- buffer. --- buffer.
--- ---
--@param bufnr (number) Buffer handle, or 0 for current. ---@param bufnr (number) Buffer handle, or 0 for current.
--@param method (string) LSP method name ---@param method (string) LSP method name
--@param params (optional, table) Parameters to send to the server ---@param params (optional, table) Parameters to send to the server
--@param handler (optional, function) See |lsp-handler| ---@param handler (optional, function) See |lsp-handler|
-- If nil, follows resolution strategy defined in |lsp-handler-configuration| -- 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. --- - Map of client-id:request-id pairs for all successful requests.
--- - Function which can be used to cancel all the requests. You could instead --- - Function which can be used to cancel all the requests. You could instead
--- iterate all clients and call their `cancel_request()` methods. --- 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 ---Parameters are the same as |vim.lsp.buf_request()| but the return result and callback are
---different. ---different.
--- ---
--@param bufnr (number) Buffer handle, or 0 for current. ---@param bufnr (number) Buffer handle, or 0 for current.
--@param method (string) LSP method name ---@param method (string) LSP method name
--@param params (optional, table) Parameters to send to the server ---@param params (optional, table) Parameters to send to the server
--@param callback (function) The callback to call when all requests are finished. ---@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. -- 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 -- 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) function lsp.buf_request_all(bufnr, method, params, callback)
local request_results = {} local request_results = {}
local result_count = 0 local result_count = 0
@@ -1337,13 +1337,13 @@ end
--- Parameters are the same as |vim.lsp.buf_request()| but the return result is --- Parameters are the same as |vim.lsp.buf_request()| but the return result is
--- different. Wait maximum of {timeout_ms} (default 1000) ms. --- different. Wait maximum of {timeout_ms} (default 1000) ms.
--- ---
--@param bufnr (number) Buffer handle, or 0 for current. ---@param bufnr (number) Buffer handle, or 0 for current.
--@param method (string) LSP method name ---@param method (string) LSP method name
--@param params (optional, table) Parameters to send to the server ---@param params (optional, table) Parameters to send to the server
--@param timeout_ms (optional, number, default=1000) Maximum time in ---@param timeout_ms (optional, number, default=1000) Maximum time in
--- milliseconds to wait for a result. --- 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 --- returns `(nil, err)` where `err` is a string describing the failure
--- reason. --- reason.
function lsp.buf_request_sync(bufnr, method, params, timeout_ms) 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 end
--- Send a notification to a server --- Send a notification to a server
--@param bufnr [number] (optional): The number of the buffer ---@param bufnr [number] (optional): The number of the buffer
--@param method [string]: Name of the request method ---@param method [string]: Name of the request method
--@param params [string]: Arguments to send to the server ---@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) function lsp.buf_notify(bufnr, method, params)
validate { validate {
bufnr = { bufnr, 'n', true }; bufnr = { bufnr, 'n', true };
@@ -1385,14 +1385,14 @@ end
--- Implements 'omnifunc' compatible LSP completion. --- Implements 'omnifunc' compatible LSP completion.
--- ---
--@see |complete-functions| ---@see |complete-functions|
--@see |complete-items| ---@see |complete-items|
--@see |CompleteDone| ---@see |CompleteDone|
--- ---
--@param findstart 0 or 1, decides behavior ---@param findstart 0 or 1, decides behavior
--@param base If findstart=0, text to match against ---@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=0: column where the completion starts, or -2 or -3
--- - findstart=1: list of matches (actually just calls |complete()|) --- - findstart=1: list of matches (actually just calls |complete()|)
function lsp.omnifunc(findstart, base) function lsp.omnifunc(findstart, base)
@@ -1438,8 +1438,8 @@ end
---Checks whether a client is stopped. ---Checks whether a client is stopped.
--- ---
--@param client_id (Number) ---@param client_id (Number)
--@returns true if client is stopped, false otherwise. ---@returns true if client is stopped, false otherwise.
function lsp.client_is_stopped(client_id) function lsp.client_is_stopped(client_id)
return active_clients[client_id] == nil return active_clients[client_id] == nil
end end
@@ -1447,7 +1447,7 @@ end
--- Gets a map of client_id:client pairs for the given buffer, where each value --- Gets a map of client_id:client pairs for the given buffer, where each value
--- is a |vim.lsp.client| object. --- 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) function lsp.buf_get_clients(bufnr)
bufnr = resolve_bufnr(bufnr) bufnr = resolve_bufnr(bufnr)
local result = {} local result = {}
@@ -1472,9 +1472,9 @@ lsp.log_levels = log.levels
--- ---
--- Use `lsp.log_levels` for reverse lookup. --- 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) function lsp.set_log_level(level)
if type(level) == 'string' or type(level) == 'number' then if type(level) == 'string' or type(level) == 'number' then
log.set_level(level) log.set_level(level)
@@ -1484,7 +1484,7 @@ function lsp.set_log_level(level)
end end
--- Gets the path of the logfile used by the LSP client. --- 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() function lsp.get_log_path()
return log.get_filename() return log.get_filename()
end end
@@ -1495,8 +1495,8 @@ function lsp.for_each_buffer_client(bufnr, fn)
end end
--- Function to manage overriding defaults for LSP handlers. --- Function to manage overriding defaults for LSP handlers.
--@param handler (function) See |lsp-handler| ---@param handler (function) See |lsp-handler|
--@param override_config (table) Table containing the keys to override behavior of the {handler} ---@param override_config (table) Table containing the keys to override behavior of the {handler}
function lsp.with(handler, override_config) function lsp.with(handler, override_config)
return function(err, method, params, client_id, bufnr, 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)) 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 = {} local M = {}
--@private ---@private
--- Returns nil if {status} is false or nil, otherwise returns the rest of the --- Returns nil if {status} is false or nil, otherwise returns the rest of the
--- arguments. --- arguments.
local function ok_or_nil(status, ...) local function ok_or_nil(status, ...)
@@ -13,31 +13,31 @@ local function ok_or_nil(status, ...)
return ... return ...
end end
--@private ---@private
--- Swallows errors. --- Swallows errors.
--- ---
--@param fn Function to run ---@param fn Function to run
--@param ... Function arguments ---@param ... Function arguments
--@returns Result of `fn(...)` if there are no errors, otherwise nil. ---@returns Result of `fn(...)` if there are no errors, otherwise nil.
--- Returns nil if errors occur during {fn}, otherwise returns --- Returns nil if errors occur during {fn}, otherwise returns
local function npcall(fn, ...) local function npcall(fn, ...)
return ok_or_nil(pcall(fn, ...)) return ok_or_nil(pcall(fn, ...))
end end
--@private ---@private
--- Sends an async request to all active clients attached to the current --- Sends an async request to all active clients attached to the current
--- buffer. --- buffer.
--- ---
--@param method (string) LSP method name ---@param method (string) LSP method name
--@param params (optional, table) Parameters to send to the server ---@param params (optional, table) Parameters to send to the server
--@param handler (optional, functionnil) See |lsp-handler|. Follows |lsp-handler-resolution| ---@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. --- - Map of client-id:request-id pairs for all successful requests.
--- - Function which can be used to cancel all the requests. You could instead --- - Function which can be used to cancel all the requests. You could instead
--- iterate all clients and call their `cancel_request()` methods. --- 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) local function request(method, params, handler)
validate { validate {
method = {method, 's'}; method = {method, 's'};
@@ -49,7 +49,7 @@ end
--- Checks whether the language servers attached to the current buffer are --- Checks whether the language servers attached to the current buffer are
--- ready. --- ready.
--- ---
--@returns `true` if server responds. ---@returns `true` if server responds.
function M.server_ready() function M.server_ready()
return not not vim.lsp.buf_notify(0, "window/progress", {}) return not not vim.lsp.buf_notify(0, "window/progress", {})
end end
@@ -62,7 +62,7 @@ function M.hover()
end end
--- Jumps to the declaration of the symbol under the cursor. --- 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() function M.declaration()
local params = util.make_position_params() local params = util.make_position_params()
@@ -100,22 +100,22 @@ end
--- Retrieves the completion items at the current cursor position. Can only be --- Retrieves the completion items at the current cursor position. Can only be
--- called in Insert mode. --- 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, --- about the context in which a completion was triggered (how it was triggered,
--- and by which trigger character, if applicable) --- and by which trigger character, if applicable)
--- ---
--@see |vim.lsp.protocol.constants.CompletionTriggerKind| ---@see |vim.lsp.protocol.constants.CompletionTriggerKind|
function M.completion(context) function M.completion(context)
local params = util.make_position_params() local params = util.make_position_params()
params.context = context params.context = context
return request('textDocument/completion', params) return request('textDocument/completion', params)
end end
--@private ---@private
--- If there is more than one client that supports the given method, --- If there is more than one client that supports the given method,
--- asks the user to select one. --- 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 function select_client(method)
local clients = vim.tbl_values(vim.lsp.buf_get_clients()); local clients = vim.tbl_values(vim.lsp.buf_get_clients());
clients = vim.tbl_filter(function (client) clients = vim.tbl_filter(function (client)
@@ -146,11 +146,11 @@ end
--- Formats the current buffer. --- 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 --- Some unspecified options will be automatically derived from the current
--- Neovim options. --- 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) function M.formatting(options)
local client = select_client("textDocument/formatting") local client = select_client("textDocument/formatting")
if client == nil then return end if client == nil then return end
@@ -168,9 +168,9 @@ end
--- vim.api.nvim_command[[autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_sync()]] --- vim.api.nvim_command[[autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_sync()]]
--- </pre> --- </pre>
--- ---
--@param options Table with valid `FormattingOptions` entries ---@param options Table with valid `FormattingOptions` entries
--@param timeout_ms (number) Request timeout ---@param timeout_ms (number) Request timeout
--@see |vim.lsp.buf.formatting_seq_sync| ---@see |vim.lsp.buf.formatting_seq_sync|
function M.formatting_sync(options, timeout_ms) function M.formatting_sync(options, timeout_ms)
local client = select_client("textDocument/formatting") local client = select_client("textDocument/formatting")
if client == nil then return end 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()]] --- vim.api.nvim_command[[autocmd BufWritePre <buffer> lua vim.lsp.buf.formatting_seq_sync()]]
--- </pre> --- </pre>
--- ---
--@param options (optional, table) `FormattingOptions` entries ---@param options (optional, table) `FormattingOptions` entries
--@param timeout_ms (optional, number) Request timeout ---@param timeout_ms (optional, number) Request timeout
--@param order (optional, table) List of client names. Formatting is requested from clients ---@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 ---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. ---the remaining clients in the order as they occur in the `order` list.
function M.formatting_seq_sync(options, timeout_ms, order) function M.formatting_seq_sync(options, timeout_ms, order)
@@ -230,10 +230,10 @@ end
--- Formats a given range. --- Formats a given range.
--- ---
--@param options Table with valid `FormattingOptions` entries. ---@param options Table with valid `FormattingOptions` entries.
--@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. ---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. ---Defaults to the end of the last visual selection.
function M.range_formatting(options, start_pos, end_pos) function M.range_formatting(options, start_pos, end_pos)
local client = select_client("textDocument/rangeFormatting") local client = select_client("textDocument/rangeFormatting")
@@ -246,7 +246,7 @@ end
--- Renames all references to the symbol under the cursor. --- 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()|. ---name using |input()|.
function M.rename(new_name) function M.rename(new_name)
-- TODO(ashkan) use prepareRename -- TODO(ashkan) use prepareRename
@@ -260,8 +260,8 @@ end
--- Lists all the references to the symbol under the cursor in the quickfix window. --- Lists all the references to the symbol under the cursor in the quickfix window.
--- ---
--@param context (table) Context for the request ---@param context (table) Context for the request
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references
function M.references(context) function M.references(context)
validate { context = { context, 't', true } } validate { context = { context, 't', true } }
local params = util.make_position_params() local params = util.make_position_params()
@@ -279,7 +279,7 @@ function M.document_symbol()
request('textDocument/documentSymbol', params) request('textDocument/documentSymbol', params)
end end
--@private ---@private
local function pick_call_hierarchy_item(call_hierarchy_items) local function pick_call_hierarchy_item(call_hierarchy_items)
if not call_hierarchy_items then return end if not call_hierarchy_items then return end
if #call_hierarchy_items == 1 then if #call_hierarchy_items == 1 then
@@ -297,7 +297,7 @@ local function pick_call_hierarchy_item(call_hierarchy_items)
return choice return choice
end end
--@private ---@private
local function call_hierarchy(method) local function call_hierarchy(method)
local params = util.make_position_params() local params = util.make_position_params()
request('textDocument/prepareCallHierarchy', params, function(err, _, result) 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 --- call, the user is prompted to enter a string on the command line. An empty
--- string means no filtering is done. --- string means no filtering is done.
--- ---
--@param query (string, optional) ---@param query (string, optional)
function M.workspace_symbol(query) function M.workspace_symbol(query)
query = query or npcall(vfn.input, "Query: ") query = query or npcall(vfn.input, "Query: ")
local params = {query = query} local params = {query = query}
@@ -424,7 +424,7 @@ end
--- Requests code actions from all clients and calls the handler exactly once --- Requests code actions from all clients and calls the handler exactly once
--- with all aggregated results --- with all aggregated results
--@private ---@private
local function code_action_request(params) local function code_action_request(params)
local bufnr = vim.api.nvim_get_current_buf() local bufnr = vim.api.nvim_get_current_buf()
local method = 'textDocument/codeAction' local method = 'textDocument/codeAction'
@@ -439,9 +439,9 @@ end
--- Selects a code action from the input list that is available at the current --- Selects a code action from the input list that is available at the current
--- cursor position. --- cursor position.
-- ---
--@param context: (table, optional) Valid `CodeActionContext` object ---@param context: (table, optional) Valid `CodeActionContext` object
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction
function M.code_action(context) function M.code_action(context)
validate { context = { context, 't', true } } validate { context = { context, 't', true } }
context = context or { diagnostics = vim.lsp.diagnostic.get_line_diagnostics() } 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. --- Performs |vim.lsp.buf.code_action()| for a given range.
--- ---
--@param context: (table, optional) Valid `CodeActionContext` object ---@param context: (table, optional) Valid `CodeActionContext` object
--@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. ---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. ---Defaults to the end of the last visual selection.
function M.range_code_action(context, start_pos, end_pos) function M.range_code_action(context, start_pos, end_pos)
validate { context = { context, 't', true } } validate { context = { context, 't', true } }
@@ -467,8 +467,8 @@ end
--- Executes an LSP server command. --- Executes an LSP server command.
--- ---
--@param command A valid `ExecuteCommandParams` object ---@param command A valid `ExecuteCommandParams` object
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
function M.execute_command(command) function M.execute_command(command)
validate { validate {
command = { command.command, 's' }, command = { command.command, 's' },

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

@@ -22,11 +22,11 @@ local namespaces = setmetatable({}, {
end; end;
}) })
--@private ---@private
M.__namespaces = namespaces M.__namespaces = namespaces
--@private ---@private
local function execute_lens(lens, bufnr, client_id) local function execute_lens(lens, bufnr, client_id)
local line = lens.range.start.line local line = lens.range.start.line
api.nvim_buf_clear_namespace(bufnr, namespaces[client_id], line, line + 1) api.nvim_buf_clear_namespace(bufnr, namespaces[client_id], line, line + 1)
@@ -151,7 +151,7 @@ function M.save(lenses, bufnr, client_id)
end end
--@private ---@private
local function resolve_lenses(lenses, bufnr, client_id, callback) local function resolve_lenses(lenses, bufnr, client_id, callback)
lenses = lenses or {} lenses = lenses or {}
local num_lens = vim.tbl_count(lenses) local num_lens = vim.tbl_count(lenses)
@@ -160,7 +160,7 @@ local function resolve_lenses(lenses, bufnr, client_id, callback)
return return
end end
--@private ---@private
local function countdown() local function countdown()
num_lens = num_lens - 1 num_lens = num_lens - 1
if num_lens == 0 then 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 local if_nil = vim.F.if_nil
--@class DiagnosticSeverity ---@class DiagnosticSeverity
local DiagnosticSeverity = protocol.DiagnosticSeverity local DiagnosticSeverity = protocol.DiagnosticSeverity
local to_severity = function(severity) local to_severity = function(severity)
@@ -46,14 +46,14 @@ end
---@brief lsp-diagnostic ---@brief lsp-diagnostic
--- ---
--@class Diagnostic ---@class Diagnostic
--@field range Range ---@field range Range
--@field message string ---@field message string
--@field severity DiagnosticSeverity|nil ---@field severity DiagnosticSeverity|nil
--@field code number | string ---@field code number | string
--@field source string ---@field source string
--@field tags DiagnosticTag[] ---@field tags DiagnosticTag[]
--@field relatedInformation DiagnosticRelatedInformation[] ---@field relatedInformation DiagnosticRelatedInformation[]
local M = {} local M = {}
@@ -167,12 +167,12 @@ end
local _diagnostic_namespaces = _make_namespace_table("vim_lsp_diagnostics", true) local _diagnostic_namespaces = _make_namespace_table("vim_lsp_diagnostics", true)
local _sign_namespaces = _make_namespace_table("vim_lsp_signs", false) local _sign_namespaces = _make_namespace_table("vim_lsp_signs", false)
--@private ---@private
function M._get_diagnostic_namespace(client_id) function M._get_diagnostic_namespace(client_id)
return _diagnostic_namespaces[client_id] return _diagnostic_namespaces[client_id]
end end
--@private ---@private
function M._get_sign_namespace(client_id) function M._get_sign_namespace(client_id)
return _sign_namespaces[client_id] return _sign_namespaces[client_id]
end end
@@ -255,7 +255,7 @@ local _diagnostic_counts = function(diagnostics)
return counts return counts
end end
--@private ---@private
--- Set the different diagnostic cache after `textDocument/publishDiagnostics` --- Set the different diagnostic cache after `textDocument/publishDiagnostics`
---@param diagnostics Diagnostic[] ---@param diagnostics Diagnostic[]
---@param bufnr number ---@param bufnr number
@@ -291,7 +291,7 @@ local function set_diagnostic_cache(diagnostics, bufnr, client_id)
end end
--@private ---@private
--- Clear the cached diagnostics --- Clear the cached diagnostics
---@param bufnr number ---@param bufnr number
---@param client_id number ---@param client_id number
@@ -512,7 +512,7 @@ local _next_diagnostic = function(position, search_forward, bufnr, opts, client_
end end
end end
--@private ---@private
--- Helper function to return a position from a diagnostic --- Helper function to return a position from a diagnostic
--- ---
---@return table {row, col} ---@return table {row, col}
@@ -527,7 +527,7 @@ local function _diagnostic_pos(opts, diagnostic)
return to_position(diagnostic.range.start, bufnr) return to_position(diagnostic.range.start, bufnr)
end end
--@private ---@private
-- Move to the diagnostic position -- Move to the diagnostic position
local function _diagnostic_move_pos(name, opts, pos) local function _diagnostic_move_pos(name, opts, pos)
opts = opts or {} opts = opts or {}
@@ -858,7 +858,7 @@ end
--- Callback scheduled for after leaving insert mode --- Callback scheduled for after leaving insert mode
--- ---
--- Used to handle --- Used to handle
--@private ---@private
function M._execute_scheduled_display(bufnr, client_id) function M._execute_scheduled_display(bufnr, client_id)
local args = _bufs_waiting_to_update[bufnr][client_id] local args = _bufs_waiting_to_update[bufnr][client_id]
if not args then if not args then
@@ -924,20 +924,20 @@ end
-- Diagnostic Private Highlight Utilies {{{ -- Diagnostic Private Highlight Utilies {{{
--- Get the severity highlight name --- Get the severity highlight name
--@private ---@private
function M._get_severity_highlight_name(severity) function M._get_severity_highlight_name(severity)
return virtual_text_highlight_map[severity] return virtual_text_highlight_map[severity]
end end
--- Get floating severity highlight name --- Get floating severity highlight name
--@private ---@private
function M._get_floating_severity_highlight_name(severity) function M._get_floating_severity_highlight_name(severity)
return floating_highlight_map[severity] return floating_highlight_map[severity]
end end
--- This should be called to update the highlights for the LSP client. --- This should be called to update the highlights for the LSP client.
function M._define_default_signs_and_highlights() function M._define_default_signs_and_highlights()
--@private ---@private
local function define_default_sign(name, properties) local function define_default_sign(name, properties)
if vim.tbl_isempty(vim.fn.sign_getdefined(name)) then if vim.tbl_isempty(vim.fn.sign_getdefined(name)) then
vim.fn.sign_define(name, properties) vim.fn.sign_define(name, properties)
@@ -1054,8 +1054,8 @@ function M.on_publish_diagnostics(_, _, params, client_id, _, config)
end end
-- restores the extmarks set by M.display -- restores the extmarks set by M.display
--- @param last number last line that was changed ---@param last number last line that was changed
-- @private ---@private
local function restore_extmarks(bufnr, last) local function restore_extmarks(bufnr, last)
for client_id, extmarks in pairs(diagnostic_cache_extmarks[bufnr]) do for client_id, extmarks in pairs(diagnostic_cache_extmarks[bufnr]) do
local ns = M._get_diagnostic_namespace(client_id) local ns = M._get_diagnostic_namespace(client_id)
@@ -1084,7 +1084,7 @@ local function restore_extmarks(bufnr, last)
end end
-- caches the extmarks set by M.display -- caches the extmarks set by M.display
-- @private ---@private
local function save_extmarks(bufnr, client_id) local function save_extmarks(bufnr, client_id)
bufnr = bufnr == 0 and api.nvim_get_current_buf() or bufnr bufnr = bufnr == 0 and api.nvim_get_current_buf() or bufnr
if not diagnostic_attached_buffers[bufnr] then 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}) diagnostic_cache_extmarks[bufnr][client_id] = api.nvim_buf_get_extmarks(bufnr, ns, 0, -1, {details = true})
end end
--@private ---@private
--- Display diagnostics for the buffer, given a configuration. --- Display diagnostics for the buffer, given a configuration.
function M.display(diagnostics, bufnr, client_id, config) function M.display(diagnostics, bufnr, client_id, config)
if diagnostic_disabled[bufnr][client_id] then if diagnostic_disabled[bufnr][client_id] then
@@ -1187,10 +1187,10 @@ end
--- for redrawing diagnostics after making changes in diagnostics --- for redrawing diagnostics after making changes in diagnostics
--- configuration. |lsp-handler-configuration| --- configuration. |lsp-handler-configuration|
--- ---
--- @param bufnr (optional, number): Buffer handle, defaults to current ---@param bufnr (optional, number): Buffer handle, defaults to current
--- @param client_id (optional, number): Redraw diagnostics for the given ---@param client_id (optional, number): Redraw diagnostics for the given
--- client. The default is to redraw diagnostics for all attached --- client. The default is to redraw diagnostics for all attached
--- clients. --- clients.
function M.redraw(bufnr, client_id) function M.redraw(bufnr, client_id)
bufnr = get_bufnr(bufnr) bufnr = get_bufnr(bufnr)
if not client_id then if not client_id then
@@ -1410,10 +1410,10 @@ function M.set_loclist(opts)
end end
--- Disable diagnostics for the given buffer and client --- Disable diagnostics for the given buffer and client
--- @param bufnr (optional, number): Buffer handle, defaults to current ---@param bufnr (optional, number): Buffer handle, defaults to current
--- @param client_id (optional, number): Disable diagnostics for the given ---@param client_id (optional, number): Disable diagnostics for the given
--- client. The default is to disable diagnostics for all attached --- client. The default is to disable diagnostics for all attached
--- clients. --- clients.
-- Note that when diagnostics are disabled for a buffer, the server will still -- Note that when diagnostics are disabled for a buffer, the server will still
-- send diagnostic information and the client will still process it. The -- send diagnostic information and the client will still process it. The
-- diagnostics are simply not displayed to the user. -- diagnostics are simply not displayed to the user.
@@ -1429,10 +1429,10 @@ function M.disable(bufnr, client_id)
end end
--- Enable diagnostics for the given buffer and client --- Enable diagnostics for the given buffer and client
--- @param bufnr (optional, number): Buffer handle, defaults to current ---@param bufnr (optional, number): Buffer handle, defaults to current
--- @param client_id (optional, number): Enable diagnostics for the given ---@param client_id (optional, number): Enable diagnostics for the given
--- client. The default is to enable diagnostics for all attached --- client. The default is to enable diagnostics for all attached
--- clients. --- clients.
function M.enable(bufnr, client_id) function M.enable(bufnr, client_id)
if not client_id then if not client_id then
return vim.lsp.for_each_buffer_client(bufnr, function(client) 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 -- FIXME: DOC: Expose in vimdocs
--@private ---@private
--- Writes to error buffer. --- 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(...) local function err_message(...)
vim.notify(table.concat(vim.tbl_flatten{...}), vim.log.levels.ERROR) vim.notify(table.concat(vim.tbl_flatten{...}), vim.log.levels.ERROR)
api.nvim_command("redraw") 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 -- Error handling is done implicitly by wrapping all handlers; see end of this file
end end
--@private ---@private
local function progress_handler(_, _, params, client_id) local function progress_handler(_, _, params, client_id)
local client = vim.lsp.get_client_by_id(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) 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 --- 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 --- 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) --- 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 map_result function `((resp, bufnr) -> list)` to convert the response
--- @param entity name of the resource used in a `not found` error message ---@param entity name of the resource used in a `not found` error message
local function response_to_list(map_result, entity) local function response_to_list(map_result, entity)
return function(_, _, result, _, bufnr, config) return function(_, _, result, _, bufnr, config)
if not result or vim.tbl_isempty(result) then 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 --see: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
M['textDocument/hover'] = M.hover M['textDocument/hover'] = M.hover
--@private ---@private
--- Jumps to a location. Used as a handler for multiple LSP methods. --- Jumps to a location. Used as a handler for multiple LSP methods.
--@param _ (not used) ---@param _ (not used)
--@param method (string) LSP method name ---@param method (string) LSP method name
--@param result (table) result of LSP method; a location or a list of locations. ---@param result (table) result of LSP method; a location or a list of locations.
---(`textDocument/definition` can return `Location` or `Location[]` ---(`textDocument/definition` can return `Location` or `Location[]`
local function location_handler(_, method, result) local function location_handler(_, method, result)
if result == nil or vim.tbl_isempty(result) then 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) util.buf_highlight_references(bufnr, result)
end end
--@private ---@private
--- ---
--- Displays call hierarchy in the quickfix window. --- Displays call hierarchy in the quickfix window.
--- ---
--@param direction `"from"` for incoming calls and `"to"` for outgoing calls ---@param direction `"from"` for incoming calls and `"to"` for outgoing calls
--@returns `CallHierarchyIncomingCall[]` if {direction} is `"from"`, ---@returns `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
--@returns `CallHierarchyOutgoingCall[]` if {direction} is `"to"`, ---@returns `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,
local make_call_hierarchy_handler = function(direction) local make_call_hierarchy_handler = function(direction)
return function(_, _, result) return function(_, _, result)
if not result then return end 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 do
local path_sep = vim.loop.os_uname().version:match("Windows") and "\\" or "/" local path_sep = vim.loop.os_uname().version:match("Windows") and "\\" or "/"
--@private ---@private
local function path_join(...) local function path_join(...)
return table.concat(vim.tbl_flatten{...}, path_sep) return table.concat(vim.tbl_flatten{...}, path_sep)
end end
local logfilename = path_join(vim.fn.stdpath('cache'), 'lsp.log') local logfilename = path_join(vim.fn.stdpath('cache'), 'lsp.log')
--- Returns the log filename. --- Returns the log filename.
--@returns (string) log filename ---@returns (string) log filename
function log.get_filename() function log.get_filename()
return logfilename return logfilename
end end
@@ -77,7 +77,7 @@ end
vim.tbl_add_reverse_lookup(log.levels) vim.tbl_add_reverse_lookup(log.levels)
--- Sets the current log level. --- 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) function log.set_level(level)
if type(level) == 'string' then if type(level) == 'string' then
current_log_level = assert(log.levels[level:upper()], string.format("Invalid log level: %q", level)) 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 end
--- Checks whether the level is sufficient for logging. --- Checks whether the level is sufficient for logging.
--@param level number log level ---@param level number log level
--@returns (bool) true if would log, false if not ---@returns (bool) true if would log, false if not
function log.should_log(level) function log.should_log(level)
return level >= current_log_level return level >= current_log_level
end end

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

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

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

@@ -40,10 +40,10 @@ local loclist_type_map = {
} }
--@private ---@private
-- Check the border given by opts or the default border for the additional --- Check the border given by opts or the default border for the additional
-- size it adds to a float. --- size it adds to a float.
--@returns size of border in height and width ---@returns size of border in height and width
local function get_border_size(opts) local function get_border_size(opts)
local border = opts and opts.border or default_border local border = opts and opts.border or default_border
local height = 0 local height = 0
@@ -86,7 +86,7 @@ local function get_border_size(opts)
return { height = height, width = width } return { height = height, width = width }
end end
--@private ---@private
local function split_lines(value) local function split_lines(value)
return split(value, '\n', true) return split(value, '\n', true)
end end
@@ -95,11 +95,11 @@ end
--- ---
--- CAUTION: Changes in-place! --- CAUTION: Changes in-place!
--- ---
--@param lines (table) Original list of strings ---@param lines (table) Original list of strings
--@param A (table) Start position; a 2-tuple of {line, col} numbers ---@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 B (table) End position; a 2-tuple of {line, col} numbers
--@param new_lines A list of strings to replace the original ---@param new_lines A list of strings to replace the original
--@returns (table) The modified {lines} object ---@returns (table) The modified {lines} object
function M.set_lines(lines, A, B, new_lines) function M.set_lines(lines, A, B, new_lines)
-- 0-indexing to 1-indexing -- 0-indexing to 1-indexing
local i_0 = A[1] + 1 local i_0 = A[1] + 1
@@ -133,7 +133,7 @@ function M.set_lines(lines, A, B, new_lines)
return lines return lines
end end
--@private ---@private
local function sort_by_key(fn) local function sort_by_key(fn)
return function(a,b) return function(a,b)
local ka, kb = fn(a), fn(b) local ka, kb = fn(a), fn(b)
@@ -147,12 +147,12 @@ local function sort_by_key(fn)
return false return false
end end
end end
--@private ---@private
local edit_sort_key = sort_by_key(function(e) local edit_sort_key = sort_by_key(function(e)
return {e.A[1], e.A[2], e.i} return {e.A[1], e.A[2], e.i}
end) end)
--@private ---@private
--- Position is a https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position --- 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 --- Returns a zero-indexed column, since set_lines() does the conversion to
--- 1-indexed --- 1-indexed
@@ -238,8 +238,8 @@ function M.get_progress_messages()
end end
--- Applies a list of text edits to a buffer. --- Applies a list of text edits to a buffer.
--@param text_edits (table) list of `TextEdit` objects ---@param text_edits (table) list of `TextEdit` objects
--@param buf_nr (number) Buffer id ---@param buf_nr (number) Buffer id
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit
function M.apply_text_edits(text_edits, bufnr) function M.apply_text_edits(text_edits, bufnr)
if not next(text_edits) then return end if not next(text_edits) then return end
@@ -295,11 +295,11 @@ end
-- function M.glob_to_regex(glob) -- function M.glob_to_regex(glob)
-- end -- end
--@private ---@private
--- Finds the first line and column of the difference between old and new lines --- Finds the first line and column of the difference between old and new lines
--@param old_lines table list of lines ---@param old_lines table list of lines
--@param new_lines table list of lines ---@param new_lines table list of lines
--@returns (int, int) start_line_idx and start_col_idx of range ---@returns (int, int) start_line_idx and start_col_idx of range
local function first_difference(old_lines, new_lines, start_line_idx) local function first_difference(old_lines, new_lines, start_line_idx)
local line_count = math.min(#old_lines, #new_lines) local line_count = math.min(#old_lines, #new_lines)
if line_count == 0 then return 1, 1 end 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 end
--@private ---@private
--- Finds the last line and column of the differences between old and new lines --- Finds the last line and column of the differences between old and new lines
--@param old_lines table list of lines ---@param old_lines table list of lines
--@param new_lines table list of lines ---@param new_lines table list of lines
--@param start_char integer First different character idx of range ---@param start_char integer First different character idx of range
--@returns (int, int) end_line_idx and end_col_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 function last_difference(old_lines, new_lines, start_char, end_line_idx)
local line_count = math.min(#old_lines, #new_lines) local line_count = math.min(#old_lines, #new_lines)
if line_count == 0 then return 0,0 end 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 end
--@private ---@private
--- Get the text of the range defined by start and end line/column --- Get the text of the range defined by start and end line/column
--@param lines table list of lines ---@param lines table list of lines
--@param start_char integer First different character idx of range ---@param start_char integer First different character idx of range
--@param end_char integer Last 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 start_line integer First different line idx of range
--@param end_line integer Last different line idx of range ---@param end_line integer Last different line idx of range
--@returns string text extracted from defined region ---@returns string text extracted from defined region
local function extract_text(lines, start_line, start_char, end_line, end_char) local function extract_text(lines, start_line, start_char, end_line, end_char)
if start_line == #lines + end_line + 1 then if start_line == #lines + end_line + 1 then
if end_line == 0 then return '' end 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 return result
end end
--@private ---@private
--- Compute the length of the substituted range --- Compute the length of the substituted range
--@param lines table list of lines ---@param lines table list of lines
--@param start_char integer First different character idx of range ---@param start_char integer First different character idx of range
--@param end_char integer Last 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 start_line integer First different line idx of range
--@param end_line integer Last 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 ---@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 function compute_length(lines, start_line, start_char, end_line, end_char)
local adj_end_line = #lines + end_line + 1 local adj_end_line = #lines + end_line + 1
local adj_end_char local adj_end_char
@@ -424,12 +424,12 @@ local function compute_length(lines, start_line, start_char, end_line, end_char)
end end
--- Returns the range table for the difference between old and new lines --- Returns the range table for the difference between old and new lines
--@param old_lines table list of lines ---@param old_lines table list of lines
--@param new_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 start_line_idx int line to begin search for first difference
--@param end_line_idx int line to begin search for last difference ---@param end_line_idx int line to begin search for last difference
--@param offset_encoding string encoding requested by language server ---@param offset_encoding string encoding requested by language server
--@returns table start_line_idx and start_col_idx of range ---@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) 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 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), 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 --- Can be used to extract the completion items from a
--- `textDocument/completion` request, which may return one of --- `textDocument/completion` request, which may return one of
--- `CompletionItem[]`, `CompletionList` or null. --- `CompletionItem[]`, `CompletionList` or null.
--@param result (table) The result of a `textDocument/completion` request ---@param result (table) The result of a `textDocument/completion` request
--@returns (table) List of completion items ---@returns (table) List of completion items
--@see https://microsoft.github.io/language-server-protocol/specification#textDocument_completion ---@see https://microsoft.github.io/language-server-protocol/specification#textDocument_completion
function M.extract_completion_items(result) function M.extract_completion_items(result)
if type(result) == 'table' and result.items then if type(result) == 'table' and result.items then
-- result is a `CompletionList` -- 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) M.apply_text_edits(text_document_edit.edits, bufnr)
end end
--@private ---@private
--- Recursively parses snippets in a completion entry. --- Recursively parses snippets in a completion entry.
--- ---
--@param input (string) Snippet text to parse for snippets ---@param input (string) Snippet text to parse for snippets
--@param inner (bool) Whether this function is being called recursively ---@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 ---@returns 2-tuple of strings: The first is the parsed result, the second is the
---unparsed rest of the input ---unparsed rest of the input
local function parse_snippet_rec(input, inner) local function parse_snippet_rec(input, inner)
local res = "" local res = ""
@@ -577,28 +577,28 @@ end
--- Parses snippets in a completion entry. --- Parses snippets in a completion entry.
--- ---
--@param input (string) unparsed snippet ---@param input (string) unparsed snippet
--@returns (string) parsed snippet ---@returns (string) parsed snippet
function M.parse_snippet(input) function M.parse_snippet(input)
local res, _ = parse_snippet_rec(input, false) local res, _ = parse_snippet_rec(input, false)
return res return res
end end
--@private ---@private
--- Sorts by CompletionItem.sortText. --- 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) local function sort_completion_items(items)
table.sort(items, function(a, b) table.sort(items, function(a, b)
return (a.sortText or a.label) < (b.sortText or b.label) return (a.sortText or a.label) < (b.sortText or b.label)
end) end)
end end
--@private ---@private
--- Returns text that should be inserted when selecting completion item. The --- Returns text that should be inserted when selecting completion item. The
--- precedence is as follows: textEdit.newText > insertText > label --- 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) local function get_completion_word(item)
if item.textEdit ~= nil and item.textEdit.newText ~= nil and item.textEdit.newText ~= "" then if item.textEdit ~= nil and item.textEdit.newText ~= nil and item.textEdit.newText ~= "" then
local insert_text_format = protocol.InsertTextFormat[item.insertTextFormat] local insert_text_format = protocol.InsertTextFormat[item.insertTextFormat]
@@ -618,7 +618,7 @@ local function get_completion_word(item)
return item.label return item.label
end end
--@private ---@private
--- Some language servers return complementary candidates whose prefixes do not --- Some language servers return complementary candidates whose prefixes do not
--- match are also returned. So we exclude completion candidates whose prefix --- match are also returned. So we exclude completion candidates whose prefix
--- does not match. --- does not match.
@@ -633,9 +633,9 @@ end
--- the client must handle it properly even if it receives a value outside the --- the client must handle it properly even if it receives a value outside the
--- specification. --- specification.
--- ---
--@param completion_item_kind (`vim.lsp.protocol.completionItemKind`) ---@param completion_item_kind (`vim.lsp.protocol.completionItemKind`)
--@returns (`vim.lsp.protocol.completionItemKind`) ---@returns (`vim.lsp.protocol.completionItemKind`)
--@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
function M._get_completion_item_kind_name(completion_item_kind) function M._get_completion_item_kind_name(completion_item_kind)
return protocol.CompletionItemKind[completion_item_kind] or "Unknown" return protocol.CompletionItemKind[completion_item_kind] or "Unknown"
end end
@@ -643,12 +643,12 @@ end
--- Turns the result of a `textDocument/completion` request into vim-compatible --- Turns the result of a `textDocument/completion` request into vim-compatible
--- |complete-items|. --- |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[]`, ---|vim.lsp.buf.completion()|, which may be one of `CompletionItem[]`,
--- `CompletionList` or `null` --- `CompletionList` or `null`
--@param prefix (string) the prefix to filter the completion items ---@param prefix (string) the prefix to filter the completion items
--@returns { matches = complete-items table, incomplete = bool } ---@returns { matches = complete-items table, incomplete = bool }
--@see |complete-items| ---@see |complete-items|
function M.text_document_completion_list_to_complete_items(result, prefix) function M.text_document_completion_list_to_complete_items(result, prefix)
local items = M.extract_completion_items(result) local items = M.extract_completion_items(result)
if vim.tbl_isempty(items) then if vim.tbl_isempty(items) then
@@ -698,8 +698,8 @@ end
--- Rename old_fname to new_fname --- Rename old_fname to new_fname
-- ---
--@param opts (table) ---@param opts (table)
-- overwrite? bool -- overwrite? bool
-- ignoreIfExists? bool -- ignoreIfExists? bool
function M.rename(old_fname, new_fname, opts) function M.rename(old_fname, new_fname, opts)
@@ -754,8 +754,8 @@ end
--- Applies a `WorkspaceEdit`. --- Applies a `WorkspaceEdit`.
--- ---
--@param workspace_edit (table) `WorkspaceEdit` ---@param workspace_edit (table) `WorkspaceEdit`
-- @see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit --see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit
function M.apply_workspace_edit(workspace_edit) function M.apply_workspace_edit(workspace_edit)
if workspace_edit.documentChanges then if workspace_edit.documentChanges then
for idx, change in ipairs(workspace_edit.documentChanges) do for idx, change in ipairs(workspace_edit.documentChanges) do
@@ -794,10 +794,10 @@ end
--- window for `textDocument/hover`, for parsing the result of --- window for `textDocument/hover`, for parsing the result of
--- `textDocument/signatureHelp`, and potentially others. --- `textDocument/signatureHelp`, and potentially others.
--- ---
--@param input (`MarkedString` | `MarkedString[]` | `MarkupContent`) ---@param input (`MarkedString` | `MarkedString[]` | `MarkupContent`)
--@param contents (table, optional, default `{}`) List of strings to extend with converted lines ---@param contents (table, optional, default `{}`) List of strings to extend with converted lines
--@returns {contents}, extended with lines of converted markdown. ---@returns {contents}, extended with lines of converted markdown.
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
function M.convert_input_to_markdown_lines(input, contents) function M.convert_input_to_markdown_lines(input, contents)
contents = contents or {} contents = contents or {}
-- MarkedString variation 1 -- MarkedString variation 1
@@ -844,11 +844,11 @@ end
--- Converts `textDocument/SignatureHelp` response to markdown lines. --- Converts `textDocument/SignatureHelp` response to markdown lines.
--- ---
--@param signature_help Response of `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 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 ---@param triggers optional list of trigger characters from the lsp server. used to better determine parameter offsets
--@returns list of lines of converted markdown. ---@returns list of lines of converted markdown.
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp ---@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) function M.convert_signature_help_to_markdown_lines(signature_help, ft, triggers)
if not signature_help.signatures then if not signature_help.signatures then
return return
@@ -943,10 +943,10 @@ end
--- Creates a table with sensible default options for a floating window. The --- Creates a table with sensible default options for a floating window. The
--- table can be passed to |nvim_open_win()|. --- table can be passed to |nvim_open_win()|.
--- ---
--@param width (number) window width (in character cells) ---@param width (number) window width (in character cells)
--@param height (number) window height (in character cells) ---@param height (number) window height (in character cells)
--@param opts (table, optional) ---@param opts (table, optional)
--@returns (table) Options ---@returns (table) Options
function M.make_floating_popup_options(width, height, opts) function M.make_floating_popup_options(width, height, opts)
validate { validate {
opts = { opts, 't', true }; opts = { opts, 't', true };
@@ -997,8 +997,8 @@ end
--- Jumps to a location. --- Jumps to a location.
--- ---
--@param location (`Location`|`LocationLink`) ---@param location (`Location`|`LocationLink`)
--@returns `true` if the jump succeeded ---@returns `true` if the jump succeeded
function M.jump_to_location(location) function M.jump_to_location(location)
-- location may be Location or LocationLink -- location may be Location or LocationLink
local uri = location.uri or location.targetUri local uri = location.uri or location.targetUri
@@ -1028,8 +1028,8 @@ end
--- - for Location, range is shown (e.g., function definition) --- - for Location, range is shown (e.g., function definition)
--- - for LocationLink, targetRange is shown (e.g., body of function definition) --- - for LocationLink, targetRange is shown (e.g., body of function definition)
--- ---
--@param location a single `Location` or `LocationLink` ---@param location a single `Location` or `LocationLink`
--@returns (bufnr,winnr) buffer and window number of floating window or nil ---@returns (bufnr,winnr) buffer and window number of floating window or nil
function M.preview_location(location, opts) function M.preview_location(location, opts)
-- location may be LocationLink or Location (more useful for the former) -- location may be LocationLink or Location (more useful for the former)
local uri = location.targetUri or location.uri 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) return M.open_floating_preview(contents, syntax, opts)
end end
--@private ---@private
local function find_window_by_var(name, value) local function find_window_by_var(name, value)
for _, win in ipairs(api.nvim_list_wins()) do for _, win in ipairs(api.nvim_list_wins()) do
if npcall(api.nvim_win_get_var, win, name) == value then if npcall(api.nvim_win_get_var, win, name) == value then
@@ -1088,10 +1088,10 @@ function M._trim(contents, opts)
return contents return contents
end end
-- Generates a table mapping markdown code block lang to vim syntax, --- Generates a table mapping markdown code block lang to vim syntax,
-- based on g:markdown_fenced_languages --- based on g:markdown_fenced_languages
-- @return a table of lang -> syntax mappings ---@return a table of lang -> syntax mappings
-- @private ---@private
local function get_markdown_fences() local function get_markdown_fences()
local fences = {} local fences = {}
for _, fence in pairs(vim.g.markdown_fenced_languages or {}) do 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) vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, stripped)
local idx = 1 local idx = 1
--@private ---@private
-- keep track of syntaxes we already inlcuded. -- keep track of syntaxes we already inlcuded.
-- no need to include the same syntax more than once -- no need to include the same syntax more than once
local langs = {} local langs = {}
@@ -1276,26 +1276,26 @@ end
--- Creates autocommands to close a preview window when events happen. --- Creates autocommands to close a preview window when events happen.
--- ---
--@param events (table) list of events ---@param events (table) list of events
--@param winnr (number) window id of preview window ---@param winnr (number) window id of preview window
--@see |autocmd-events| ---@see |autocmd-events|
function M.close_preview_autocmd(events, winnr) function M.close_preview_autocmd(events, winnr)
if #events > 0 then if #events > 0 then
api.nvim_command("autocmd "..table.concat(events, ',').." <buffer> ++once lua pcall(vim.api.nvim_win_close, "..winnr..", true)") api.nvim_command("autocmd "..table.concat(events, ',').." <buffer> ++once lua pcall(vim.api.nvim_win_close, "..winnr..", true)")
end end
end end
--@internal ---@internal
--- Computes size of float needed to show contents (with optional wrapping) --- Computes size of float needed to show contents (with optional wrapping)
--- ---
--@param contents table of lines to show in window ---@param contents table of lines to show in window
--@param opts dictionary with optional fields ---@param opts dictionary with optional fields
-- - height of floating window --- - height of floating window
-- - width of floating window --- - width of floating window
-- - wrap_at character to wrap at for computing height --- - wrap_at character to wrap at for computing height
-- - max_width maximal width of floating window --- - max_width maximal width of floating window
-- - max_height maximal height of floating window --- - max_height maximal height of floating window
--@returns width,height size of float ---@returns width,height size of float
function M._make_floating_popup_size(contents, opts) function M._make_floating_popup_size(contents, opts)
validate { validate {
contents = { contents, 't' }; contents = { contents, 't' };
@@ -1362,9 +1362,9 @@ end
--- Shows contents in a floating window. --- Shows contents in a floating window.
--- ---
--@param contents table of lines to show in window ---@param contents table of lines to show in window
--@param syntax string of syntax to set for opened buffer ---@param syntax string of syntax to set for opened buffer
--@param opts dictionary with optional fields ---@param opts dictionary with optional fields
--- - height of floating window --- - height of floating window
--- - width of floating window --- - width of floating window
--- - wrap boolean enable wrapping of long lines (defaults to true) --- - 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 --- - focus_id if a popup with this id is opened, then focus it
--- - close_events list of events that closes the floating window --- - close_events list of events that closes the floating window
--- - focusable (boolean, default true): Make float focusable --- - 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 ---preview window
function M.open_floating_preview(contents, syntax, opts) function M.open_floating_preview(contents, syntax, opts)
validate { validate {
@@ -1474,7 +1474,7 @@ do --[[ References ]]
--- Removes document highlights from a buffer. --- Removes document highlights from a buffer.
--- ---
--@param bufnr buffer id ---@param bufnr buffer id
function M.buf_clear_references(bufnr) function M.buf_clear_references(bufnr)
validate { bufnr = {bufnr, 'n', true} } validate { bufnr = {bufnr, 'n', true} }
api.nvim_buf_clear_namespace(bufnr, reference_ns, 0, -1) 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. --- Shows a list of document highlights for a certain buffer.
--- ---
--@param bufnr buffer id ---@param bufnr buffer id
--@param references List of `DocumentHighlight` objects to highlight ---@param references List of `DocumentHighlight` objects to highlight
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#documentHighlight ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#documentHighlight
function M.buf_highlight_references(bufnr, references) function M.buf_highlight_references(bufnr, references)
validate { bufnr = {bufnr, 'n', true} } validate { bufnr = {bufnr, 'n', true} }
@@ -1505,24 +1505,24 @@ local position_sort = sort_by_key(function(v)
return {v.start.line, v.start.character} return {v.start.line, v.start.character}
end) 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. -- For non-file uris, we load the buffer and get the line.
-- If a loaded buffer exists, then that is used. -- 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. -- 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) function M.get_line(uri, row)
return M.get_lines(uri, { row })[row] return M.get_lines(uri, { row })[row]
end 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. -- For non-file uris, we load the buffer and get the lines.
-- If a loaded buffer exists, then that is used. -- 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. -- 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) function M.get_lines(uri, rows)
rows = type(rows) == "table" and rows or { 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 --- Returns the items with the byte position calculated correctly and in sorted
--- order, for display in quickfix and location lists. --- order, for display in quickfix and location lists.
--- ---
--@param locations (table) list of `Location`s or `LocationLink`s ---@param locations (table) list of `Location`s or `LocationLink`s
--@returns (table) list of items ---@returns (table) list of items
function M.locations_to_items(locations) function M.locations_to_items(locations)
local items = {} local items = {}
local grouped = setmetatable({}, { local grouped = setmetatable({}, {
@@ -1648,7 +1648,7 @@ end
--- Can be obtained with e.g. |vim.lsp.util.locations_to_items()|. --- Can be obtained with e.g. |vim.lsp.util.locations_to_items()|.
--- Defaults to current window. --- Defaults to current window.
--- ---
--@param items (table) list of items ---@param items (table) list of items
function M.set_loclist(items, win_id) function M.set_loclist(items, win_id)
vim.fn.setloclist(win_id or 0, {}, ' ', { vim.fn.setloclist(win_id or 0, {}, ' ', {
title = 'Language Server'; title = 'Language Server';
@@ -1659,7 +1659,7 @@ end
--- Fills quickfix list with given list of items. --- Fills quickfix list with given list of items.
--- Can be obtained with e.g. |vim.lsp.util.locations_to_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) function M.set_qflist(items)
vim.fn.setqflist({}, ' ', { vim.fn.setqflist({}, ' ', {
title = 'Language Server'; title = 'Language Server';
@@ -1676,9 +1676,9 @@ end
--- Converts symbols to quickfix list items. --- Converts symbols to quickfix list items.
--- ---
--@param symbols DocumentSymbol[] or SymbolInformation[] ---@param symbols DocumentSymbol[] or SymbolInformation[]
function M.symbols_to_items(symbols, bufnr) function M.symbols_to_items(symbols, bufnr)
--@private ---@private
local function _symbols_to_items(_symbols, _items, _bufnr) local function _symbols_to_items(_symbols, _items, _bufnr)
for _, symbol in ipairs(_symbols) do for _, symbol in ipairs(_symbols) do
if symbol.location then -- SymbolInformation type if symbol.location then -- SymbolInformation type
@@ -1714,8 +1714,8 @@ function M.symbols_to_items(symbols, bufnr)
end end
--- Removes empty lines from the beginning and end. --- Removes empty lines from the beginning and end.
--@param lines (table) list of lines to trim ---@param lines (table) list of lines to trim
--@returns (table) trimmed list of lines ---@returns (table) trimmed list of lines
function M.trim_empty_lines(lines) function M.trim_empty_lines(lines)
local start = 1 local start = 1
for i = 1, #lines do for i = 1, #lines do
@@ -1739,8 +1739,8 @@ end
--- ---
--- CAUTION: Modifies the input in-place! --- CAUTION: Modifies the input in-place!
--- ---
--@param lines (table) list of lines ---@param lines (table) list of lines
--@returns (string) filetype or 'markdown' if it was unchanged. ---@returns (string) filetype or 'markdown' if it was unchanged.
function M.try_trim_markdown_code_blocks(lines) function M.try_trim_markdown_code_blocks(lines)
local language_id = lines[1]:match("^```(.*)") local language_id = lines[1]:match("^```(.*)")
if language_id then if language_id then
@@ -1763,7 +1763,7 @@ function M.try_trim_markdown_code_blocks(lines)
end end
local str_utfindex = vim.str_utfindex local str_utfindex = vim.str_utfindex
--@private ---@private
local function make_position_param() local function make_position_param()
local row, col = unpack(api.nvim_win_get_cursor(0)) local row, col = unpack(api.nvim_win_get_cursor(0))
row = row - 1 row = row - 1
@@ -1777,8 +1777,8 @@ end
--- Creates a `TextDocumentPositionParams` object for the current buffer and cursor position. --- Creates a `TextDocumentPositionParams` object for the current buffer and cursor position.
--- ---
--@returns `TextDocumentPositionParams` object ---@returns `TextDocumentPositionParams` object
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
function M.make_position_params() function M.make_position_params()
return { return {
textDocument = M.make_text_document_params(); textDocument = M.make_text_document_params();
@@ -1791,7 +1791,7 @@ end
--- `textDocument/codeAction`, `textDocument/colorPresentation`, --- `textDocument/codeAction`, `textDocument/colorPresentation`,
--- `textDocument/rangeFormatting`. --- `textDocument/rangeFormatting`.
--- ---
--@returns { textDocument = { uri = `current_file_uri` }, range = { start = ---@returns { textDocument = { uri = `current_file_uri` }, range = { start =
---`current_position`, end = `current_position` } } ---`current_position`, end = `current_position` } }
function M.make_range_params() function M.make_range_params()
local position = make_position_param() local position = make_position_param()
@@ -1804,11 +1804,11 @@ end
--- Using the given range in the current buffer, creates an object that --- Using the given range in the current buffer, creates an object that
--- is similar to |vim.lsp.util.make_range_params()|. --- 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. ---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. ---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` } } ---`start_position`, end = `end_position` } }
function M.make_given_range_params(start_pos, end_pos) function M.make_given_range_params(start_pos, end_pos)
validate { validate {
@@ -1844,23 +1844,23 @@ end
--- Creates a `TextDocumentIdentifier` object for the current buffer. --- Creates a `TextDocumentIdentifier` object for the current buffer.
--- ---
--@returns `TextDocumentIdentifier` ---@returns `TextDocumentIdentifier`
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
function M.make_text_document_params() function M.make_text_document_params()
return { uri = vim.uri_from_bufnr(0) } return { uri = vim.uri_from_bufnr(0) }
end end
--- Create the workspace params --- Create the workspace params
--@param added ---@param added
--@param removed ---@param removed
function M.make_workspace_params(added, removed) function M.make_workspace_params(added, removed)
return { event = { added = added; removed = removed; } } return { event = { added = added; removed = removed; } }
end end
--- Returns visual width of tabstop. --- Returns visual width of tabstop.
--- ---
--@see |softtabstop| ---@see |softtabstop|
--@param bufnr (optional, number): Buffer handle, defaults to current ---@param bufnr (optional, number): Buffer handle, defaults to current
--@returns (number) tabstop visual width ---@returns (number) tabstop visual width
function M.get_effective_tabstop(bufnr) function M.get_effective_tabstop(bufnr)
validate { bufnr = {bufnr, 'n', true} } validate { bufnr = {bufnr, 'n', true} }
local bo = bufnr and vim.bo[bufnr] or vim.bo 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. --- Creates a `DocumentFormattingParams` object for the current buffer and cursor position.
--- ---
--@param options Table with valid `FormattingOptions` entries ---@param options Table with valid `FormattingOptions` entries
--@returns `DocumentFormattingParams` object ---@returns `DocumentFormattingParams` object
--@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
function M.make_formatting_params(options) function M.make_formatting_params(options)
validate { options = {options, 't', true} } validate { options = {options, 't', true} }
options = vim.tbl_extend('keep', options or {}, { 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. --- Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer.
--- ---
--@param buf buffer id (0 for current) ---@param buf buffer id (0 for current)
--@param row 0-indexed line ---@param row 0-indexed line
--@param col 0-indexed byte offset in 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} ---@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) function M.character_offset(bufnr, row, col)
local uri = vim.uri_from_bufnr(bufnr) local uri = vim.uri_from_bufnr(bufnr)
local line = M.get_line(uri, row) local line = M.get_line(uri, row)
@@ -1903,9 +1903,9 @@ end
--- Helper function to return nested values in language server settings --- Helper function to return nested values in language server settings
--- ---
--@param settings a table of language server settings ---@param settings a table of language server settings
--@param section a string indicating the field of the settings table ---@param section a string indicating the field of the settings table
--@returns (table or string) The value of settings accessed via section ---@returns (table or string) The value of settings accessed via section
function M.lookup_section(settings, section) function M.lookup_section(settings, section)
for part in vim.gsplit(section, '.', true) do for part in vim.gsplit(section, '.', true) do
settings = settings[part] settings = settings[part]
@@ -1920,10 +1920,10 @@ end
--- Convert diagnostics grouped by bufnr to a list of items for use in the --- Convert diagnostics grouped by bufnr to a list of items for use in the
--- quickfix or location list. --- quickfix or location list.
--- ---
--@param diagnostics_by_bufnr table bufnr -> Diagnostic[] ---@param diagnostics_by_bufnr table bufnr -> Diagnostic[]
--@param predicate an optional function to filter the diagnostics. ---@param predicate an optional function to filter the diagnostics.
-- If present, only diagnostic items matching will be included. --- If present, only diagnostic items matching will be included.
--@return table (A list of items) ---@return table (A list of items)
function M.diagnostics_to_items(diagnostics_by_bufnr, predicate) function M.diagnostics_to_items(diagnostics_by_bufnr, predicate)
local items = {} local items = {}
for bufnr, diagnostics in pairs(diagnostics_by_bufnr or {}) do 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 --- same functions as those in the input table. Userdata and threads are not
--- copied and will throw an error. --- copied and will throw an error.
--- ---
--@param orig Table to copy ---@param orig Table to copy
--@returns New table of copied keys and (nested) values. ---@returns New table of copied keys and (nested) values.
function vim.deepcopy(orig) end -- luacheck: no unused function vim.deepcopy(orig) end -- luacheck: no unused
vim.deepcopy = (function() vim.deepcopy = (function()
local function _id(v) local function _id(v)
@@ -52,14 +52,14 @@ end)()
--- Splits a string at each instance of a separator. --- Splits a string at each instance of a separator.
--- ---
--@see |vim.split()| ---@see |vim.split()|
--@see https://www.lua.org/pil/20.2.html ---@see https://www.lua.org/pil/20.2.html
--@see http://lua-users.org/wiki/StringLibraryTutorial ---@see http://lua-users.org/wiki/StringLibraryTutorial
--- ---
--@param s String to split ---@param s String to split
--@param sep Separator string or pattern ---@param sep Separator string or pattern
--@param plain If `true` use `sep` literally (passed to String.find) ---@param plain If `true` use `sep` literally (passed to String.find)
--@returns Iterator over the split components ---@returns Iterator over the split components
function vim.gsplit(s, sep, plain) function vim.gsplit(s, sep, plain)
vim.validate{s={s,'s'},sep={sep,'s'},plain={plain,'b',true}} 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'} --- split(x*yz*o, "*", true) --> {'x','yz','o'}
--- </pre> --- </pre>
-- --
--@see |vim.gsplit()| ---@see |vim.gsplit()|
--- ---
--@param s String to split ---@param s String to split
--@param sep Separator string or pattern ---@param sep Separator string or pattern
--@param plain If `true` use `sep` literally (passed to String.find) ---@param plain If `true` use `sep` literally (passed to String.find)
--@returns List-like table of the split components. ---@returns List-like table of the split components.
function vim.split(s,sep,plain) function vim.split(s,sep,plain)
local t={} for c in vim.gsplit(s, sep, plain) do table.insert(t,c) end local t={} for c in vim.gsplit(s, sep, plain) do table.insert(t,c) end
return t return t
@@ -115,10 +115,10 @@ end
--- Return a list of all keys used in a table. --- Return a list of all keys used in a table.
--- However, the order of the return table of keys is not guaranteed. --- 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 ---@param t Table
--@returns list of keys ---@returns list of keys
function vim.tbl_keys(t) function vim.tbl_keys(t)
assert(type(t) == 'table', string.format("Expected table, got %s", type(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. --- Return a list of all values used in a table.
--- However, the order of the return table of values is not guaranteed. --- However, the order of the return table of values is not guaranteed.
--- ---
--@param t Table ---@param t Table
--@returns list of values ---@returns list of values
function vim.tbl_values(t) function vim.tbl_values(t)
assert(type(t) == 'table', string.format("Expected table, got %s", type(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. --- Apply a function to all values of a table.
--- ---
--@param func function or callable table ---@param func function or callable table
--@param t table ---@param t table
function vim.tbl_map(func, t) function vim.tbl_map(func, t)
vim.validate{func={func,'c'},t={t,'t'}} vim.validate{func={func,'c'},t={t,'t'}}
@@ -160,8 +160,8 @@ end
--- Filter a table using a predicate function --- Filter a table using a predicate function
--- ---
--@param func function or callable table ---@param func function or callable table
--@param t table ---@param t table
function vim.tbl_filter(func, t) function vim.tbl_filter(func, t)
vim.validate{func={func,'c'},t={t,'t'}} vim.validate{func={func,'c'},t={t,'t'}}
@@ -176,9 +176,9 @@ end
--- Checks if a list-like (vector) table contains `value`. --- Checks if a list-like (vector) table contains `value`.
--- ---
--@param t Table to check ---@param t Table to check
--@param value Value to compare ---@param value Value to compare
--@returns true if `t` contains `value` ---@returns true if `t` contains `value`
function vim.tbl_contains(t, value) function vim.tbl_contains(t, value)
vim.validate{t={t,'t'}} vim.validate{t={t,'t'}}
@@ -192,16 +192,16 @@ end
--- Checks if a table is empty. --- 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) function vim.tbl_isempty(t)
assert(type(t) == 'table', string.format("Expected table, got %s", type(t))) assert(type(t) == 'table', string.format("Expected table, got %s", type(t)))
return next(t) == nil return next(t) == nil
end end
--- we only merge empty tables or tables that are not a list --- we only merge empty tables or tables that are not a list
--@private ---@private
local function can_merge(v) local function can_merge(v)
return type(v) == "table" and (vim.tbl_isempty(v) or not vim.tbl_islist(v)) return type(v) == "table" and (vim.tbl_isempty(v) or not vim.tbl_islist(v))
end end
@@ -242,26 +242,26 @@ end
--- Merges two or more map-like tables. --- 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 --- - "error": raise an error
--- - "keep": use value from the leftmost map --- - "keep": use value from the leftmost map
--- - "force": use value from the rightmost 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, ...) function vim.tbl_extend(behavior, ...)
return tbl_extend(behavior, false, ...) return tbl_extend(behavior, false, ...)
end end
--- Merges recursively two or more map-like tables. --- 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 --- - "error": raise an error
--- - "keep": use value from the leftmost map --- - "keep": use value from the leftmost map
--- - "force": use value from the rightmost 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, ...) function vim.tbl_deep_extend(behavior, ...)
return tbl_extend(behavior, true, ...) return tbl_extend(behavior, true, ...)
end end
@@ -292,7 +292,7 @@ end
--- `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }` --- `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }`
-- --
--Do note that it *modifies* the input. --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) function vim.tbl_add_reverse_lookup(o)
local keys = vim.tbl_keys(o) local keys = vim.tbl_keys(o)
for _, k in ipairs(keys) do for _, k in ipairs(keys) do
@@ -309,13 +309,13 @@ end
--- ---
--- NOTE: This mutates dst! --- NOTE: This mutates dst!
--- ---
--@see |vim.tbl_extend()| ---@see |vim.tbl_extend()|
--- ---
--@param dst list which will be modified and appended to. ---@param dst list which will be modified and appended to.
--@param src list from which values will be inserted. ---@param src list from which values will be inserted.
--@param start Start index on src. defaults to 1 ---@param start Start index on src. defaults to 1
--@param finish Final index on src. defaults to #src ---@param finish Final index on src. defaults to #src
--@returns dst ---@returns dst
function vim.list_extend(dst, src, start, finish) function vim.list_extend(dst, src, start, finish)
vim.validate { vim.validate {
dst = {dst, 't'}; dst = {dst, 't'};
@@ -332,10 +332,10 @@ end
--- Creates a copy of a list-like table such that any nested tables are --- Creates a copy of a list-like table such that any nested tables are
--- "unrolled" and appended to the result. --- "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 ---@param t List-like table
--@returns Flattened copy of the given list-like table. ---@returns Flattened copy of the given list-like table.
function vim.tbl_flatten(t) function vim.tbl_flatten(t)
local result = {} local result = {}
local function _tbl_flatten(_t) local function _tbl_flatten(_t)
@@ -359,8 +359,8 @@ end
--- |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result, --- |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
--- for example from |rpcrequest()| or |vim.fn|. --- for example from |rpcrequest()| or |vim.fn|.
--- ---
--@param t Table ---@param t Table
--@returns `true` if array-like table, else `false`. ---@returns `true` if array-like table, else `false`.
function vim.tbl_islist(t) function vim.tbl_islist(t)
if type(t) ~= 'table' then if type(t) ~= 'table' then
return false return false
@@ -395,9 +395,9 @@ end
--- vim.tbl_count({ 1, 2 }) => 2 --- vim.tbl_count({ 1, 2 }) => 2
--- </pre> --- </pre>
--- ---
--@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua ---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
--@param t Table ---@param t Table
--@returns Number that is the number of the value in table ---@returns Number that is the number of the value in table
function vim.tbl_count(t) function vim.tbl_count(t)
vim.validate{t={t,'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) --- Creates a copy of a table containing only elements from start to end (inclusive)
--- ---
--@param list table table ---@param list table table
--@param start integer Start range of slice ---@param start integer Start range of slice
--@param finish integer End range of slice ---@param finish integer End range of slice
--@returns Copy of table sliced from start to finish (inclusive) ---@returns Copy of table sliced from start to finish (inclusive)
function vim.list_slice(list, start, finish) function vim.list_slice(list, start, finish)
local new_list = {} local new_list = {}
for i = start or 1, finish or #list do 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. --- Trim whitespace (Lua pattern "%s") from both sides of a string.
--- ---
--@see https://www.lua.org/pil/20.2.html ---@see https://www.lua.org/pil/20.2.html
--@param s String to trim ---@param s String to trim
--@returns String with whitespace removed from its beginning and end ---@returns String with whitespace removed from its beginning and end
function vim.trim(s) function vim.trim(s)
vim.validate{s={s,'s'}} vim.validate{s={s,'s'}}
return s:match('^%s*(.*%S)') or '' return s:match('^%s*(.*%S)') or ''
@@ -432,9 +432,9 @@ end
--- Escapes magic chars in a Lua pattern. --- Escapes magic chars in a Lua pattern.
--- ---
--@see https://github.com/rxi/lume ---@see https://github.com/rxi/lume
--@param s String to escape ---@param s String to escape
--@returns %-escaped pattern string ---@returns %-escaped pattern string
function vim.pesc(s) function vim.pesc(s)
vim.validate{s={s,'s'}} vim.validate{s={s,'s'}}
return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1') return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
@@ -442,9 +442,9 @@ end
--- Tests if `s` starts with `prefix`. --- Tests if `s` starts with `prefix`.
--- ---
--@param s (string) a string ---@param s (string) a string
--@param prefix (string) a prefix ---@param prefix (string) a prefix
--@return (boolean) true if `prefix` is a prefix of s ---@return (boolean) true if `prefix` is a prefix of s
function vim.startswith(s, prefix) function vim.startswith(s, prefix)
vim.validate { s = {s, 's'}; prefix = {prefix, 's'}; } vim.validate { s = {s, 's'}; prefix = {prefix, 's'}; }
return s:sub(1, #prefix) == prefix return s:sub(1, #prefix) == prefix
@@ -452,9 +452,9 @@ end
--- Tests if `s` ends with `suffix`. --- Tests if `s` ends with `suffix`.
--- ---
--@param s (string) a string ---@param s (string) a string
--@param suffix (string) a suffix ---@param suffix (string) a suffix
--@return (boolean) true if `suffix` is a suffix of s ---@return (boolean) true if `suffix` is a suffix of s
function vim.endswith(s, suffix) function vim.endswith(s, suffix)
vim.validate { s = {s, 's'}; suffix = {suffix, 's'}; } vim.validate { s = {s, 's'}; suffix = {suffix, 's'}; }
return #suffix == 0 or s:sub(-#suffix) == suffix return #suffix == 0 or s:sub(-#suffix) == suffix
@@ -486,7 +486,7 @@ end
--- => error('arg1: expected even number, got 3') --- => error('arg1: expected even number, got 3')
--- </pre> --- </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: --- name; each value is a tuple in one of these forms:
--- 1. (arg_value, type_name, optional) --- 1. (arg_value, type_name, optional)
--- - arg_value: argument value --- - arg_value: argument value
@@ -570,8 +570,8 @@ do
end end
--- Returns true if object `f` can be called as a function. --- Returns true if object `f` can be called as a function.
--- ---
--@param f Any object ---@param f Any object
--@return true if `f` is callable, else false ---@return true if `f` is callable, else false
function vim.is_callable(f) function vim.is_callable(f)
if type(f) == 'function' then return true end if type(f) == 'function' then return true end
local m = getmetatable(f) 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. --- It is not recommended to use this, use vim.treesitter.get_parser() instead.
--- ---
--- @param bufnr The buffer the parser will be tied to ---@param bufnr The buffer the parser will be tied to
--- @param lang The language of the parser ---@param lang The language of the parser
--- @param opts Options to pass to the created language tree ---@param opts Options to pass to the created language tree
function M._create_parser(bufnr, lang, opts) function M._create_parser(bufnr, lang, opts)
language.require_language(lang) language.require_language(lang)
if bufnr == 0 then if bufnr == 0 then
@@ -71,11 +71,11 @@ end
--- If needed this will create the parser. --- If needed this will create the parser.
--- Unconditionnally attach the provided callback --- Unconditionnally attach the provided callback
--- ---
--- @param bufnr The buffer the parser should be tied to ---@param bufnr The buffer the parser should be tied to
--- @param lang The filetype of this parser ---@param lang The filetype of this parser
--- @param opts Options object to pass to the created language tree ---@param opts Options object to pass to the created language tree
--- ---
--- @returns The parser ---@returns The parser
function M.get_parser(bufnr, lang, opts) function M.get_parser(bufnr, lang, opts)
opts = opts or {} opts = opts or {}
@@ -97,9 +97,9 @@ end
--- Gets a string parser --- Gets a string parser
--- ---
--- @param str The string to parse ---@param str The string to parse
--- @param lang The language of this string ---@param lang The language of this string
--- @param opts Options to pass to the created language tree ---@param opts Options to pass to the created language tree
function M.get_string_parser(str, lang, opts) function M.get_string_parser(str, lang, opts)
vim.validate { vim.validate {
str = { str, 'string' }, str = { str, 'string' },

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

@@ -122,8 +122,8 @@ end
--- Creates a new highlighter using @param tree --- Creates a new highlighter using @param tree
--- ---
--- @param tree The language tree to use for highlighting ---@param tree The language tree to use for highlighting
--- @param opts Table used to configure the highlighter ---@param opts Table used to configure the highlighter
--- - queries: Table to overwrite queries used by the highlighter --- - queries: Table to overwrite queries used by the highlighter
function TSHighlighter.new(tree, opts) function TSHighlighter.new(tree, opts)
local self = setmetatable({}, TSHighlighter) local self = setmetatable({}, TSHighlighter)
@@ -217,7 +217,7 @@ end
--- Gets the query used for @param lang --- 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) function TSHighlighter:get_query(lang)
if not self._queries[lang] then if not self._queries[lang] then
self._queries[lang] = TSHighlighterQuery.new(lang) 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. --- Parsers are searched in the `parser` runtime directory.
--- ---
--- @param lang The language the parser should parse ---@param lang The language the parser should parse
--- @param path Optional path the parser is located at ---@param path Optional path the parser is located at
--- @param silent Don't throw an error if language not found ---@param silent Don't throw an error if language not found
function M.require_language(lang, path, silent) function M.require_language(lang, path, silent)
if vim._ts_has_language(lang) then if vim._ts_has_language(lang) then
return true return true
@@ -40,7 +40,7 @@ end
--- ---
--- Inspecting provides some useful informations on the language like node names, ... --- Inspecting provides some useful informations on the language like node names, ...
--- ---
--- @param lang The language. ---@param lang The language.
function M.inspect_language(lang) function M.inspect_language(lang)
M.require_language(lang) M.require_language(lang)
return vim._ts_inspect_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, --- The language can contain child languages with in its range,
--- hence the tree. --- hence the tree.
--- ---
--- @param source Can be a bufnr or a string of text to parse ---@param source Can be a bufnr or a string of text to parse
--- @param lang The language this tree represents ---@param lang The language this tree represents
--- @param opts Options table ---@param opts Options table
--- @param opts.injections A table of language to injection query strings. ---@param opts.injections A table of language to injection query strings.
--- This is useful for overriding the built-in runtime file --- This is useful for overriding the built-in runtime file
--- searching for the injection language query per language. --- searching for the injection language query per language.
function LanguageTree.new(source, lang, opts) function LanguageTree.new(source, lang, opts)
language.require_language(lang) language.require_language(lang)
opts = opts or {} opts = opts or {}
@@ -171,8 +171,8 @@ end
--- Invokes the callback for each LanguageTree and it's children recursively --- 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 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 include_self Whether to include the invoking tree in the results.
function LanguageTree:for_each_child(fn, include_self) function LanguageTree:for_each_child(fn, include_self)
if include_self then if include_self then
fn(self, self._lang) fn(self, self._lang)
@@ -187,8 +187,8 @@ end
--- ---
--- Note, this includes the invoking language tree's trees as well. --- Note, this includes the invoking language tree's trees as well.
--- ---
--- @param fn The callback to invoke. The callback is invoked with arguments ---@param fn The callback to invoke. The callback is invoked with arguments
--- (tree: TSTree, languageTree: LanguageTree) --- (tree: TSTree, languageTree: LanguageTree)
function LanguageTree:for_each_tree(fn) function LanguageTree:for_each_tree(fn)
for _, tree in ipairs(self._trees) do for _, tree in ipairs(self._trees) do
fn(tree, self) fn(tree, self)
@@ -203,7 +203,7 @@ end
--- ---
--- If the language already exists as a child, it will first be removed. --- 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) function LanguageTree:add_child(lang)
if self._children[lang] then if self._children[lang] then
self:remove_child(lang) self:remove_child(lang)
@@ -219,7 +219,7 @@ end
--- Removes a child language from this tree. --- Removes a child language from this tree.
--- ---
--- @param lang The language to remove. ---@param lang The language to remove.
function LanguageTree:remove_child(lang) function LanguageTree:remove_child(lang)
local child = self._children[lang] local child = self._children[lang]
@@ -259,7 +259,7 @@ end
--- ---
--- Note, this call invalidates the tree and requires it to be parsed again. --- 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) function LanguageTree:set_included_regions(regions)
-- TODO(vigoux): I don't think string parsers are useful for now -- TODO(vigoux): I don't think string parsers are useful for now
if type(self._source) == "number" then if type(self._source) == "number" then
@@ -299,7 +299,7 @@ end
--- ---
--- TODO: Allow for an offset predicate to tailor the injection range --- TODO: Allow for an offset predicate to tailor the injection range
--- instead of using the entire nodes range. --- instead of using the entire nodes range.
--- @private ---@private
function LanguageTree:_get_injections() function LanguageTree:_get_injections()
if not self._injection_query then return {} end if not self._injection_query then return {} end
@@ -449,7 +449,7 @@ function LanguageTree:_on_detach(...)
end end
--- Registers callbacks for the parser --- 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_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. --- `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 --- 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. --- 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) function LanguageTree:contains(range)
for _, tree in pairs(self._trees) do for _, tree in pairs(self._trees) do
if tree_contains(tree, range) then if tree_contains(tree, range) then
@@ -510,7 +510,7 @@ end
--- Gets the appropriate language that contains @param range --- 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) function LanguageTree:language_for_range(range)
for _, child in pairs(self._children) do for _, child in pairs(self._children) do
if child:contains(range) then 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 --- Gets the list of files used to make up a query
--- ---
--- @param lang The language ---@param lang The language
--- @param query_name The name of the query to load ---@param query_name The name of the query to load
--- @param is_included Internal parameter, most of the time left as `nil` ---@param is_included Internal parameter, most of the time left as `nil`
function M.get_query_files(lang, query_name, is_included) function M.get_query_files(lang, query_name, is_included)
local query_path = string.format('queries/%s/%s.scm', lang, query_name) 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)) 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 --- This allows users to override any runtime files and/or configuration
--- set by plugins. --- set by plugins.
--- ---
--- @param lang string: The language to use for the query ---@param lang string: The language to use for the query
--- @param query_name string: The name of the query (i.e. "highlights") ---@param query_name string: The name of the query (i.e. "highlights")
--- @param text string: The query text (unparsed). ---@param text string: The query text (unparsed).
function M.set_query(lang, query_name, text) function M.set_query(lang, query_name, text)
explicit_queries[lang][query_name] = M.parse_query(lang, text) explicit_queries[lang][query_name] = M.parse_query(lang, text)
end end
--- Returns the runtime query {query_name} for {lang}. --- Returns the runtime query {query_name} for {lang}.
--- ---
--- @param lang The language to use for the query ---@param lang The language to use for the query
--- @param query_name The name of the query (i.e. "highlights") ---@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) function M.get_query(lang, query_name)
if explicit_queries[lang][query_name] then if explicit_queries[lang][query_name] then
return explicit_queries[lang][query_name] return explicit_queries[lang][query_name]
@@ -151,10 +151,10 @@ end
--- -` info.captures` also points to `captures`. --- -` info.captures` also points to `captures`.
--- - `info.patterns` contains information about predicates. --- - `info.patterns` contains information about predicates.
--- ---
--- @param lang The language ---@param lang The language
--- @param query A string containing the query (s-expr syntax) ---@param query A string containing the query (s-expr syntax)
--- ---
--- @returns The query ---@returns The query
function M.parse_query(lang, query) function M.parse_query(lang, query)
language.require_language(lang) language.require_language(lang)
local self = setmetatable({}, Query) local self = setmetatable({}, Query)
@@ -168,8 +168,8 @@ end
--- Gets the text corresponding to a given node --- Gets the text corresponding to a given node
--- ---
--- @param node the node ---@param node the node
--- @param bsource The buffer or string from which the node is extracted ---@param bsource The buffer or string from which the node is extracted
function M.get_node_text(node, source) function M.get_node_text(node, source)
local start_row, start_col, start_byte = node:start() local start_row, start_col, start_byte = node:start()
local end_row, end_col, end_byte = node:end_() 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 --- Adds a new predicate to be used in queries
--- ---
--- @param name the name of the predicate, without leading # ---@param name the name of the predicate, without leading #
--- @param handler the handler function to be used ---@param handler the handler function to be used
--- signature will be (match, pattern, bufnr, predicate) --- signature will be (match, pattern, bufnr, predicate)
function M.add_predicate(name, handler, force) function M.add_predicate(name, handler, force)
if predicate_handlers[name] and not force then if predicate_handlers[name] and not force then
error(string.format("Overriding %s", name)) error(string.format("Overriding %s", name))
@@ -340,9 +340,9 @@ end
--- Adds a new directive to be used in queries --- Adds a new directive to be used in queries
--- ---
--- @param name the name of the directive, without leading # ---@param name the name of the directive, without leading #
--- @param handler the handler function to be used ---@param handler the handler function to be used
--- signature will be (match, pattern, bufnr, predicate) --- signature will be (match, pattern, bufnr, predicate)
function M.add_directive(name, handler, force) function M.add_directive(name, handler, force)
if directive_handlers[name] and not force then if directive_handlers[name] and not force then
error(string.format("Overriding %s", name)) error(string.format("Overriding %s", name))
@@ -351,12 +351,12 @@ function M.add_directive(name, handler, force)
directive_handlers[name] = handler directive_handlers[name] = handler
end end
--- @return The list of supported directives. ---@return The list of supported directives.
function M.list_directives() function M.list_directives()
return vim.tbl_keys(directive_handlers) return vim.tbl_keys(directive_handlers)
end end
--- @return The list of supported predicates. ---@return The list of supported predicates.
function M.list_predicates() function M.list_predicates()
return vim.tbl_keys(predicate_handlers) return vim.tbl_keys(predicate_handlers)
end end
@@ -465,13 +465,13 @@ end
--- end --- end
--- </pre> --- </pre>
--- ---
--- @param node The node under which the search will occur ---@param node The node under which the search will occur
--- @param source The source buffer or string to exctract text from ---@param source The source buffer or string to exctract text from
--- @param start The starting line of the search ---@param start The starting line of the search
--- @param stop The stopping line of the search (end-exclusive) ---@param stop The stopping line of the search (end-exclusive)
--- ---
--- @returns The matching capture id ---@returns The matching capture id
--- @returns The captured node ---@returns The captured node
function Query:iter_captures(node, source, start, stop) function Query:iter_captures(node, source, start, stop)
if type(source) == "number" and source == 0 then if type(source) == "number" and source == 0 then
source = vim.api.nvim_get_current_buf() source = vim.api.nvim_get_current_buf()
@@ -522,13 +522,13 @@ end
--- end --- end
--- </pre> --- </pre>
--- ---
--- @param node The node under which the search will occur ---@param node The node under which the search will occur
--- @param source The source buffer or string to search ---@param source The source buffer or string to search
--- @param start The starting line of the search ---@param start The starting line of the search
--- @param stop The stopping line of the search (end-exclusive) ---@param stop The stopping line of the search (end-exclusive)
--- ---
--- @returns The matching pattern id ---@returns The matching pattern id
--- @returns The matching match ---@returns The matching match
function Query:iter_matches(node, source, start, stop) function Query:iter_matches(node, source, start, stop)
if type(source) == "number" and source == 0 then if type(source) == "number" and source == 0 then
source = vim.api.nvim_get_current_buf() source = vim.api.nvim_get_current_buf()

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

@@ -9,7 +9,7 @@ do
local schar = string.char local schar = string.char
--- Convert hex to char --- Convert hex to char
--@private ---@private
local function hex_to_char(hex) local function hex_to_char(hex)
return schar(tonumber(hex, 16)) return schar(tonumber(hex, 16))
end end
@@ -38,7 +38,7 @@ do
tohex = function(b) return string.format("%02x", b) end tohex = function(b) return string.format("%02x", b) end
end end
--@private ---@private
local function percent_encode_char(char) local function percent_encode_char(char)
return "%"..tohex(sbyte(char), 2) return "%"..tohex(sbyte(char), 2)
end end
@@ -50,14 +50,14 @@ do
end end
--@private ---@private
local function is_windows_file_uri(uri) local function is_windows_file_uri(uri)
return uri:match('^file:/+[a-zA-Z]:') ~= nil return uri:match('^file:/+[a-zA-Z]:') ~= nil
end end
--- Get a URI from a file path. --- Get a URI from a file path.
--@param path (string): Path to file ---@param path (string): Path to file
--@return URI ---@return URI
local function uri_from_fname(path) local function uri_from_fname(path)
local volume_path, fname = path:match("^([a-zA-Z]:)(.*)") local volume_path, fname = path:match("^([a-zA-Z]:)(.*)")
local is_windows = volume_path ~= nil local is_windows = volume_path ~= nil
@@ -77,8 +77,8 @@ end
local URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9+-.]*):.*' local URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9+-.]*):.*'
--- Get a URI from a bufnr --- Get a URI from a bufnr
--@param bufnr (number): Buffer number ---@param bufnr (number): Buffer number
--@return URI ---@return URI
local function uri_from_bufnr(bufnr) local function uri_from_bufnr(bufnr)
local fname = vim.api.nvim_buf_get_name(bufnr) local fname = vim.api.nvim_buf_get_name(bufnr)
local scheme = fname:match(URI_SCHEME_PATTERN) local scheme = fname:match(URI_SCHEME_PATTERN)
@@ -90,8 +90,8 @@ local function uri_from_bufnr(bufnr)
end end
--- Get a filename from a URI --- Get a filename from a URI
--@param uri (string): The URI ---@param uri (string): The URI
--@return Filename ---@return Filename
local function uri_to_fname(uri) local function uri_to_fname(uri)
local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri) local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
if scheme ~= 'file' then if scheme ~= 'file' then
@@ -109,9 +109,9 @@ local function uri_to_fname(uri)
end end
--- Return or create a buffer for a uri. --- Return or create a buffer for a uri.
--@param uri (string): The URI ---@param uri (string): The URI
--@return bufnr. ---@return bufnr.
--@note Creates buffer but does not load it ---@note Creates buffer but does not load it
local function uri_to_bufnr(uri) local function uri_to_bufnr(uri)
local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri) local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
if scheme == 'file' then 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. --- Return a human-readable representation of the given object.
--- ---
--@see https://github.com/kikito/inspect.lua ---@see https://github.com/kikito/inspect.lua
--@see https://github.com/mpeterv/vinspect ---@see https://github.com/mpeterv/vinspect
local function inspect(object, options) -- luacheck: no unused local function inspect(object, options) -- luacheck: no unused
error(object, options) -- Stub for gen_vimdoc.py error(object, options) -- Stub for gen_vimdoc.py
end end
@@ -203,15 +203,15 @@ do
--- end)(vim.paste) --- end)(vim.paste)
--- </pre> --- </pre>
--- ---
--@see |paste| ---@see |paste|
--- ---
--@param lines |readfile()|-style list of lines to paste. |channel-lines| ---@param lines |readfile()|-style list of lines to paste. |channel-lines|
--@param phase -1: "non-streaming" paste: the call contains all lines. ---@param phase -1: "non-streaming" paste: the call contains all lines.
--- If paste is "streamed", `phase` indicates the stream state: --- If paste is "streamed", `phase` indicates the stream state:
--- - 1: starts the paste (exactly once) --- - 1: starts the paste (exactly once)
--- - 2: continues the paste (zero or more times) --- - 2: continues the paste (zero or more times)
--- - 3: ends the paste (exactly once) --- - 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) function vim.paste(lines, phase)
local call = vim.api.nvim_call_function local call = vim.api.nvim_call_function
local now = vim.loop.now() local now = vim.loop.now()
@@ -279,7 +279,7 @@ function vim.schedule_wrap(cb)
end end
--- <Docs described in |vim.empty_dict()| > --- <Docs described in |vim.empty_dict()| >
--@private ---@private
function vim.empty_dict() function vim.empty_dict()
return setmetatable({}, vim._empty_dict_mt) return setmetatable({}, vim._empty_dict_mt)
end end
@@ -338,12 +338,12 @@ end
--- Get a table of lines with start, end columns for a region marked by two points --- Get a table of lines with start, end columns for a region marked by two points
--- ---
--@param bufnr number of buffer ---@param bufnr number of buffer
--@param pos1 (line, column) tuple marking beginning of region ---@param pos1 (line, column) tuple marking beginning of region
--@param pos2 (line, column) tuple marking end of region ---@param pos2 (line, column) tuple marking end of region
--@param regtype type of selection (:help setreg) ---@param regtype type of selection (:help setreg)
--@param inclusive boolean indicating whether the selection is end-inclusive ---@param inclusive boolean indicating whether the selection is end-inclusive
--@return region lua table of the form {linenr = {startcol,endcol}} ---@return region lua table of the form {linenr = {startcol,endcol}}
function vim.region(bufnr, pos1, pos2, regtype, inclusive) function vim.region(bufnr, pos1, pos2, regtype, inclusive)
if not vim.api.nvim_buf_is_loaded(bufnr) then if not vim.api.nvim_buf_is_loaded(bufnr) then
vim.fn.bufload(bufnr) vim.fn.bufload(bufnr)
@@ -390,9 +390,9 @@ end
--- Use to do a one-shot timer that calls `fn` --- Use to do a one-shot timer that calls `fn`
--- Note: The {fn} is |schedule_wrap|ped automatically, so API functions are --- Note: The {fn} is |schedule_wrap|ped automatically, so API functions are
--- safe to call. --- safe to call.
--@param fn Callback to call once `timeout` expires ---@param fn Callback to call once `timeout` expires
--@param timeout Number of milliseconds to wait before calling `fn` ---@param timeout Number of milliseconds to wait before calling `fn`
--@return timer luv timer object ---@return timer luv timer object
function vim.defer_fn(fn, timeout) function vim.defer_fn(fn, timeout)
vim.validate { fn = { fn, 'c', true}; } vim.validate { fn = { fn, 'c', true}; }
local timer = vim.loop.new_timer() local timer = vim.loop.new_timer()
@@ -408,11 +408,12 @@ end
--- Notification provider --- Notification provider
--- without a runtime, writes to :Messages ---
-- see :help nvim_notify --- Without a runtime, writes to :Messages
--@param msg Content of the notification to show to the user ---@see :help nvim_notify
--@param log_level Optional log level ---@param msg Content of the notification to show to the user
--@param opts Dictionary with optional options (timeout, etc) ---@param log_level Optional log level
---@param opts Dictionary with optional options (timeout, etc)
function vim.notify(msg, log_level, _opts) function vim.notify(msg, log_level, _opts)
if log_level == vim.log.levels.ERROR then 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. --- 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. --- The string will contain the literal keys typed.
--- See |i_CTRL-V| --- See |i_CTRL-V|
--- ---
--- If {fn} is nil, it removes the callback for the associated {ns_id} --- 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()| --- 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 --- This is to prevent the annoying situation of every keystroke erroring
--- while trying to remove a broken callback. --- while trying to remove a broken callback.
--@note {fn} will not be cleared from |nvim_buf_clear_namespace()| ---@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 receive the keystrokes after mappings have been evaluated
function vim.register_keystroke_callback(fn, ns_id) function vim.register_keystroke_callback(fn, ns_id)
vim.validate { vim.validate {
fn = { fn, 'c', true}, fn = { fn, 'c', true},
@@ -459,7 +460,7 @@ function vim.register_keystroke_callback(fn, ns_id)
end end
--- Function that executes the keystroke callbacks. --- Function that executes the keystroke callbacks.
--@private ---@private
function vim._log_keystroke(char) function vim._log_keystroke(char)
local failed_ns_ids = {} local failed_ns_ids = {}
local failed_messages = {} local failed_messages = {}

4
test/functional/helpers.lua
View File

@@ -422,7 +422,7 @@ end
-- Builds an argument list for use in clear(). -- Builds an argument list for use in clear().
-- --
--@see clear() for parameters. ---@see clear() for parameters.
function module.new_argv(...) function module.new_argv(...)
local args = {unpack(module.nvim_argv)} local args = {unpack(module.nvim_argv)}
table.insert(args, '--headless') 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) return module.exec_lua("return vim.api.nvim_buf_get_lines((...), 0, -1, false)", bufnr)
end end
--@see buf_lines() ---@see buf_lines()
function module.curbuf_contents() function module.curbuf_contents()
module.poke_eventloop() -- Before inspecting the buffer, do whatever. module.poke_eventloop() -- Before inspecting the buffer, do whatever.
return table.concat(module.curbuf('get_lines', 0, -1, true), '\n') 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 --- Invokes `fn` and includes the tail of `logfile` in the error message if it
--- fails. --- fails.
--- ---
--@param logfile Log file, defaults to $NVIM_LOG_FILE or '.nvimlog' ---@param logfile Log file, defaults to $NVIM_LOG_FILE or '.nvimlog'
--@param fn Function to invoke ---@param fn Function to invoke
--@param ... Function arguments ---@param ... Function arguments
local function dumplog(logfile, fn, ...) local function dumplog(logfile, fn, ...)
-- module.validate({ -- module.validate({
-- logfile={logfile,'s',true}, -- logfile={logfile,'s',true},
@@ -102,8 +102,8 @@ end
--- Asserts that `pat` matches one or more lines in the tail of $NVIM_LOG_FILE. --- 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 pat (string) Lua pattern to search for in the log file.
--@param logfile (string, default=$NVIM_LOG_FILE) full path to log file. ---@param logfile (string, default=$NVIM_LOG_FILE) full path to log file.
function module.assert_log(pat, logfile) function module.assert_log(pat, logfile)
logfile = logfile or os.getenv('NVIM_LOG_FILE') or '.nvimlog' logfile = logfile or os.getenv('NVIM_LOG_FILE') or '.nvimlog'
local nrlines = 10 local nrlines = 10