aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLewis Russell <lewis6991@gmail.com>2024-01-09 17:36:46 +0000
committerLewis Russell <me@lewisr.dev>2024-01-11 16:24:12 +0000
commit2f9ee9b6cfc61a0504fc0bc22bdf481828e2ea91 (patch)
tree06884cc40b3f6e7c0dd47f4018c8ba0f671ba610
parenta767c046f4e6bff1412269d56a8edfe33857d954 (diff)
downloadrneovim-2f9ee9b6cfc61a0504fc0bc22bdf481828e2ea91.tar.gz
rneovim-2f9ee9b6cfc61a0504fc0bc22bdf481828e2ea91.tar.bz2
rneovim-2f9ee9b6cfc61a0504fc0bc22bdf481828e2ea91.zip
fix(doc): improve doc generation of types using lpeg
Added a lpeg grammar for LuaCATS and use it in lua2dox.lua
Diffstat
-rw-r--r--runtime/doc/api.txt5
-rw-r--r--runtime/doc/diagnostic.txt132
-rw-r--r--runtime/doc/lsp.txt466
-rw-r--r--runtime/doc/lua.txt759
-rw-r--r--runtime/doc/treesitter.txt233
-rw-r--r--runtime/lua/vim/_editor.lua7
-rw-r--r--runtime/lua/vim/_meta/api.lua5
-rw-r--r--runtime/lua/vim/_system.lua4
-rw-r--r--runtime/lua/vim/filetype.lua4
-rw-r--r--runtime/lua/vim/health.lua2
-rw-r--r--runtime/lua/vim/iter.lua48
-rw-r--r--runtime/lua/vim/lsp/handlers.lua2
-rw-r--r--runtime/lua/vim/lsp/util.lua6
-rw-r--r--runtime/lua/vim/shared.lua2
-rw-r--r--runtime/lua/vim/treesitter/query.lua2
-rwxr-xr-xscripts/gen_vimdoc.py14
-rw-r--r--scripts/lua2dox.lua192
-rw-r--r--src/nvim/CMakeLists.txt2
-rw-r--r--src/nvim/generators/luacats_grammar.lua136
-rw-r--r--test/functional/luacats_grammar_spec.lua133
20 files changed, 1234 insertions, 920 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 5b464debca..b5a49f6002 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3381,9 +3381,8 @@ nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()*
• |autocmd-groups|
nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()*
- Creates an |autocommand| event handler, defined by `callback` (Lua
- function or Vimscript function name string) or `command` (Ex command
- string).
+ Creates an |autocommand| event handler, defined by `callback` (Lua function
+ or Vimscript function name string) or `command` (Ex command string).
Example using Lua callback: >lua
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index ddebeb6730..5ff1c3bab5 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -390,7 +390,7 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
any of the above.
Parameters: ~
- • {opts} (table|nil) When omitted or "nil", retrieve the current
+ • {opts} (`table?`) When omitted or "nil", retrieve the current
configuration. Otherwise, a configuration table with the
following keys:
• underline: (default true) Use underline for
@@ -475,55 +475,55 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
severities are displayed before lower severities (e.g.
ERROR is displayed before WARN). Options:
• reverse: (boolean) Reverse sort order
- • {namespace} (integer|nil) Update the options for the given namespace.
+ • {namespace} (`integer?`) Update the options for the given namespace.
When omitted, update the global diagnostic options.
Return: ~
- (table|nil) table of current diagnostic config if `opts` is omitted.
+ (`table?`) table of current diagnostic config if `opts` is omitted.
count({bufnr}, {opts}) *vim.diagnostic.count()*
Get current diagnostics count.
Parameters: ~
- • {bufnr} (integer|nil) Buffer number to get diagnostics from. Use 0
- for current buffer or nil for all buffers.
- • {opts} (table|nil) A table with the following keys:
+ • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for
+ current buffer or nil for all buffers.
+ • {opts} (`table?`) A table with the following keys:
• namespace: (number) Limit diagnostics to the given
namespace.
• lnum: (number) Limit diagnostics to the given line number.
• severity: See |diagnostic-severity|.
Return: ~
- (table) A table with actually present severity values as keys (see
+ (`table`) A table with actually present severity values as keys (see
|diagnostic-severity|) and integer counts as values.
disable({bufnr}, {namespace}) *vim.diagnostic.disable()*
Disable diagnostics in the given buffer.
Parameters: ~
- • {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
- When omitted, disable diagnostics in all buffers.
- • {namespace} (integer|nil) Only disable diagnostics for the given
+ • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When
+ omitted, disable diagnostics in all buffers.
+ • {namespace} (`integer?`) Only disable diagnostics for the given
namespace.
enable({bufnr}, {namespace}) *vim.diagnostic.enable()*
Enable diagnostics in the given buffer.
Parameters: ~
- • {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
- When omitted, enable diagnostics in all buffers.
- • {namespace} (integer|nil) Only enable diagnostics for the given
+ • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When
+ omitted, enable diagnostics in all buffers.
+ • {namespace} (`integer?`) Only enable diagnostics for the given
namespace.
fromqflist({list}) *vim.diagnostic.fromqflist()*
Convert a list of quickfix items to a list of diagnostics.
Parameters: ~
- • {list} table[] List of quickfix items from |getqflist()| or
+ • {list} (`table[]`) List of quickfix items from |getqflist()| or
|getloclist()|.
Return: ~
- Diagnostic [] array of |diagnostic-structure|
+ (`Diagnostic[]`) array of |diagnostic-structure|
get({bufnr}, {opts}) *vim.diagnostic.get()*
Get current diagnostics.
@@ -532,77 +532,77 @@ get({bufnr}, {opts}) *vim.diagnostic.get()*
diagnostics in a buffer, use |vim.diagnostic.set()|.
Parameters: ~
- • {bufnr} (integer|nil) Buffer number to get diagnostics from. Use 0
- for current buffer or nil for all buffers.
- • {opts} (table|nil) A table with the following keys:
+ • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for
+ current buffer or nil for all buffers.
+ • {opts} (`table?`) A table with the following keys:
• namespace: (number) Limit diagnostics to the given
namespace.
• lnum: (number) Limit diagnostics to the given line number.
• severity: See |diagnostic-severity|.
Return: ~
- Diagnostic [] table A list of diagnostic items |diagnostic-structure|.
- Keys `bufnr` , `end_lnum` , `end_col` , and `severity` are
+ (`Diagnostic[]`) table A list of diagnostic items
+ |diagnostic-structure|. Keys `bufnr` , `end_lnum` , `end_col` , and `severity` are
guaranteed to be present.
get_namespace({namespace}) *vim.diagnostic.get_namespace()*
Get namespace metadata.
Parameters: ~
- • {namespace} (integer) Diagnostic namespace
+ • {namespace} (`integer`) Diagnostic namespace
Return: ~
- (table) Namespace metadata
+ (`table`) Namespace metadata
get_namespaces() *vim.diagnostic.get_namespaces()*
Get current diagnostic namespaces.
Return: ~
- (table) A list of active diagnostic namespaces |vim.diagnostic|.
+ (`table`) A list of active diagnostic namespaces |vim.diagnostic|.
get_next({opts}) *vim.diagnostic.get_next()*
Get the next diagnostic closest to the cursor position.
Parameters: ~
- • {opts} (table|nil) See |vim.diagnostic.goto_next()|
+ • {opts} (`table?`) See |vim.diagnostic.goto_next()|
Return: ~
- Diagnostic|nil Next diagnostic
+ (`Diagnostic?`) Next diagnostic
get_next_pos({opts}) *vim.diagnostic.get_next_pos()*
Return the position of the next diagnostic in the current buffer.
Parameters: ~
- • {opts} (table|nil) See |vim.diagnostic.goto_next()|
+ • {opts} (`table?`) See |vim.diagnostic.goto_next()|
Return: ~
- table|false Next diagnostic position as a (row, col) tuple or false if
- no next diagnostic.
+ (`table|false`) Next diagnostic position as a (row, col) tuple or
+ false if no next diagnostic.
get_prev({opts}) *vim.diagnostic.get_prev()*
Get the previous diagnostic closest to the cursor position.
Parameters: ~
- • {opts} nil|table See |vim.diagnostic.goto_next()|
+ • {opts} (`table?`) See |vim.diagnostic.goto_next()|
Return: ~
- Diagnostic|nil Previous diagnostic
+ (`Diagnostic?`) Previous diagnostic
get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()*
Return the position of the previous diagnostic in the current buffer.
Parameters: ~
- • {opts} (table|nil) See |vim.diagnostic.goto_next()|
+ • {opts} (`table?`) See |vim.diagnostic.goto_next()|
Return: ~
- table|false Previous diagnostic position as a (row, col) tuple or
+ (`table|false`) Previous diagnostic position as a (row, col) tuple or
false if there is no prior diagnostic
goto_next({opts}) *vim.diagnostic.goto_next()*
Move to the next diagnostic.
Parameters: ~
- • {opts} (table|nil) Configuration table with the following keys:
+ • {opts} (`table?`) Configuration table with the following keys:
• namespace: (number) Only consider diagnostics from the given
namespace.
• cursor_position: (cursor position) Cursor position as a
@@ -623,7 +623,7 @@ goto_prev({opts}) *vim.diagnostic.goto_prev()*
Move to the previous diagnostic in the current buffer.
Parameters: ~
- • {opts} (table|nil) See |vim.diagnostic.goto_next()|
+ • {opts} (`table?`) See |vim.diagnostic.goto_next()|
hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
Hide currently displayed diagnostics.
@@ -636,22 +636,22 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
|vim.diagnostic.disable()|.
Parameters: ~
- • {namespace} (integer|nil) Diagnostic namespace. When omitted, hide
+ • {namespace} (`integer?`) Diagnostic namespace. When omitted, hide
diagnostics from all namespaces.
- • {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
- When omitted, hide diagnostics in all buffers.
+ • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When
+ omitted, hide diagnostics in all buffers.
is_disabled({bufnr}, {namespace}) *vim.diagnostic.is_disabled()*
Check whether diagnostics are disabled in a given buffer.
Parameters: ~
- • {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
- • {namespace} (integer|nil) Diagnostic namespace. When omitted, checks
- if all diagnostics are disabled in {bufnr}. Otherwise,
- only checks if diagnostics from {namespace} are disabled.
+ • {bufnr} (`integer?`) Buffer number, or 0 for current buffer.
+ • {namespace} (`integer?`) Diagnostic namespace. When omitted, checks if
+ all diagnostics are disabled in {bufnr}. Otherwise, only
+ checks if diagnostics from {namespace} are disabled.
Return: ~
- (boolean)
+ (`boolean`)
*vim.diagnostic.match()*
match({str}, {pat}, {groups}, {severity_map}, {defaults})
@@ -669,25 +669,25 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
<
Parameters: ~
- • {str} (string) String to parse diagnostics from.
- • {pat} (string) Lua pattern with capture groups.
- • {groups} (table) List of fields in a |diagnostic-structure| to
- associate with captures from {pat}.
- • {severity_map} (table) A table mapping the severity field from
+ • {str} (`string`) String to parse diagnostics from.
+ • {pat} (`string`) Lua pattern with capture groups.
+ • {groups} (`table`) List of fields in a |diagnostic-structure|
+ to associate with captures from {pat}.
+ • {severity_map} (`table`) A table mapping the severity field from
{groups} with an item from |vim.diagnostic.severity|.
- • {defaults} (table|nil) Table of default values for any fields not
+ • {defaults} (`table?`) Table of default values for any fields not
listed in {groups}. When omitted, numeric values
default to 0 and "severity" defaults to ERROR.
Return: ~
- Diagnostic|nil: |diagnostic-structure| or `nil` if {pat} fails to
- match {str}.
+ (`Diagnostic?`) |diagnostic-structure| or `nil` if {pat} fails to match
+ {str}.
open_float({opts}, {...}) *vim.diagnostic.open_float()*
Show diagnostics in a floating window.
Parameters: ~
- • {opts} (table|nil) Configuration table with the same keys as
+ • {opts} (`table?`) Configuration table with the same keys as
|vim.lsp.util.open_floating_preview()| in addition to the
following:
• bufnr: (number) Buffer number to show diagnostics from.
@@ -737,7 +737,7 @@ open_float({opts}, {...}) *vim.diagnostic.open_float()*
from |vim.diagnostic.config()|.
Return: ~
- integer|nil, integer|nil: ({float_bufnr}, {win_id})
+ (`integer?, integer?`) ({float_bufnr}, {win_id})
reset({namespace}, {bufnr}) *vim.diagnostic.reset()*
Remove all diagnostics from the given namespace.
@@ -748,27 +748,27 @@ reset({namespace}, {bufnr}) *vim.diagnostic.reset()*
re-displayed, use |vim.diagnostic.hide()|.
Parameters: ~
- • {namespace} (integer|nil) Diagnostic namespace. When omitted, remove
+ • {namespace} (`integer?`) Diagnostic namespace. When omitted, remove
diagnostics from all namespaces.
- • {bufnr} (integer|nil) Remove diagnostics for the given buffer.
+ • {bufnr} (`integer?`) Remove diagnostics for the given buffer.
When omitted, diagnostics are removed for all buffers.
set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()*
Set diagnostics for the given namespace and buffer.
Parameters: ~
- • {namespace} (integer) The diagnostic namespace
- • {bufnr} (integer) Buffer number
- • {diagnostics} (table) A list of diagnostic items
+ • {namespace} (`integer`) The diagnostic namespace
+ • {bufnr} (`integer`) Buffer number
+ • {diagnostics} (`table`) A list of diagnostic items
|diagnostic-structure|
- • {opts} (table|nil) Display options to pass to
+ • {opts} (`table?`) Display options to pass to
|vim.diagnostic.show()|
setloclist({opts}) *vim.diagnostic.setloclist()*
Add buffer diagnostics to the location list.
Parameters: ~
- • {opts} (table|nil) Configuration table with the following keys:
+ • {opts} (`table?`) Configuration table with the following keys:
• namespace: (number) Only add diagnostics from the given
namespace.
• winnr: (number, default 0) Window number to set location
@@ -783,7 +783,7 @@ setqflist({opts}) *vim.diagnostic.setqflist()*
Add all diagnostics to the quickfix list.
Parameters: ~
- • {opts} (table|nil) Configuration table with the following keys:
+ • {opts} (`table?`) Configuration table with the following keys:
• namespace: (number) Only add diagnostics from the given
namespace.
• open: (boolean, default true) Open quickfix list after
@@ -797,17 +797,17 @@ show({namespace}, {bufnr}, {diagnostics}, {opts})
Display diagnostics for the given namespace and buffer.
Parameters: ~
- • {namespace} (integer|nil) Diagnostic namespace. When omitted, show
+ • {namespace} (`integer?`) Diagnostic namespace. When omitted, show
diagnostics from all namespaces.
- • {bufnr} (integer|nil) Buffer number, or 0 for current buffer.
+ • {bufnr} (`integer?`) Buffer number, or 0 for current buffer.
When omitted, show diagnostics in all buffers.
- • {diagnostics} (table|nil) The diagnostics to display. When omitted,
+ • {diagnostics} (`table?`) The diagnostics to display. When omitted,
use the saved diagnostics for the given namespace and
buffer. This can be used to display a list of
diagnostics without saving them or to display only a
subset of diagnostics. May not be used when {namespace}
or {bufnr} is nil.
- • {opts} (table|nil) Display options. See
+ • {opts} (`table?`) Display options. See
|vim.diagnostic.config()|.
toqflist({diagnostics}) *vim.diagnostic.toqflist()*
@@ -815,9 +815,9 @@ toqflist({diagnostics}) *vim.diagnostic.toqflist()*
passed to |setqflist()| or |setloclist()|.
Parameters: ~
- • {diagnostics} (table) List of diagnostics |diagnostic-structure|.
+ • {diagnostics} (`table`) List of diagnostics |diagnostic-structure|.
Return: ~
- table[] of quickfix list items |setqflist-what|
+ (`table[]`) of quickfix list items |setqflist-what|
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 47c5c2379e..7e1c0a4a15 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -642,12 +642,12 @@ buf_attach_client({bufnr}, {client_id}) *vim.lsp.buf_attach_client()*
Without calling this, the server won't be notified of changes to a buffer.
Parameters: ~
- • {bufnr} (integer) Buffer handle, or 0 for current
- • {client_id} (integer) Client id
+ • {bufnr} (`integer`) Buffer handle, or 0 for current
+ • {client_id} (`integer`) Client id
Return: ~
- (boolean) success `true` if client was attached successfully; `false`
- otherwise
+ (`boolean`) success `true` if client was attached successfully;
+ `false` otherwise
buf_detach_client({bufnr}, {client_id}) *vim.lsp.buf_detach_client()*
Detaches client from the specified buffer. Note: While the server is
@@ -655,26 +655,26 @@ buf_detach_client({bufnr}, {client_id}) *vim.lsp.buf_detach_client()*
send notifications should it ignore this notification.
Parameters: ~
- • {bufnr} (integer) Buffer handle, or 0 for current
- • {client_id} (integer) Client id
+ • {bufnr} (`integer`) Buffer handle, or 0 for current
+ • {client_id} (`integer`) Client id
buf_is_attached({bufnr}, {client_id}) *vim.lsp.buf_is_attached()*
Checks if a buffer is attached for a particular client.
Parameters: ~
- • {bufnr} (integer) Buffer handle, or 0 for current
- • {client_id} (integer) the client id
+ • {bufnr} (`integer`) Buffer handle, or 0 for current
+ • {client_id} (`integer`) the client id
buf_notify({bufnr}, {method}, {params}) *vim.lsp.buf_notify()*
Send a notification to a server
Parameters: ~
- • {bufnr} (integer|nil) The number of the buffer
- • {method} (string) Name of the request method
- • {params} (any) Arguments to send to the server
+ • {bufnr} (`integer?`) The number of the buffer
+ • {method} (`string`) Name of the request method
+ • {params} (`any`) Arguments to send to the server
Return: ~
- (boolean) success true if any client returns true; false otherwise
+ (`boolean`) success true if any client returns true; false otherwise
*vim.lsp.buf_request_all()*
buf_request_all({bufnr}, {method}, {params}, {handler})
@@ -682,14 +682,15 @@ buf_request_all({bufnr}, {method}, {params}, {handler})
executes the `handler` callback with the combined result.
Parameters: ~
- • {bufnr} (integer) Buffer handle, or 0 for current.
- • {method} (string) LSP method name
- • {params} (table|nil) Parameters to send to the server
- • {handler} (function) Handler called after all requests are completed.
- Server results are passed as a `client_id:result` map.
+ • {bufnr} (`integer`) Buffer handle, or 0 for current.
+ • {method} (`string`) LSP method name
+ • {params} (`table?`) Parameters to send to the server
+ • {handler} (`function`) Handler called after all requests are
+ completed. Server results are passed as a
+ `client_id:result` map.
Return: ~
- (function) cancel Function that cancels all requests.
+ (`function`) cancel Function that cancels all requests.
*vim.lsp.buf_request_sync()*
buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
@@ -700,15 +701,15 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
result is different. Waits a maximum of {timeout_ms} (default 1000) ms.
Parameters: ~
- • {bufnr} (integer) Buffer handle, or 0 for current.
- • {method} (string) LSP method name
- • {params} (table|nil) Parameters to send to the server
- • {timeout_ms} (integer|nil) Maximum time in milliseconds to wait for a
+ • {bufnr} (`integer`) Buffer handle, or 0 for current.
+ • {method} (`string`) LSP method name
+ • {params} (`table?`) Parameters to send to the server
+ • {timeout_ms} (`integer?`) Maximum time in milliseconds to wait for a
result. Defaults to 1000
Return (multiple): ~
- (table) result Map of client_id:request_result.
- (string|nil) err On timeout, cancel, or error, `err` is a string
+ (`table`) result Map of client_id:request_result.
+ (`string?`) err On timeout, cancel, or error, `err` is a string
describing the failure reason, and `result` is nil.
client() *vim.lsp.client*
@@ -780,10 +781,10 @@ client_is_stopped({client_id}) *vim.lsp.client_is_stopped()*
Checks whether a client is stopped.
Parameters: ~
- • {client_id} (integer)
+ • {client_id} (`integer`)
Return: ~
- (boolean) stopped true if client is stopped, false otherwise.
+ (`boolean`) stopped true if client is stopped, false otherwise.
commands *vim.lsp.commands*
Registry for client side commands. This is an extension point for plugins
@@ -813,7 +814,7 @@ formatexpr({opts}) *vim.lsp.formatexpr()*
'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`.
Parameters: ~
- • {opts} (table) options for customizing the formatting expression
+ • {opts} (`table`) options for customizing the formatting expression
which takes the following optional keys:
• timeout_ms (default 500ms). The timeout period for the
formatting request.
@@ -823,26 +824,26 @@ get_buffers_by_client_id({client_id})
Returns list of buffers attached to client_id.
Parameters: ~
- • {client_id} (integer) client id
+ • {client_id} (`integer`) client id
Return: ~
- integer[] buffers list of buffer ids
+ (`integer[]`) buffers list of buffer ids
get_client_by_id({client_id}) *vim.lsp.get_client_by_id()*
Gets a client by id, or nil if the id is invalid. The returned client may
not yet be fully initialized.
Parameters: ~
- • {client_id} (integer) client id
+ • {client_id} (`integer`) client id
Return: ~
- (nil|lsp.Client) client rpc object
+ (`lsp.Client?`) client rpc object
get_clients({filter}) *vim.lsp.get_clients()*
Get active clients.
Parameters: ~
- • {filter} (table|nil) A table with key-value pairs used to filter the
+ • {filter} (`table?`) A table with key-value pairs used to filter the
returned clients. The available keys are:
• id (number): Only return clients with the given id
• bufnr (number): Only return clients attached to this
@@ -852,23 +853,23 @@ get_clients({filter}) *vim.lsp.get_clients()*
method
Return: ~
- lsp.Client []: List of |vim.lsp.client| objects
+ (`lsp.Client[]`) List of |vim.lsp.client| objects
get_log_path() *vim.lsp.get_log_path()*
Gets the path of the logfile used by the LSP client.
Return: ~
- (string) path to log file
+ (`string`) path to log file
omnifunc({findstart}, {base}) *vim.lsp.omnifunc()*
Implements 'omnifunc' compatible LSP completion.
Parameters: ~
- • {findstart} (integer) 0 or 1, decides behavior
- • {base} (integer) findstart=0, text to match against
+ • {findstart} (`integer`) 0 or 1, decides behavior
+ • {base} (`integer`) findstart=0, text to match against
Return: ~
- integer|table Decided by {findstart}:
+ (`integer|table`) Decided by {findstart}:
• findstart=0: column where the completion starts, or -2 or -3
• findstart=1: list of matches (actually just calls |complete()|)
@@ -887,7 +888,7 @@ set_log_level({level}) *vim.lsp.set_log_level()*
Use `lsp.log_levels` for reverse lookup.
Parameters: ~
- • {level} (integer|string) the case insensitive level name or number
+ • {level} (`integer|string`) the case insensitive level name or number
See also: ~
• |vim.lsp.log_levels|
@@ -932,9 +933,9 @@ start({config}, {opts}) *vim.lsp.start()*
`ftplugin/<filetype_name>.lua` (See |ftplugin-name|)
Parameters: ~
- • {config} (table) Same configuration as documented in
+ • {config} (`table`) Same configuration as documented in
|vim.lsp.start_client()|
- • {opts} (nil|lsp.StartOpts) Optional keyword arguments:
+ • {opts} (`lsp.StartOpts?`) Optional keyword arguments:
• reuse_client (fun(client: client, config: table): boolean)
Predicate used to decide if a client should be re-used.
Used on all running clients. The default implementation
@@ -943,7 +944,7 @@ start({config}, {opts}) *vim.lsp.start()*
re-using a client (0 for current).
Return: ~
- (integer|nil) client_id
+ (`integer?`) client_id
start_client({config}) *vim.lsp.start_client()*
Starts and initializes a client with the given configuration.
@@ -951,7 +952,7 @@ start_client({config}) *vim.lsp.start_client()*
Field `cmd` in {config} is required.
Parameters: ~
- • {config} ( lsp.ClientConfig ) Configuration for the server:
+ • {config} (`lsp.ClientConfig`) Configuration for the server:
• cmd: (string[]|fun(dispatchers: table):table) command a
list of strings treated like |jobstart()|. The command
must launch the language server process. `cmd` can also be
@@ -1060,7 +1061,7 @@ start_client({config}) *vim.lsp.start_client()*
initialization.
Return: ~
- (integer|nil) client_id. |vim.lsp.get_client_by_id()| Note: client may
+ (`integer?`) client_id. |vim.lsp.get_client_by_id()| Note: client may
not be fully initialized. Use `on_init` to do any actions once the
client has been initialized.
@@ -1069,7 +1070,7 @@ status() *vim.lsp.status()*
a string. Empty if there are no clients or if no new messages
Return: ~
- (string)
+ (`string`)
stop_client({client_id}, {force}) *vim.lsp.stop_client()*
Stops a client(s).
@@ -1083,9 +1084,9 @@ stop_client({client_id}, {force}) *vim.lsp.stop_client()*
for this client, then force-shutdown is attempted.
Parameters: ~
- • {client_id} integer|table id or |vim.lsp.client| object, or list
+ • {client_id} (`integer|table`) id or |vim.lsp.client| object, or list
thereof
- • {force} (boolean|nil) shutdown forcefully
+ • {force} (`boolean?`) shutdown forcefully
tagfunc({pattern}, {flags}) *vim.lsp.tagfunc()*
Provides an interface between the built-in client and 'tagfunc'.
@@ -1096,18 +1097,18 @@ tagfunc({pattern}, {flags}) *vim.lsp.tagfunc()*
LSP servers, falls back to using built-in tags.
Parameters: ~
- • {pattern} (string) Pattern used to find a workspace symbol
- • {flags} (string) See |tag-function|
+ • {pattern} (`string`) Pattern used to find a workspace symbol
+ • {flags} (`string`) See |tag-function|
Return: ~
- table[] tags A list of matching tags
+ (`table[]`) tags A list of matching tags
with({handler}, {override_config}) *vim.lsp.with()*
Function to manage overriding defaults for LSP handlers.
Parameters: ~
- • {handler} (lsp.Handler) See |lsp-handler|
- • {override_config} (table) Table containing the keys to override
+ • {handler} (`lsp.Handler`) See |lsp-handler|
+ • {override_config} (`table`) Table containing the keys to override
behavior of the {handler}
@@ -1126,7 +1127,7 @@ code_action({options}) *vim.lsp.buf.code_action()*
Selects a code action available at the current cursor position.
Parameters: ~
- • {options} (table|nil) Optional table which holds the following
+ • {options} (`table?`) Optional table which holds the following
optional fields:
• context: (table|nil) Corresponds to `CodeActionContext` of
the LSP specification:
@@ -1158,7 +1159,7 @@ completion({context}) *vim.lsp.buf.completion()*
called in Insert mode.
Parameters: ~
- • {context} (table) (context support not yet implemented) Additional
+ • {context} (`table`) (context support not yet implemented) Additional
information about the context in which a completion was
triggered (how it was triggered, and by which trigger
character, if applicable)
@@ -1174,7 +1175,7 @@ declaration({options}) *vim.lsp.buf.declaration()*
|vim.lsp.buf.definition()| instead.
Parameters: ~
- • {options} (table|nil) additional options
+ • {options} (`table?`) additional options
• reuse_win: (boolean) Jump to existing window if buffer is
already open.
• on_list: (function) |lsp-on-list-handler| replacing the
@@ -1184,7 +1185,7 @@ definition({options}) *vim.lsp.buf.definition()*
Jumps to the definition of the symbol under the cursor.
Parameters: ~
- • {options} (table|nil) additional options
+ • {options} (`table?`) additional options
• reuse_win: (boolean) Jump to existing window if buffer is
already open.
• on_list: (function) |lsp-on-list-handler| replacing the
@@ -1208,7 +1209,7 @@ document_symbol({options}) *vim.lsp.buf.document_symbol()*
Lists all symbols in the current buffer in the quickfix window.
Parameters: ~
- • {options} (table|nil) additional options
+ • {options} (`table?`) additional options
• on_list: (function) handler for list results. See
|lsp-on-list-handler|
@@ -1216,7 +1217,7 @@ execute_command({command_params}) *vim.lsp.buf.execute_command()*
Executes an LSP server command.
Parameters: ~
- • {command_params} (table) A valid `ExecuteCommandParams` object
+ • {command_params} (`table`) A valid `ExecuteCommandParams` object
See also: ~
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
@@ -1226,7 +1227,7 @@ format({options}) *vim.lsp.buf.format()*
server clients.
Parameters: ~
- • {options} (table|nil) Optional table which holds the following
+ • {options} (`table?`) Optional table which holds the following
optional fields:
• formatting_options (table|nil): Can be used to specify
FormattingOptions. Some unspecified options will be
@@ -1268,7 +1269,7 @@ implementation({options}) *vim.lsp.buf.implementation()*
quickfix window.
Parameters: ~
- • {options} (table|nil) additional options
+ • {options} (`table?`) additional options
• on_list: (function) |lsp-on-list-handler| replacing the
default handler. Called for any non-empty result.
@@ -1290,8 +1291,8 @@ references({context}, {options}) *vim.lsp.buf.references()*
window.
Parameters: ~
- • {context} (table|nil) Context for the request
- • {options} (table|nil) additional options
+ • {context} (`table?`) Context for the request
+ • {options} (`table?`) additional options
• on_list: (function) handler for list results. See
|lsp-on-list-handler|
@@ -1307,9 +1308,9 @@ rename({new_name}, {options}) *vim.lsp.buf.rename()*
Renames all references to the symbol under the cursor.
Parameters: ~
- • {new_name} (string|nil) If not provided, the user will be prompted
- for a new name using |vim.ui.input()|.
- • {options} (table|nil) additional options
+ • {new_name} (`string?`) If not provided, the user will be prompted for
+ a new name using |vim.ui.input()|.
+ • {options} (`table?`) additional options
• filter (function|nil): Predicate used to filter clients.
Receives a client as argument and must return a boolean.
Clients matching the predicate are included.
@@ -1324,7 +1325,7 @@ type_definition({options}) *vim.lsp.buf.type_definition()*
Jumps to the definition of the type of the symbol under the cursor.
Parameters: ~
- • {options} (table|nil) additional options
+ • {options} (`table?`) additional options
• reuse_win: (boolean) Jump to existing window if buffer is
already open.
• on_list: (function) |lsp-on-list-handler| replacing the
@@ -1338,8 +1339,8 @@ workspace_symbol({query}, {options}) *vim.lsp.buf.workspace_symbol()*
string means no filtering is done.
Parameters: ~
- • {query} (string|nil) optional
- • {options} (table|nil) additional options
+ • {query} (`string?`) optional
+ • {options} (`table?`) additional options
• on_list: (function) handler for list results. See
|lsp-on-list-handler|
@@ -1353,8 +1354,8 @@ get_namespace({client_id}, {is_pull})
|vim.diagnostic| for diagnostics
Parameters: ~
- • {client_id} (integer) The id of the LSP client
- • {is_pull} boolean? Whether the namespace is for a pull or push
+ • {client_id} (`integer`) The id of the LSP client
+ • {is_pull} (`boolean?`) Whether the namespace is for a pull or push
client. Defaults to push
*vim.lsp.diagnostic.on_diagnostic()*
@@ -1383,8 +1384,9 @@ on_diagnostic({_}, {result}, {ctx}, {config})
<
Parameters: ~
- • {ctx} lsp.HandlerContext
- • {config} (table) Configuration table (see |vim.diagnostic.config()|).
+ • {ctx} (`lsp.HandlerContext`)
+ • {config} (`table`) Configuration table (see
+ |vim.diagnostic.config()|).
*vim.lsp.diagnostic.on_publish_diagnostics()*
on_publish_diagnostics({_}, {result}, {ctx}, {config})
@@ -1412,8 +1414,9 @@ on_publish_diagnostics({_}, {result}, {ctx}, {config})
<
Parameters: ~
- • {ctx} lsp.HandlerContext
- • {config} (table) Configuration table (see |vim.diagnostic.config()|).
+ • {ctx} (`lsp.HandlerContext`)
+ • {config} (`table`) Configuration table (see
+ |vim.diagnostic.config()|).
==============================================================================
@@ -1423,33 +1426,33 @@ clear({client_id}, {bufnr}) *vim.lsp.codelens.clear()*
Clear the lenses
Parameters: ~
- • {client_id} (integer|nil) filter by client_id. All clients if nil
- • {bufnr} (integer|nil) filter by buffer. All buffers if nil
+ • {client_id} (`integer?`) filter by client_id. All clients if nil
+ • {bufnr} (`integer?`) filter by buffer. All buffers if nil
display({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.display()*
Display the lenses using virtual text
Parameters: ~
- • {lenses} lsp.CodeLens[]|nil lenses to display
- • {bufnr} (integer)
- • {client_id} (integer)
+ • {lenses} (`lsp.CodeLens[]?`) lenses to display
+ • {bufnr} (`integer`)
+ • {client_id} (`integer`)
get({bufnr}) *vim.lsp.codelens.get()*
Return all lenses for the given buffer
Parameters: ~
- • {bufnr} (integer) Buffer number. 0 can be used for the current
+ • {bufnr} (`integer`) Buffer number. 0 can be used for the current
buffer.
Return: ~
- lsp.CodeLens[]
+ (`lsp.CodeLens[]`)
*vim.lsp.codelens.on_codelens()*
on_codelens({err}, {result}, {ctx}, {_})
|lsp-handler| for the method `textDocument/codeLens`
Parameters: ~
- • {ctx} lsp.HandlerContext
+ • {ctx} (`lsp.HandlerContext`)
refresh() *vim.lsp.codelens.refresh()*
Refresh the codelens for the current buffer
@@ -1467,9 +1470,9 @@ save({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.save()*
Store lenses for a specific buffer and client
Parameters: ~
- • {lenses} lsp.CodeLens[]|nil lenses to store
- • {bufnr} (integer)
- • {client_id} (integer)
+ • {lenses} (`lsp.CodeLens[]?`) lenses to store
+ • {bufnr} (`integer`)
+ • {client_id} (`integer`)
==============================================================================
@@ -1482,8 +1485,8 @@ enable({bufnr}, {enable}) *vim.lsp.inlay_hint.enable()*
This API is pre-release (unstable).
Parameters: ~
- • {bufnr} (integer|nil) Buffer handle, or 0 or nil for current
- • {enable} (boolean|nil) true/nil to enable, false to disable
+ • {bufnr} (`integer?`) Buffer handle, or 0 or nil for current
+ • {enable} (`boolean?`) true/nil to enable, false to disable
get({filter}) *vim.lsp.inlay_hint.get()*
Get the list of inlay hints, (optionally) restricted by buffer or range.
@@ -1506,12 +1509,13 @@ get({filter}) *vim.lsp.inlay_hint.get()*
This API is pre-release (unstable).
Parameters: ~
- • {filter} vim.lsp.inlay_hint.get.filter ? Optional filters |kwargs|:
+ • {filter} (`vim.lsp.inlay_hint.get.filter?`) Optional filters
+ |kwargs|:
• bufnr (integer?): 0 for current buffer
• range (lsp.Range?)
Return: ~
- vim.lsp.inlay_hint.get.ret [] Each list item is a table with the
+ (`vim.lsp.inlay_hint.get.ret[]`) Each list item is a table with the
following fields:
• bufnr (integer)
• client_id (integer)
@@ -1522,10 +1526,10 @@ is_enabled({bufnr}) *vim.lsp.inlay_hint.is_enabled()*
This API is pre-release (unstable).
Parameters: ~
- • {bufnr} (integer|nil) Buffer handle, or 0 or nil for current
+ • {bufnr} (`integer?`) Buffer handle, or 0 or nil for current
Return: ~
- (boolean)
+ (`boolean`)
==============================================================================
@@ -1538,7 +1542,7 @@ force_refresh({bufnr}) *vim.lsp.semantic_tokens.force_refresh()*
highlighting (|vim.lsp.semantic_tokens.start()| has been called for it)
Parameters: ~
- • {bufnr} (integer|nil) filter by buffer. All buffers if nil, current
+ • {bufnr} (`integer?`) filter by buffer. All buffers if nil, current
buffer if 0
*vim.lsp.semantic_tokens.get_at_pos()*
@@ -1547,12 +1551,12 @@ get_at_pos({bufnr}, {row}, {col})
arguments, returns the token under the cursor.
Parameters: ~
- • {bufnr} (integer|nil) Buffer number (0 for current buffer, default)
- • {row} (integer|nil) Position row (default cursor position)
- • {col} (integer|nil) Position column (default cursor position)
+ • {bufnr} (`integer?`) Buffer number (0 for current buffer, default)
+ • {row} (`integer?`) Position row (default cursor position)
+ • {col} (`integer?`) Position column (default cursor position)
Return: ~
- (table|nil) List of tokens at position. Each token has the following
+ (`table?`) List of tokens at position. Each token has the following
fields:
• line (integer) line number, 0-based
• start_col (integer) start column, 0-based
@@ -1572,12 +1576,12 @@ highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts})
use inside |LspTokenUpdate| callbacks.
Parameters: ~
- • {token} (table) a semantic token, found as `args.data.token` in
+ • {token} (`table`) a semantic token, found as `args.data.token` in
|LspTokenUpdate|.
- • {bufnr} (integer) the buffer to highlight
- • {client_id} (integer) The ID of the |vim.lsp.client|
- • {hl_group} (string) Highlight group name
- • {opts} (table|nil) Optional parameters.
+ • {bufnr} (`integer`) the buffer to highlight
+ • {client_id} (`integer`) The ID of the |vim.lsp.client|
+ • {hl_group} (`string`) Highlight group name
+ • {opts} (`table?`) Optional parameters.
• priority: (integer|nil) Priority for the applied
extmark. Defaults to
`vim.highlight.priorities.semantic_tokens + 3`
@@ -1595,9 +1599,9 @@ start({bufnr}, {client_id}, {opts}) *vim.lsp.semantic_tokens.start()*
<
Parameters: ~
- • {bufnr} (integer)
- • {client_id} (integer)
- • {opts} (nil|table) Optional keyword arguments
+ • {bufnr} (`integer`)
+ • {client_id} (`integer`)
+ • {opts} (`table?`) Optional keyword arguments
• debounce (integer, default: 200): Debounce token
requests to the server by the given number in
milliseconds
@@ -1612,8 +1616,8 @@ stop({bufnr}, {client_id}) *vim.lsp.semantic_tokens.stop()*
from the buffer.
Parameters: ~
- • {bufnr} (integer)
- • {client_id} (integer)
+ • {bufnr} (`integer`)
+ • {client_id} (`integer`)
==============================================================================
@@ -1632,8 +1636,8 @@ hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()*
<
Parameters: ~
- • {ctx} lsp.HandlerContext
- • {config} (table) Configuration table.
+ • {ctx} (`lsp.HandlerContext`)
+ • {config} (`table`) Configuration table.
• border: (default=nil)
• Add borders to the floating window
• See |vim.lsp.util.open_floating_preview()| for more
@@ -1653,9 +1657,9 @@ signature_help({_}, {result}, {ctx}, {config})
<
Parameters: ~
- • {result} (table) Response from the language server
- • {ctx} lsp.HandlerContext Client context
- • {config} (table) Configuration table.
+ • {result} (`table`) Response from the language server
+ • {ctx} (`lsp.HandlerContext`) Client context
+ • {config} (`table`) Configuration table.
• border: (default=nil)
• Add borders to the floating window
• See |vim.lsp.util.open_floating_preview()| for more
@@ -1671,9 +1675,9 @@ apply_text_document_edit({text_document_edit}, {index}, {offset_encoding})
document.
Parameters: ~
- • {text_document_edit} (table) a `TextDocumentEdit` object
- • {index} (integer) Optional index of the edit, if from a
- list of edits (or nil, if not from a list)
+ • {text_document_edit} (`table`) a `TextDocumentEdit` object
+ • {index} (`integer`) Optional index of the edit, if from
+ a list of edits (or nil, if not from a list)
See also: ~
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit
@@ -1683,9 +1687,9 @@ apply_text_edits({text_edits}, {bufnr}, {offset_encoding})
Applies a list of text edits to a buffer.
Parameters: ~
- • {text_edits} (table) list of `TextEdit` objects
- • {bufnr} (integer) Buffer id
- • {offset_encoding} (string) utf-8|utf-16|utf-32
+ • {text_edits} (`table`) list of `TextEdit` objects
+ • {bufnr} (`integer`) Buffer id
+ • {offset_encoding} (`string`) utf-8|utf-16|utf-32
See also: ~
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit
@@ -1695,24 +1699,24 @@ apply_workspace_edit({workspace_edit}, {offset_encoding})
Applies a `WorkspaceEdit`.
Parameters: ~
- • {workspace_edit} (table) `WorkspaceEdit`
- • {offset_encoding} (string) utf-8|utf-16|utf-32 (required)
+ • {workspace_edit} (`table`) `WorkspaceEdit`
+ • {offset_encoding} (`string`) utf-8|utf-16|utf-32 (required)
buf_clear_references({bufnr}) *vim.lsp.util.buf_clear_references()*
Removes document highlights from a buffer.
Parameters: ~
- • {bufnr} (integer|nil) Buffer id
+ • {bufnr} (`integer?`) Buffer id
*vim.lsp.util.buf_highlight_references()*
buf_highlight_references({bufnr}, {references}, {offset_encoding})
Shows a list of document highlights for a certain buffer.
Parameters: ~
- • {bufnr} (integer) Buffer id
- • {references} (table) List of `DocumentHighlight` objects to
+ • {bufnr} (`integer`) Buffer id
+ • {references} (`table`) List of `DocumentHighlight` objects to
highlight
- • {offset_encoding} (string) One of "utf-8", "utf-16", "utf-32".
+ • {offset_encoding} (`string`) One of "utf-8", "utf-16", "utf-32".
See also: ~
• https://microsoft.github.io/language-server-protocol/specification/#textDocumentContentChangeEvent
@@ -1722,14 +1726,14 @@ character_offset({buf}, {row}, {col}, {offset_encoding})
Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer.
Parameters: ~
- • {buf} (integer) buffer number (0 for current)
- • {row} 0-indexed line
- • {col} 0-indexed byte offset in line
- • {offset_encoding} (string) utf-8|utf-16|utf-32 defaults to
+ • {buf} (`integer`) buffer number (0 for current)
+ • {row} (`integer`) 0-indexed line
+ • {col} (`integer`) 0-indexed byte offset in line
+ • {offset_encoding} (`string`) utf-8|utf-16|utf-32 defaults to
`offset_encoding` of first client of `buf`
Return: ~
- (integer) `offset_encoding` index of the character in line {row}
+ (`integer`) `offset_encoding` index of the character in line {row}
column {col} in buffer {buf}
*vim.lsp.util.convert_input_to_markdown_lines()*
@@ -1744,12 +1748,12 @@ convert_input_to_markdown_lines({input}, {contents})
modifications.
Parameters: ~
- • {input} (`MarkedString` | `MarkedString[]` | `MarkupContent`)
- • {contents} (table|nil) List of strings to extend with converted
- lines. Defaults to {}.
+ • {input} (`lsp.MarkedString|lsp.MarkedString[]|lsp.MarkupContent`)
+ • {contents} (`table?`) List of strings to extend with converted lines.
+ Defaults to {}.
Return: ~
- string[] extended with lines of converted markdown.
+ (`string[]`) extended with lines of converted markdown.
See also: ~
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
@@ -1759,15 +1763,15 @@ convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers})
Converts `textDocument/signatureHelp` response to markdown lines.
Parameters: ~
- • {signature_help} (table) Response of `textDocument/SignatureHelp`
- • {ft} (string|nil) filetype that will be use as the `lang`
+ • {signature_help} (`table`) Response of `textDocument/SignatureHelp`
+ • {ft} (`string?`) filetype that will be use as the `lang`
for the label markdown code block
- • {triggers} (table|nil) list of trigger characters from the lsp
+ • {triggers} (`table?`) list of trigger characters from the lsp
server. used to better determine parameter offsets
Return (multiple): ~
- (table|nil) table list of lines of converted markdown.
- (table|nil) table of active hl
+ (`table?`) table list of lines of converted markdown.
+ (`table?`) table of active hl
See also: ~
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
@@ -1776,10 +1780,10 @@ get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()*
Returns indentation size.
Parameters: ~
- • {bufnr} (integer|nil) Buffer handle, defaults to current
+ • {bufnr} (`integer?`) Buffer handle, defaults to current
Return: ~
- (integer) indentation size
+ (`integer`) indentation size
See also: ~
• 'shiftwidth'
@@ -1789,13 +1793,13 @@ jump_to_location({location}, {offset_encoding}, {reuse_win})
Jumps to a location.
Parameters: ~
- • {location} (table) (`Location`|`LocationLink`)
- • {offset_encoding} (string|nil) utf-8|utf-16|utf-32
- • {reuse_win} (boolean|nil) Jump to existing window if buffer is
+ • {location} (`table`) (`Location`|`LocationLink`)
+ • {offset_encoding} (`string?`) utf-8|utf-16|utf-32
+ • {reuse_win} (`boolean?`) Jump to existing window if buffer is
already open.
Return: ~
- (boolean) `true` if the jump succeeded
+ (`boolean`) `true` if the jump succeeded
*vim.lsp.util.locations_to_items()*
locations_to_items({locations}, {offset_encoding})
@@ -1809,23 +1813,23 @@ locations_to_items({locations}, {offset_encoding})
|setloclist()|.
Parameters: ~
- • {locations} lsp.Location[]|lsp.LocationLink[]
- • {offset_encoding} (string) offset_encoding for locations
+ • {locations} (`lsp.Location[]|lsp.LocationLink[]`)
+ • {offset_encoding} (`string`) offset_encoding for locations
utf-8|utf-16|utf-32 default to first client of
buffer
Return: ~
- vim.lsp.util.LocationItem [] list of items
+ (`vim.lsp.util.LocationItem[]`) list of items
lookup_section({settings}, {section}) *vim.lsp.util.lookup_section()*
Helper function to return nested values in language server settings
Parameters: ~
- • {settings} (table) language server settings
- • {section} string indicating the field of the settings table
+ • {settings} (`table`) language server settings
+ • {section} (`string`) indicating the field of the settings table
Return: ~
- table|string The value of settings accessed via section
+ (`table|string`) The value of settings accessed via section
*vim.lsp.util.make_floating_popup_options()*
make_floating_popup_options({width}, {height}, {opts})
@@ -1833,9 +1837,9 @@ make_floating_popup_options({width}, {height}, {opts})
table can be passed to |nvim_open_win()|.
Parameters: ~
- • {width} (integer) window width (in character cells)
- • {height} (integer) window height (in character cells)
- • {opts} (table) optional
+ • {width} (`integer`) window width (in character cells)
+ • {height} (`integer`) window height (in character cells)
+ • {opts} (`table`) optional
• offset_x (integer) offset to add to `col`
• offset_y (integer) offset to add to `row`
• border (string or table) override `border`
@@ -1851,7 +1855,7 @@ make_floating_popup_options({width}, {height}, {opts})
are not enough lines to display the full window height.
Return: ~
- (table) Options
+ (`table`) Options
*vim.lsp.util.make_formatting_params()*
make_formatting_params({options})
@@ -1859,10 +1863,10 @@ make_formatting_params({options})
cursor position.
Parameters: ~
- • {options} (table|nil) with valid `FormattingOptions` entries
+ • {options} (`table?`) with valid `FormattingOptions` entries
Return: ~
- lsp.DocumentFormattingParams object
+ (`lsp.DocumentFormattingParams`) object
See also: ~
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting
@@ -1873,18 +1877,18 @@ make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding})
similar to |vim.lsp.util.make_range_params()|.
Parameters: ~
- • {start_pos} integer[]|nil {row,col} mark-indexed position.
+ • {start_pos} (`integer[]?`) {row,col} mark-indexed position.
Defaults to the start of the last visual selection.
- • {end_pos} integer[]|nil {row,col} mark-indexed position.
+ • {end_pos} (`integer[]?`) {row,col} mark-indexed position.
Defaults to the end of the last visual selection.
- • {bufnr} (integer|nil) buffer handle or 0 for current,
+ • {bufnr} (`integer?`) buffer handle or 0 for current,
defaults to current
- • {offset_encoding} "utf-8"|"utf-16"|"utf-32"|nil defaults to
+ • {offset_encoding} (`"utf-8"|"utf-16"|"utf-32"?`) defaults to
`offset_encoding` of first client of `bufnr`
Return: ~
- (table) { textDocument = { uri = `current_file_uri` }, range = { start
- = `start_position`, end = `end_position` } }
+ (`table`) { textDocument = { uri = `current_file_uri` }, range = {
+ start = `start_position`, end = `end_position` } }
*vim.lsp.util.make_position_params()*
make_position_params({window}, {offset_encoding})
@@ -1892,14 +1896,14 @@ make_position_params({window}, {offset_encoding})
cursor position.
Parameters: ~
- • {window} (integer|nil) window handle or 0 for current,
+ • {window} (`integer?`) window handle or 0 for current,
defaults to current
- • {offset_encoding} (string|nil) utf-8|utf-16|utf-32|nil defaults to
+ • {offset_encoding} (`string?`) utf-8|utf-16|utf-32|nil defaults to
`offset_encoding` of first client of buffer of
`window`
Return: ~
- (table) `TextDocumentPositionParams` object
+ (`table`) `TextDocumentPositionParams` object
See also: ~
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams
@@ -1912,25 +1916,25 @@ make_range_params({window}, {offset_encoding})
`textDocument/rangeFormatting`.
Parameters: ~
- • {window} (integer|nil) window handle or 0 for current,
+ • {window} (`integer?`) window handle or 0 for current,
defaults to current
- • {offset_encoding} "utf-8"|"utf-16"|"utf-32"|nil defaults to
+ • {offset_encoding} (`"utf-8"|"utf-16"|"utf-32"?`) defaults to
`offset_encoding` of first client of buffer of
`window`
Return: ~
- (table) { textDocument = { uri = `current_file_uri` }, range = { start
- = `current_position`, end = `current_position` } }
+ (`table`) { textDocument = { uri = `current_file_uri` }, range = {
+ start = `current_position`, end = `current_position` } }
*vim.lsp.util.make_text_document_params()*
make_text_document_params({bufnr})
Creates a `TextDocumentIdentifier` object for the current buffer.
Parameters: ~
- • {bufnr} (integer|nil) Buffer handle, defaults to current
+ • {bufnr} (`integer?`) Buffer handle, defaults to current
Return: ~
- (table) `TextDocumentIdentifier`
+ (`table`) `TextDocumentIdentifier`
See also: ~
• https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier
@@ -1940,19 +1944,19 @@ make_workspace_params({added}, {removed})
Create the workspace params
Parameters: ~
- • {added} (table)
- • {removed} (table)
+ • {added} (`table`)
+ • {removed} (`table`)
*vim.lsp.util.open_floating_preview()*
open_floating_preview({contents}, {syntax}, {opts})
Shows contents in a floating window.
Parameters: ~
- • {contents} (table) of lines to show in window
- • {syntax} (string) of syntax to set for opened buffer
- • {opts} (table) with optional fields (additional keys are filtered
- with |vim.lsp.util.make_floating_popup_options()| before
- they are passed on to |nvim_open_win()|)
+ • {contents} (`table`) of lines to show in window
+ • {syntax} (`string`) of syntax to set for opened buffer
+ • {opts} (`table`) with optional fields (additional keys are
+ filtered with |vim.lsp.util.make_floating_popup_options()|
+ before they are passed on to |nvim_open_win()|)
• height: (integer) height of floating window
• width: (integer) width of floating window
• wrap: (boolean, default true) wrap long lines
@@ -1970,8 +1974,8 @@ open_floating_preview({contents}, {syntax}, {opts})
window with the same {focus_id}
Return (multiple): ~
- (integer) bufnr of newly created float window
- (integer) winid of newly created float window preview window
+ (`integer`) bufnr of newly created float window
+ (`integer`) winid of newly created float window preview window
preview_location({location}, {opts}) *vim.lsp.util.preview_location()*
Previews a location in a floating window
@@ -1982,33 +1986,33 @@ preview_location({location}, {opts}) *vim.lsp.util.preview_location()*
definition)
Parameters: ~
- • {location} (table) a single `Location` or `LocationLink`
+ • {location} (`table`) a single `Location` or `LocationLink`
Return (multiple): ~
- (integer|nil) buffer id of float window
- (integer|nil) window id of float window
+ (`integer?`) buffer id of float window
+ (`integer?`) window id of float window
rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()*
Rename old_fname to new_fname
Parameters: ~
- • {opts} (table)
+ • {opts} (`table`)
*vim.lsp.util.show_document()*
show_document({location}, {offset_encoding}, {opts})
Shows document and optionally jumps to the location.
Parameters: ~
- • {location} (table) (`Location`|`LocationLink`)
- • {offset_encoding} (string|nil) utf-8|utf-16|utf-32
- • {opts} (table|nil) options
+ • {location} (`table`) (`Location`|`LocationLink`)
+ • {offset_encoding} (`string?`) utf-8|utf-16|utf-32
+ • {opts} (`table?`) options
• reuse_win (boolean) Jump to existing window if
buffer is already open.
• focus (boolean) Whether to focus/jump to location
if possible. Defaults to true.
Return: ~
- (boolean) `true` if succeeded
+ (`boolean`) `true` if succeeded
*vim.lsp.util.stylize_markdown()*
stylize_markdown({bufnr}, {contents}, {opts})
@@ -2023,8 +2027,8 @@ stylize_markdown({bufnr}, {contents}, {opts})
`open_floating_preview` instead
Parameters: ~
- • {contents} (table) of lines to show in window
- • {opts} (table) with optional fields
+ • {contents} (`table`) of lines to show in window
+ • {opts} (`table`) with optional fields
• height of floating window
• width of floating window
• wrap_at character to wrap at for computing height
@@ -2033,13 +2037,13 @@ stylize_markdown({bufnr}, {contents}, {opts})
• separator insert separator after code block
Return: ~
- (table) stripped content
+ (`table`) stripped content
symbols_to_items({symbols}, {bufnr}) *vim.lsp.util.symbols_to_items()*
Converts symbols to quickfix list items.
Parameters: ~
- • {symbols} (table) DocumentSymbol[] or SymbolInformation[]
+ • {symbols} (`table`) DocumentSymbol[] or SymbolInformation[]
==============================================================================
@@ -2049,32 +2053,32 @@ get_filename() *vim.lsp.log.get_filename()*
Returns the log filename.
Return: ~
- (string) log filename
+ (`string`) log filename
get_level() *vim.lsp.log.get_level()*
Gets the current log level.
Return: ~
- (integer) current log level
+ (`integer`) current log level
set_format_func({handle}) *vim.lsp.log.set_format_func()*
Sets formatting function used to format logs
Parameters: ~
- • {handle} (function) function to apply to logging arguments, pass
+ • {handle} (`function`) function to apply to logging arguments, pass
vim.inspect for multi-line formatting
set_level({level}) *vim.lsp.log.set_level()*
Sets the current log level.
Parameters: ~
- • {level} (string|integer) One of `vim.lsp.log.levels`
+ • {level} (`string|integer`) One of `vim.lsp.log.levels`
should_log({level}) *vim.lsp.log.should_log()*
Checks whether the level is sufficient for logging.
Parameters: ~
- • {level} (integer) log level
+ • {level} (`integer`) log level
Return: ~
(bool) true if would log, false if not
@@ -2088,13 +2092,13 @@ connect({host}, {port}) *vim.lsp.rpc.connect()*
and port
Parameters: ~
- • {host} (string) host to connect to
- • {port} (integer) port to connect to
+ • {host} (`string`) host to connect to
+ • {port} (`integer`) port to connect to
Return: ~
- fun(dispatchers: vim.lsp.rpc.Dispatchers ): vim.lsp.rpc.PublicClient function
- intended to be passed to |vim.lsp.start_client()| or |vim.lsp.start()|
- on the field cmd
+ (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
+ function intended to be passed to |vim.lsp.start_client()| or
+ |vim.lsp.start()| on the field cmd
*vim.lsp.rpc.domain_socket_connect()*
domain_socket_connect({pipe_path})
@@ -2103,48 +2107,48 @@ domain_socket_connect({pipe_path})
name on Windows)
Parameters: ~
- • {pipe_path} (string) file path of the domain socket (Unix) or name of
- the named pipe (Windows) to connect to
+ • {pipe_path} (`string`) file path of the domain socket (Unix) or name
+ of the named pipe (Windows) to connect to
Return: ~
- fun(dispatchers: vim.lsp.rpc.Dispatchers ):
- vim.lsp.rpc.PublicClient::function intended to be passed to
- |vim.lsp.start_client()| or |vim.lsp.start()| on the field cmd
+ (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`)
+ function intended to be passed to |vim.lsp.start_client()| or
+ |vim.lsp.start()| on the field cmd
format_rpc_error({err}) *vim.lsp.rpc.format_rpc_error()*
Constructs an error message from an LSP error object.
Parameters: ~
- • {err} (table) The error object
+ • {err} (`table`) The error object
Return: ~
- string::The formatted error message
+ (`string`) The formatted error message
notify({method}, {params}) *vim.lsp.rpc.notify()*
Sends a notification to the LSP server.
Parameters: ~
- • {method} (string) The invoked LSP method
- • {params} (table?) Parameters for the invoked LSP method
+ • {method} (`string`) The invoked LSP method
+ • {params} (`table?`) Parameters for the invoked LSP method
Return: ~
- (boolean) `true` if notification could be sent, `false` if not
+ (`boolean`) `true` if notification could be sent, `false` if not
*vim.lsp.rpc.request()*
request({method}, {params}, {callback}, {notify_reply_callback})
Sends a request to the LSP server and runs {callback} upon response.
Parameters: ~
- • {method} (string) The invoked LSP method
- • {params} (table?) Parameters for the invoked LSP
+ • {method} (`string`) The invoked LSP method
+ • {params} (`table?`) Parameters for the invoked LSP
method
- • {callback} fun(err: lsp.ResponseError | nil, result:
- any) Callback to invoke
- • {notify_reply_callback} (function?) Callback to invoke as soon as a
+ • {callback} (`fun(err: lsp.ResponseError?, result: any)`)
+ Callback to invoke
+ • {notify_reply_callback} (`function?`) Callback to invoke as soon as a
request is no longer pending
Return: ~
- (boolean) success, integer|nil request_id true, message_id if request
+ (`boolean success, integer? request_id`) true, message_id if request
could be sent, `false` if not
*vim.lsp.rpc.rpc_response_error()*
@@ -2152,12 +2156,12 @@ rpc_response_error({code}, {message}, {data})
Creates an RPC response object/table.
Parameters: ~
- • {code} (integer) RPC error code defined by JSON RPC
- • {message} (string|nil) arbitrary message to send to server
- • {data} any|nil arbitrary data to send to server
+ • {code} (`integer`) RPC error code defined by JSON RPC
+ • {message} (`string?`) arbitrary message to send to server
+ • {data} (`any?`) arbitrary data to send to server
Return: ~
- vim.lsp.rpc.Error
+ (`vim.lsp.rpc.Error`)
*vim.lsp.rpc.start()*
start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
@@ -2167,17 +2171,17 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
|vim.lsp.rpc.connect()|
Parameters: ~
- • {cmd} (string) Command to start the LSP server.
- • {cmd_args} string[] List of additional string arguments to
- pass to {cmd}.
- • {dispatchers} (table|nil) Dispatchers for LSP message types.
+ • {cmd} (`string`) Command to start the LSP server.
+ • {cmd_args} (`string[]`) List of additional string arguments
+ to pass to {cmd}.
+ • {dispatchers} (`table?`) Dispatchers for LSP message types.
Valid dispatcher names are:
• `"notification"`
• `"server_request"`
• `"on_error"`
• `"on_exit"`
- • {extra_spawn_params} (table|nil) Additional context for the LSP
- server process. May contain:
+ • {extra_spawn_params} (`table?`) Additional context for the LSP server
+ process. May contain:
• {cwd} (string) Working directory for the LSP
server process
• {detached?} (boolean) Detach the LSP server
@@ -2187,7 +2191,7 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
variables for LSP server process
Return: ~
- (table|nil) client RPC object, with these methods:
+ (`table?`) client RPC object, with these methods:
• `notify()` |vim.lsp.rpc.notify()|
• `request()` |vim.lsp.rpc.request()|
• `is_closing()` returns a boolean indicating if the RPC is closing.
@@ -2203,7 +2207,7 @@ make_client_capabilities()
capabilities.
Return: ~
- lsp.ClientCapabilities
+ (`lsp.ClientCapabilities`)
Methods *vim.lsp.protocol.Methods*
LSP method names.
@@ -2216,10 +2220,10 @@ resolve_capabilities({server_capabilities})
Creates a normalized object describing LSP server capabilities.
Parameters: ~
- • {server_capabilities} (table) Table of capabilities supported by the
- server
+ • {server_capabilities} (`table`) Table of capabilities supported by
+ the server
Return: ~
- lsp.ServerCapabilities|nil Normalized table of capabilities
+ (`lsp.ServerCapabilities?`) Normalized table of capabilities
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index b558a3fc8d..aadc73e95c 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -606,7 +606,7 @@ vim.highlight.on_yank({opts}) *vim.highlight.on_yank()*
Highlight the yanked text
Parameters: ~
- • {opts} (table|nil) Optional parameters
+ • {opts} (`table?`) Optional parameters
• higroup highlight group for yanked region (default
"IncSearch")
• timeout time in ms before highlight is cleared (default 150)
@@ -631,14 +631,14 @@ vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts})
Apply highlight group to range of text.
Parameters: ~
- • {bufnr} (integer) Buffer number to apply highlighting to
- • {ns} (integer) Namespace to add highlight to
- • {higroup} (string) Highlight group to use for highlighting
- • {start} integer[]|string Start of region as a (line, column) tuple
- or string accepted by |getpos()|
- • {finish} integer[]|string End of region as a (line, column) tuple or
- string accepted by |getpos()|
- • {opts} (table|nil) Optional parameters
+ • {bufnr} (`integer`) Buffer number to apply highlighting to
+ • {ns} (`integer`) Namespace to add highlight to
+ • {higroup} (`string`) Highlight group to use for highlighting
+ • {start} (`integer[]|string`) Start of region as a (line, column)
+ tuple or string accepted by |getpos()|
+ • {finish} (`integer[]|string`) End of region as a (line, column)
+ tuple or string accepted by |getpos()|
+ • {opts} (`table?`) Optional parameters
• regtype type of range (see |setreg()|, default charwise)
• inclusive boolean indicating whether the range is
end-inclusive (default false)
@@ -660,10 +660,10 @@ vim.regex({re}) *vim.regex()*
They can be controlled with flags, see |/magic| and |/ignorecase|.
Parameters: ~
- • {re} (string)
+ • {re} (`string`)
Return: ~
- vim.regex
+ (`vim.regex`)
*regex:match_line()*
vim.regex:match_line({bufnr}, {line_idx}, {start}, {end_})
@@ -673,10 +673,10 @@ vim.regex:match_line({bufnr}, {line_idx}, {start}, {end_})
will be relative {start}.
Parameters: ~
- • {bufnr} (integer)
- • {line_idx} (integer)
- • {start} (integer|nil)
- • {end_} (integer|nil)
+ • {bufnr} (`integer`)
+ • {line_idx} (`integer`)
+ • {start} (`integer?`)
+ • {end_} (`integer?`)
vim.regex:match_str({str}) *regex:match_str()*
Match the string against the regex. If the string should match the regex
@@ -686,7 +686,7 @@ vim.regex:match_str({str}) *regex:match_str()*
be directly used as a condition in an if-statement.
Parameters: ~
- • {str} (string)
+ • {str} (`string`)
==============================================================================
@@ -712,9 +712,9 @@ vim.diff({a}, {b}, {opts}) *vim.diff()*
<
Parameters: ~
- • {a} (string) First string to compare
- • {b} (string) Second string to compare
- • {opts} table<string,any> Optional parameters:
+ • {a} (`string`) First string to compare
+ • {b} (`string`) Second string to compare
+ • {opts} (`table<string,any>`) Optional parameters:
• `on_hunk` (callback): Invoked for each hunk in the diff.
Return a negative number to cancel the callback for any
remaining hunks. Args:
@@ -753,7 +753,7 @@ vim.diff({a}, {b}, {opts}) *vim.diff()*
the internal diff library.
Return: ~
- string|table|nil See {opts.result_type}. `nil` if {opts.on_hunk} is
+ (`string|table?`) See {opts.result_type}. `nil` if {opts.on_hunk} is
given.
@@ -768,7 +768,7 @@ vim.mpack.decode({str}) *vim.mpack.decode()*
Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object.
Parameters: ~
- • {str} (string)
+ • {str} (`string`)
vim.mpack.encode({obj}) *vim.mpack.encode()*
Encodes (or "packs") Lua object {obj} as msgpack in a Lua string.
@@ -794,8 +794,8 @@ vim.json.decode({str}, {opts}) *vim.json.decode()*
<
Parameters: ~
- • {str} (string) Stringified JSON data.
- • {opts} table<string,any>|nil Options table with keys:
+ • {str} (`string`) Stringified JSON data.
+ • {opts} (`table<string,any>?`) Options table with keys:
• luanil: (table) Table with keys:
• object: (boolean) When true, converts `null` in JSON
objects to Lua `nil` instead of |vim.NIL|.
@@ -803,16 +803,16 @@ vim.json.decode({str}, {opts}) *vim.json.decode()*
to Lua `nil` instead of |vim.NIL|.
Return: ~
- any
+ (`any`)
vim.json.encode({obj}) *vim.json.encode()*
Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
Parameters: ~
- • {obj} any
+ • {obj} (`any`)
Return: ~
- (string)
+ (`string`)
==============================================================================
@@ -822,19 +822,19 @@ vim.base64.decode({str}) *vim.base64.decode()*
Decode a Base64 encoded string.
Parameters: ~
- • {str} (string) Base64 encoded string
+ • {str} (`string`) Base64 encoded string
Return: ~
- (string) Decoded string
+ (`string`) Decoded string
vim.base64.encode({str}) *vim.base64.encode()*
Encode {str} using Base64.
Parameters: ~
- • {str} (string) String to encode
+ • {str} (`string`) String to encode
Return: ~
- (string) Encoded string
+ (`string`) Encoded string
==============================================================================
@@ -857,11 +857,11 @@ vim.spell.check({str}) *vim.spell.check()*
<
Parameters: ~
- • {str} (string)
+ • {str} (`string`)
Return: ~
- `{[1]: string, [2]: string, [3]: string}[]` List of tuples with three
- items:
+ (`{[1]: string, [2]: string, [3]: string}[]`) List of tuples with
+ three items:
• The badly spelled word.
• The type of the spelling error: "bad" spelling mistake "rare" rare
word "local" word only valid in another region "caps" word should
@@ -945,13 +945,13 @@ vim.iconv({str}, {from}, {to}, {opts}) *vim.iconv()*
":Man 3 iconv".
Parameters: ~
- • {str} (string) Text to convert
- • {from} (number) Encoding of {str}
- • {to} (number) Target encoding
- • {opts} table<string,any>|nil
+ • {str} (`string`) Text to convert
+ • {from} (`number`) Encoding of {str}
+ • {to} (`number`) Target encoding
+ • {opts} (`table<string,any>?`)
Return: ~
- (string|nil) Converted string if conversion succeeds, `nil` otherwise.
+ (`string?`) Converted string if conversion succeeds, `nil` otherwise.
vim.in_fast_event() *vim.in_fast_event()*
Returns true if the code is executing as part of a "fast" event handler,
@@ -967,10 +967,10 @@ vim.rpcnotify({channel}, {method}, {args}, {...}) *vim.rpcnotify()*
This function also works in a fast callback |lua-loop-callbacks|.
Parameters: ~
- • {channel} (integer)
- • {method} (string)
- • {args} any[]|nil
- • {...} any|nil
+ • {channel} (`integer`)
+ • {method} (`string`)
+ • {args} (`any[]?`)
+ • {...} (`any?`)
vim.rpcrequest({channel}, {method}, {args}, {...}) *vim.rpcrequest()*
Sends a request to {channel} to invoke {method} via |RPC| and blocks until
@@ -980,17 +980,17 @@ vim.rpcrequest({channel}, {method}, {args}, {...}) *vim.rpcrequest()*
special value
Parameters: ~
- • {channel} (integer)
- • {method} (string)
- • {args} any[]|nil
- • {...} any|nil
+ • {channel} (`integer`)
+ • {method} (`string`)
+ • {args} (`any[]?`)
+ • {...} (`any?`)
vim.schedule({fn}) *vim.schedule()*
Schedules {fn} to be invoked soon by the main event-loop. Useful to avoid
|textlock| or other temporary restrictions.
Parameters: ~
- • {fn} (function)
+ • {fn} (`function`)
vim.str_byteindex({str}, {index}, {use_utf16}) *vim.str_byteindex()*
Convert UTF-32 or UTF-16 {index} to byte index. If {use_utf16} is not
@@ -1001,9 +1001,9 @@ vim.str_byteindex({str}, {index}, {use_utf16}) *vim.str_byteindex()*
sequence.
Parameters: ~
- • {str} (string)
- • {index} (number)
- • {use_utf16} any|nil
+ • {str} (`string`)
+ • {index} (`number`)
+ • {use_utf16} (`any?`)
vim.str_utf_end({str}, {index}) *vim.str_utf_end()*
Gets the distance (in bytes) from the last byte of the codepoint
@@ -1020,11 +1020,11 @@ vim.str_utf_end({str}, {index}) *vim.str_utf_end()*
<
Parameters: ~
- • {str} (string)
- • {index} (number)
+ • {str} (`string`)
+ • {index} (`number`)
Return: ~
- (number)
+ (`number`)
vim.str_utf_pos({str}) *vim.str_utf_pos()*
Gets a list of the starting byte positions of each UTF-8 codepoint in the
@@ -1033,10 +1033,10 @@ vim.str_utf_pos({str}) *vim.str_utf_pos()*
Embedded NUL bytes are treated as terminating the string.
Parameters: ~
- • {str} (string)
+ • {str} (`string`)
Return: ~
- (table)
+ (`table`)
vim.str_utf_start({str}, {index}) *vim.str_utf_start()*
Gets the distance (in bytes) from the starting byte of the codepoint
@@ -1056,11 +1056,11 @@ vim.str_utf_start({str}, {index}) *vim.str_utf_start()*
<
Parameters: ~
- • {str} (string)
- • {index} (number)
+ • {str} (`string`)
+ • {index} (`number`)
Return: ~
- (number)
+ (`number`)
vim.str_utfindex({str}, {index}) *vim.str_utfindex()*
Convert byte index to UTF-32 and UTF-16 indices. If {index} is not
@@ -1072,23 +1072,23 @@ vim.str_utfindex({str}, {index}) *vim.str_utfindex()*
that sequence.
Parameters: ~
- • {str} (string)
- • {index} (number|nil)
+ • {str} (`string`)
+ • {index} (`number?`)
Return (multiple): ~
- (integer) UTF-32 index
- (integer) UTF-16 index
+ (`integer`) UTF-32 index
+ (`integer`) UTF-16 index
vim.stricmp({a}, {b}) *vim.stricmp()*
Compares strings case-insensitively.
Parameters: ~
- • {a} (string)
- • {b} (string)
+ • {a} (`string`)
+ • {b} (`string`)
Return: ~
- 0|1|-1 if strings are equal, {a} is greater than {b} or {a} is lesser
- than {b}, respectively.
+ (`0|1|-1`) if strings are equal, {a} is greater than {b} or {a} is
+ lesser than {b}, respectively.
vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()*
Attach to ui events, similar to |nvim_ui_attach()| but receive events as
@@ -1126,16 +1126,16 @@ vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()*
<
Parameters: ~
- • {ns} (integer)
- • {options} table<string, any>
- • {callback} fun()
+ • {ns} (`integer`)
+ • {options} (`table<string, any>`)
+ • {callback} (`fun()`)
vim.ui_detach({ns}) *vim.ui_detach()*
Detach a callback previously attached with |vim.ui_attach()| for the given
namespace {ns}.
Parameters: ~
- • {ns} (integer)
+ • {ns} (`integer`)
vim.wait({time}, {callback}, {interval}, {fast_only}) *vim.wait()*
Wait for {time} in milliseconds until {callback} returns `true`.
@@ -1170,16 +1170,16 @@ vim.wait({time}, {callback}, {interval}, {fast_only}) *vim.wait()*
<
Parameters: ~
- • {time} (integer) Number of milliseconds to wait
- • {callback} fun():|nil boolean Optional callback. Waits until
+ • {time} (`integer`) Number of milliseconds to wait
+ • {callback} (`fun(): boolean?`) Optional callback. Waits until
{callback} returns true
- • {interval} (integer|nil) (Approximate) number of milliseconds to
- wait between polls
- • {fast_only} (boolean|nil) If true, only |api-fast| events will be
+ • {interval} (`integer?`) (Approximate) number of milliseconds to wait
+ between polls
+ • {fast_only} (`boolean?`) If true, only |api-fast| events will be
processed.
Return: ~
- boolean, nil|-1|-2
+ (`boolean, -1|-2?`)
• If {callback} returns `true` during the {time}: `true, nil`
• If {callback} never returns `true` during the {time}: `false, -1`
• If {callback} is interrupted during the {time}: `false, -2`
@@ -1376,7 +1376,7 @@ Option:append({value}) *vim.opt:append()*
<
Parameters: ~
- • {value} (string) Value to append
+ • {value} (`string`) Value to append
Option:get() *vim.opt:get()*
Returns a Lua-representation of the option. Boolean, number and string
@@ -1422,7 +1422,7 @@ Option:get() *vim.opt:get()*
<
Return: ~
- string|integer|boolean|nil value of option
+ (`string|integer|boolean?`) value of option
Option:prepend({value}) *vim.opt:prepend()*
Prepend a value to string-style options. See |:set^=|
@@ -1433,7 +1433,7 @@ Option:prepend({value}) *vim.opt:prepend()*
<
Parameters: ~
- • {value} (string) Value to prepend
+ • {value} (`string`) Value to prepend
Option:remove({value}) *vim.opt:remove()*
Remove a value from string-style options. See |:set-=|
@@ -1444,7 +1444,7 @@ Option:remove({value}) *vim.opt:remove()*
<
Parameters: ~
- • {value} (string) Value to remove
+ • {value} (`string`) Value to remove
vim.bo *vim.bo*
Get or set buffer-scoped |options| for the buffer with number {bufnr}.
@@ -1471,7 +1471,7 @@ vim.env *vim.env*
<
Parameters: ~
- • {var} (string)
+ • {var} (`string`)
vim.go *vim.go*
Get or set global |options|. Like `:setglobal`. Invalid key is an error.
@@ -1553,12 +1553,12 @@ vim.cmd *vim.cmd()*
<
Parameters: ~
- • {command} string|table Command(s) to execute. If a string, executes
- multiple lines of Vim script at once. In this case, it is
- an alias to |nvim_exec2()|, where `opts.output` is set to
- false. Thus it works identical to |:source|. If a table,
- executes a single command. In this case, it is an alias to
- |nvim_cmd()| where `opts` is empty.
+ • {command} (`string|table`) Command(s) to execute. If a string,
+ executes multiple lines of Vim script at once. In this
+ case, it is an alias to |nvim_exec2()|, where `opts.output`
+ is set to false. Thus it works identical to |:source|. If a
+ table, executes a single command. In this case, it is an
+ alias to |nvim_cmd()| where `opts` is empty.
See also: ~
• |ex-cmd-index|
@@ -1570,34 +1570,34 @@ vim.defer_fn({fn}, {timeout}) *vim.defer_fn()*
|vim.schedule_wrap()|ped automatically, so API functions are safe to call.
Parameters: ~
- • {fn} (function) Callback to call once `timeout` expires
- • {timeout} (integer) Number of milliseconds to wait before calling
+ • {fn} (`function`) Callback to call once `timeout` expires
+ • {timeout} (`integer`) Number of milliseconds to wait before calling
`fn`
Return: ~
- (table) timer luv timer object
+ (`table`) timer luv timer object
*vim.deprecate()*
vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
Shows a deprecation message to the user.
Parameters: ~
- • {name} string Deprecated feature (function, API, etc.).
- • {alternative} (string|nil) Suggested alternative feature.
- • {version} string Version when the deprecated function will be
+ • {name} (`string`) Deprecated feature (function, API, etc.).
+ • {alternative} (`string?`) Suggested alternative feature.
+ • {version} (`string`) Version when the deprecated function will be
removed.
- • {plugin} string|nil Name of the plugin that owns the deprecated
+ • {plugin} (`string?`) Name of the plugin that owns the deprecated
feature. Defaults to "Nvim".
- • {backtrace} boolean|nil Prints backtrace. Defaults to true.
+ • {backtrace} (`boolean?`) Prints backtrace. Defaults to true.
Return: ~
- (string|nil) Deprecated message, or nil if no message was shown.
+ (`string?`) Deprecated message, or nil if no message was shown.
vim.inspect *vim.inspect()*
Gets a human-readable representation of the given object.
Return: ~
- (string)
+ (`string`)
See also: ~
• |vim.print()|
@@ -1613,10 +1613,10 @@ vim.keycode({str}) *vim.keycode()*
<
Parameters: ~
- • {str} (string) String to be converted.
+ • {str} (`string`) String to be converted.
Return: ~
- (string)
+ (`string`)
See also: ~
• |nvim_replace_termcodes()|
@@ -1635,9 +1635,9 @@ vim.notify({msg}, {level}, {opts}) *vim.notify()*
writes to |:messages|.
Parameters: ~
- • {msg} (string) Content of the notification to show to the user.
- • {level} (integer|nil) One of the values from |vim.log.levels|.
- • {opts} (table|nil) Optional parameters. Unused by default.
+ • {msg} (`string`) Content of the notification to show to the user.
+ • {level} (`integer?`) One of the values from |vim.log.levels|.
+ • {opts} (`table?`) Optional parameters. Unused by default.
vim.notify_once({msg}, {level}, {opts}) *vim.notify_once()*
Displays a notification only one time.
@@ -1646,12 +1646,12 @@ vim.notify_once({msg}, {level}, {opts}) *vim.notify_once()*
display a notification.
Parameters: ~
- • {msg} (string) Content of the notification to show to the user.
- • {level} (integer|nil) One of the values from |vim.log.levels|.
- • {opts} (table|nil) Optional parameters. Unused by default.
+ • {msg} (`string`) Content of the notification to show to the user.
+ • {level} (`integer?`) One of the values from |vim.log.levels|.
+ • {opts} (`table?`) Optional parameters. Unused by default.
Return: ~
- (boolean) true if message was displayed, else false
+ (`boolean`) true if message was displayed, else false
vim.on_key({fn}, {ns_id}) *vim.on_key()*
Adds Lua function {fn} with namespace id {ns_id} as a listener to every,
@@ -1666,15 +1666,15 @@ vim.on_key({fn}, {ns_id}) *vim.on_key()*
• {fn} will receive the keys after mappings have been evaluated
Parameters: ~
- • {fn} fun(key: string) Function invoked on every key press.
+ • {fn} (`fun(key: string)`) Function invoked on every key press.
|i_CTRL-V| Returning nil removes the callback associated with
namespace {ns_id}.
- • {ns_id} integer? Namespace ID. If nil or 0, generates and returns a
- new |nvim_create_namespace()| id.
+ • {ns_id} (`integer?`) Namespace ID. If nil or 0, generates and returns
+ a new |nvim_create_namespace()| id.
Return: ~
- (integer) Namespace id associated with {fn}. Or count of all callbacks
- if on_key() is called without arguments.
+ (`integer`) Namespace id associated with {fn}. Or count of all
+ callbacks if on_key() is called without arguments.
vim.paste({lines}, {phase}) *vim.paste()*
Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the
@@ -1693,9 +1693,9 @@ vim.paste({lines}, {phase}) *vim.paste()*
<
Parameters: ~
- • {lines} string[] # |readfile()|-style list of lines to paste.
+ • {lines} (`string[]`) |readfile()|-style list of lines to paste.
|channel-lines|
- • {phase} paste_phase -1: "non-streaming" paste: the call contains all
+ • {phase} (`-1|1|2|3`) -1: "non-streaming" paste: the call contains all
lines. If paste is "streamed", `phase` indicates
the stream state:
• 1: starts the paste (exactly once)
@@ -1703,10 +1703,10 @@ vim.paste({lines}, {phase}) *vim.paste()*
• 3: ends the paste (exactly once)
Return: ~
- (boolean) result false if client should cancel the paste.
+ (`boolean`) result false if client should cancel the paste.
See also: ~
- • |paste| @alias paste_phase -1 | 1 | 2 | 3
+ • |paste|
vim.print({...}) *vim.print()*
"Pretty prints" the given arguments and returns them unmodified.
@@ -1716,7 +1716,7 @@ vim.print({...}) *vim.print()*
<
Return: ~
- any given arguments.
+ (`any`) given arguments.
See also: ~
• |vim.inspect()|
@@ -1732,17 +1732,17 @@ vim.region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})
returned as |v:maxcol| (big number).
Parameters: ~
- • {bufnr} (integer) Buffer number, or 0 for current buffer
- • {pos1} integer[]|string Start of region as a (line, column)
+ • {bufnr} (`integer`) Buffer number, or 0 for current buffer
+ • {pos1} (`integer[]|string`) Start of region as a (line, column)
tuple or |getpos()|-compatible string
- • {pos2} integer[]|string End of region as a (line, column) tuple
- or |getpos()|-compatible string
- • {regtype} (string) |setreg()|-style selection type
- • {inclusive} (boolean) Controls whether the ending column is inclusive
- (see also 'selection').
+ • {pos2} (`integer[]|string`) End of region as a (line, column)
+ tuple or |getpos()|-compatible string
+ • {regtype} (`string`) |setreg()|-style selection type
+ • {inclusive} (`boolean`) Controls whether the ending column is
+ inclusive (see also 'selection').
Return: ~
- (table) region Dict of the form `{linenr = {startcol,endcol}}`.
+ (`table`) region Dict of the form `{linenr = {startcol,endcol}}`.
`endcol` is exclusive, and whole lines are returned as
`{startcol,endcol} = {0,-1}`.
@@ -1759,10 +1759,10 @@ vim.schedule_wrap({fn}) *vim.schedule_wrap()*
<
Parameters: ~
- • {fn} (function)
+ • {fn} (`function`)
Return: ~
- (function)
+ (`function`)
See also: ~
• |lua-loop-callbacks|
@@ -1792,8 +1792,8 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()*
throws an error if {cmd} cannot be run.
Parameters: ~
- • {cmd} (string[]) Command to execute
- • {opts} (SystemOpts|nil) Options:
+ • {cmd} (`string[]`) Command to execute
+ • {opts} (`vim.SystemOpts?`) Options:
• cwd: (string) Set the current working directory for the
sub-process.
• env: table<string,string> Set environment variables for
@@ -1823,12 +1823,13 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()*
process will still keep the parent's event loop alive
unless the parent process calls |uv.unref()| on the
child's process handle.
- • {on_exit} (function|nil) Called when subprocess exits. When provided,
- the command runs asynchronously. Receives SystemCompleted
- object, see return of SystemObj:wait().
+ • {on_exit} (`fun(out: vim.SystemCompleted)?`) Called when subprocess
+ exits. When provided, the command runs asynchronously.
+ Receives SystemCompleted object, see return of
+ SystemObj:wait().
Return: ~
- vim.SystemObj Object with the fields:
+ (`vim.SystemObj`) Object with the fields:
• pid (integer) Process ID
• wait (fun(timeout: integer|nil): SystemCompleted) Wait for the
process to complete. Upon timeout the process is sent the KILL
@@ -1855,12 +1856,12 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()*
Can also be pretty-printed with `:Inspect!`. *:Inspect!*
Parameters: ~
- • {bufnr} (integer|nil) defaults to the current buffer
- • {row} (integer|nil) row to inspect, 0-based. Defaults to the row
- of the current cursor
- • {col} (integer|nil) col to inspect, 0-based. Defaults to the col
- of the current cursor
- • {filter} (table|nil) a table with key-value pairs to filter the items
+ • {bufnr} (`integer?`) defaults to the current buffer
+ • {row} (`integer?`) row to inspect, 0-based. Defaults to the row of
+ the current cursor
+ • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of
+ the current cursor
+ • {filter} (`table?`) a table with key-value pairs to filter the items
• syntax (boolean): include syntax based highlight groups
(defaults to true)
• treesitter (boolean): include treesitter based highlight
@@ -1872,7 +1873,7 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()*
(defaults to true)
Return: ~
- (table) a table with the following key-value pairs. Items are in
+ (`table`) a table with the following key-value pairs. Items are in
"traversal order":
• treesitter: a list of treesitter captures
• syntax: a list of syntax groups
@@ -1888,12 +1889,12 @@ vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()*
Can also be shown with `:Inspect`. *:Inspect*
Parameters: ~
- • {bufnr} (integer|nil) defaults to the current buffer
- • {row} (integer|nil) row to inspect, 0-based. Defaults to the row
- of the current cursor
- • {col} (integer|nil) col to inspect, 0-based. Defaults to the col
- of the current cursor
- • {filter} (table|nil) see |vim.inspect_pos()|
+ • {bufnr} (`integer?`) defaults to the current buffer
+ • {row} (`integer?`) row to inspect, 0-based. Defaults to the row of
+ the current cursor
+ • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of
+ the current cursor
+ • {filter} (`table?`) see |vim.inspect_pos()|
@@ -1905,11 +1906,11 @@ vim.deep_equal({a}, {b}) *vim.deep_equal()*
All other types are compared using the equality `==` operator.
Parameters: ~
- • {a} any First value
- • {b} any Second value
+ • {a} (`any`) First value
+ • {b} (`any`) Second value
Return: ~
- (boolean) `true` if values are equals, else `false`
+ (`boolean`) `true` if values are equals, else `false`
vim.deepcopy({orig}, {noref}) *vim.deepcopy()*
Returns a deep copy of the given object. Non-table objects are copied as
@@ -1923,15 +1924,15 @@ vim.deepcopy({orig}, {noref}) *vim.deepcopy()*
fields.
Parameters: ~
- • {orig} (table) Table to copy
- • {noref} (boolean|nil) When `false` (default) a contained table is
- only copied once and all references point to this single
- copy. When `true` every occurrence of a table results in a
- new copy. This also means that a cyclic reference can cause
+ • {orig} (`table`) Table to copy
+ • {noref} (`boolean?`) When `false` (default) a contained table is only
+ copied once and all references point to this single copy.
+ When `true` every occurrence of a table results in a new
+ copy. This also means that a cyclic reference can cause
`deepcopy()` to fail.
Return: ~
- (table) Table of copied keys and (nested) values.
+ (`table`) Table of copied keys and (nested) values.
vim.defaulttable({createfn}) *vim.defaulttable()*
Creates a table whose missing keys are provided by {createfn} (like
@@ -1944,21 +1945,21 @@ vim.defaulttable({createfn}) *vim.defaulttable()*
<
Parameters: ~
- • {createfn} function?(key:any):any Provides the value for a missing
+ • {createfn} (`fun(key:any):any?`) Provides the value for a missing
`key`.
Return: ~
- (table) Empty table with `__index` metamethod.
+ (`table`) Empty table with `__index` metamethod.
vim.endswith({s}, {suffix}) *vim.endswith()*
Tests if `s` ends with `suffix`.
Parameters: ~
- • {s} (string) String
- • {suffix} (string) Suffix to match
+ • {s} (`string`) String
+ • {suffix} (`string`) Suffix to match
Return: ~
- (boolean) `true` if `suffix` is a suffix of `s`
+ (`boolean`) `true` if `suffix` is a suffix of `s`
vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()*
Gets an |iterator| that splits a string at each instance of a separator,
@@ -1978,15 +1979,15 @@ vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()*
<
Parameters: ~
- • {s} (string) String to split
- • {sep} (string) Separator or pattern
- • {opts} (table|nil) Keyword arguments |kwargs|:
+ • {s} (`string`) String to split
+ • {sep} (`string`) Separator or pattern
+ • {opts} (`table?`) Keyword arguments |kwargs|:
• plain: (boolean) Use `sep` literally (as in string.find).
• trimempty: (boolean) Discard empty segments at start and end
of the sequence.
Return: ~
- (function) Iterator over the split components
+ (`function`) Iterator over the split components
See also: ~
• |string.gmatch()|
@@ -1999,20 +2000,20 @@ vim.is_callable({f}) *vim.is_callable()*
Returns true if object `f` can be called as a function.
Parameters: ~
- • {f} any Any object
+ • {f} (`any`) Any object
Return: ~
- (boolean) `true` if `f` is callable, else `false`
+ (`boolean`) `true` if `f` is callable, else `false`
vim.list_contains({t}, {value}) *vim.list_contains()*
Checks if a list-like table (integer keys without gaps) contains `value`.
Parameters: ~
- • {t} (table) Table to check (must be list-like, not validated)
- • {value} any Value to compare
+ • {t} (`table`) Table to check (must be list-like, not validated)
+ • {value} (`any`) Value to compare
Return: ~
- (boolean) `true` if `t` contains `value`
+ (`boolean`) `true` if `t` contains `value`
See also: ~
• |vim.tbl_contains()| for checking values in general tables
@@ -2023,13 +2024,13 @@ vim.list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()*
NOTE: This mutates dst!
Parameters: ~
- • {dst} (table) List which will be modified and appended to
- • {src} (table) List from which values will be inserted
- • {start} (integer|nil) Start index on src. Defaults to 1
- • {finish} (integer|nil) Final index on src. Defaults to `#src`
+ • {dst} (`table`) List which will be modified and appended to
+ • {src} (`table`) List from which values will be inserted
+ • {start} (`integer?`) Start index on src. Defaults to 1
+ • {finish} (`integer?`) Final index on src. Defaults to `#src`
Return: ~
- (table) dst
+ (`table`) dst
See also: ~
• |vim.tbl_extend()|
@@ -2039,21 +2040,21 @@ vim.list_slice({list}, {start}, {finish}) *vim.list_slice()*
(inclusive)
Parameters: ~
- • {list} (list) Table
- • {start} (integer|nil) Start range of slice
- • {finish} (integer|nil) End range of slice
+ • {list} (`list`) Table
+ • {start} (`integer?`) Start range of slice
+ • {finish} (`integer?`) End range of slice
Return: ~
- (list) Copy of table sliced from start to finish (inclusive)
+ (`list`) Copy of table sliced from start to finish (inclusive)
vim.pesc({s}) *vim.pesc()*
Escapes magic chars in |lua-patterns|.
Parameters: ~
- • {s} (string) String to escape
+ • {s} (`string`) String to escape
Return: ~
- (string) %-escaped pattern string
+ (`string`) %-escaped pattern string
See also: ~
• https://github.com/rxi/lume
@@ -2084,10 +2085,10 @@ vim.ringbuf({size}) *vim.ringbuf()*
• |Ringbuf:clear()|
Parameters: ~
- • {size} (integer)
+ • {size} (`integer`)
Return: ~
- (table)
+ (`table`)
vim.Ringbuf:clear() *Ringbuf:clear()*
Clear all items.
@@ -2096,28 +2097,28 @@ vim.Ringbuf:peek() *Ringbuf:peek()*
Returns the first unread item without removing it
Return: ~
- any?|nil
+ (`any?`)
vim.Ringbuf:pop() *Ringbuf:pop()*
Removes and returns the first unread item
Return: ~
- any?|nil
+ (`any?`)
vim.Ringbuf:push({item}) *Ringbuf:push()*
Adds an item, overriding the oldest item if the buffer is full.
Parameters: ~
- • {item} any
+ • {item} (`any`)
vim.spairs({t}) *vim.spairs()*
Enumerates key-value pairs of a table, ordered by key.
Parameters: ~
- • {t} (table) Dict-like table
+ • {t} (`table`) Dict-like table
Return: ~
- (function) |for-in| iterator over sorted keys and their values
+ (`function`) |for-in| iterator over sorted keys and their values
See also: ~
• Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
@@ -2134,13 +2135,13 @@ vim.split({s}, {sep}, {opts}) *vim.split()*
<
Parameters: ~
- • {s} (string) String to split
- • {sep} (string) Separator or pattern
- • {opts} (table|nil) Keyword arguments |kwargs| accepted by
+ • {s} (`string`) String to split
+ • {sep} (`string`) Separator or pattern
+ • {opts} (`table?`) Keyword arguments |kwargs| accepted by
|vim.gsplit()|
Return: ~
- string[] List of split components
+ (`string[]`) List of split components
See also: ~
• |vim.gsplit()|
@@ -2150,11 +2151,11 @@ vim.startswith({s}, {prefix}) *vim.startswith()*
Tests if `s` starts with `prefix`.
Parameters: ~
- • {s} (string) String
- • {prefix} (string) Prefix to match
+ • {s} (`string`) String
+ • {prefix} (`string`) Prefix to match
Return: ~
- (boolean) `true` if `prefix` is a prefix of `s`
+ (`boolean`) `true` if `prefix` is a prefix of `s`
vim.tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()*
Add the reverse lookup values to an existing table. For example:
@@ -2163,10 +2164,10 @@ vim.tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()*
Note that this modifies the input.
Parameters: ~
- • {o} (table) Table to add the reverse to
+ • {o} (`table`) Table to add the reverse to
Return: ~
- (table) o
+ (`table`) o
vim.tbl_contains({t}, {value}, {opts}) *vim.tbl_contains()*
Checks if a table contains a given value, specified either directly or via
@@ -2180,14 +2181,14 @@ vim.tbl_contains({t}, {value}, {opts}) *vim.tbl_contains()*
<
Parameters: ~
- • {t} (table) Table to check
- • {value} any Value to compare or predicate function reference
- • {opts} (table|nil) Keyword arguments |kwargs|:
+ • {t} (`table`) Table to check
+ • {value} (`any`) Value to compare or predicate function reference
+ • {opts} (`table?`) Keyword arguments |kwargs|:
• predicate: (boolean) `value` is a function reference to be
checked (default false)
Return: ~
- (boolean) `true` if `t` contains `value`
+ (`boolean`) `true` if `t` contains `value`
See also: ~
• |vim.list_contains()| for checking values in list-like tables
@@ -2199,10 +2200,10 @@ vim.tbl_count({t}) *vim.tbl_count()*
<
Parameters: ~
- • {t} (table) Table
+ • {t} (`table`) Table
Return: ~
- (integer) Number of non-nil values in table
+ (`integer`) Number of non-nil values in table
See also: ~
• https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
@@ -2211,15 +2212,15 @@ vim.tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()*
Merges recursively two or more tables.
Parameters: ~
- • {behavior} (string) Decides what to do if a key is found in more than
- one map:
+ • {behavior} (`string`) Decides what to do if a key is found in more
+ than one map:
• "error": raise an error
• "keep": use value from the leftmost map
• "force": use value from the rightmost map
- • {...} (table) Two or more tables
+ • {...} (`table`) Two or more tables
Return: ~
- (table) Merged table
+ (`table`) Merged table
See also: ~
• |vim.tbl_extend()|
@@ -2228,15 +2229,15 @@ vim.tbl_extend({behavior}, {...}) *vim.tbl_extend()*
Merges two or more tables.
Parameters: ~
- • {behavior} (string) Decides what to do if a key is found in more than
- one map:
+ • {behavior} (`string`) Decides what to do if a key is found in more
+ than one map:
• "error": raise an error
• "keep": use value from the leftmost map
• "force": use value from the rightmost map
- • {...} (table) Two or more tables
+ • {...} (`table`) Two or more tables
Return: ~
- (table) Merged table
+ (`table`) Merged table
See also: ~
• |extend()|
@@ -2245,21 +2246,21 @@ vim.tbl_filter({func}, {t}) *vim.tbl_filter()*
Filter a table using a predicate function
Parameters: ~
- • {func} (function) Function
- • {t} (table) Table
+ • {func} (`function`) Function
+ • {t} (`table`) Table
Return: ~
- (table) Table of filtered values
+ (`table`) Table of filtered values
vim.tbl_flatten({t}) *vim.tbl_flatten()*
Creates a copy of a list-like table such that any nested tables are
"unrolled" and appended to the result.
Parameters: ~
- • {t} (table) List-like table
+ • {t} (`table`) List-like table
Return: ~
- (table) Flattened copy of the given list-like table
+ (`table`) Flattened copy of the given list-like table
See also: ~
• From https://github.com/premake/premake-core/blob/master/src/base/table.lua
@@ -2274,12 +2275,12 @@ vim.tbl_get({o}, {...}) *vim.tbl_get()*
<
Parameters: ~
- • {o} (table) Table to index
- • {...} any Optional keys (0 or more, variadic) via which to index the
- table
+ • {o} (`table`) Table to index
+ • {...} (`any`) Optional keys (0 or more, variadic) via which to index
+ the table
Return: ~
- any Nested value indexed by key (if it exists), else nil
+ (`any`) Nested value indexed by key (if it exists), else nil
vim.tbl_isarray({t}) *vim.tbl_isarray()*
Tests if `t` is an "array": a table indexed only by integers (potentially
@@ -2293,10 +2294,10 @@ vim.tbl_isarray({t}) *vim.tbl_isarray()*
|rpcrequest()| or |vim.fn|.
Parameters: ~
- • {t} (table)
+ • {t} (`table`)
Return: ~
- (boolean) `true` if array-like table, else `false`.
+ (`boolean`) `true` if array-like table, else `false`.
See also: ~
• https://github.com/openresty/luajit2#tableisarray
@@ -2305,10 +2306,10 @@ vim.tbl_isempty({t}) *vim.tbl_isempty()*
Checks if a table is empty.
Parameters: ~
- • {t} (table) Table to check
+ • {t} (`table`) Table to check
Return: ~
- (boolean) `true` if `t` is empty
+ (`boolean`) `true` if `t` is empty
See also: ~
• https://github.com/premake/premake-core/blob/master/src/base/table.lua
@@ -2322,10 +2323,10 @@ vim.tbl_islist({t}) *vim.tbl_islist()*
|rpcrequest()| or |vim.fn|.
Parameters: ~
- • {t} (table)
+ • {t} (`table`)
Return: ~
- (boolean) `true` if list-like table, else `false`.
+ (`boolean`) `true` if list-like table, else `false`.
See also: ~
• |vim.tbl_isarray()|
@@ -2335,10 +2336,10 @@ vim.tbl_keys({t}) *vim.tbl_keys()*
return table of keys is not guaranteed.
Parameters: ~
- • {t} (table) Table
+ • {t} (`table`) Table
Return: ~
- (list) List of keys
+ (`list`) List of keys
See also: ~
• From https://github.com/premake/premake-core/blob/master/src/base/table.lua
@@ -2347,30 +2348,30 @@ vim.tbl_map({func}, {t}) *vim.tbl_map()*
Apply a function to all values of a table.
Parameters: ~
- • {func} (function) Function
- • {t} (table) Table
+ • {func} (`function`) Function
+ • {t} (`table`) Table
Return: ~
- (table) Table of transformed values
+ (`table`) Table of transformed values
vim.tbl_values({t}) *vim.tbl_values()*
Return a list of all values used in a table. However, the order of the
return table of values is not guaranteed.
Parameters: ~
- • {t} (table) Table
+ • {t} (`table`) Table
Return: ~
- (list) List of values
+ (`list`) List of values
vim.trim({s}) *vim.trim()*
Trim whitespace (Lua pattern "%s") from both sides of a string.
Parameters: ~
- • {s} (string) String to trim
+ • {s} (`string`) String to trim
Return: ~
- (string) String with whitespace removed from its beginning and end
+ (`string`) String with whitespace removed from its beginning and end
See also: ~
• |lua-patterns|
@@ -2410,7 +2411,7 @@ vim.validate({opt}) *vim.validate()*
<
Parameters: ~
- • {opt} (table) Names of parameters to validate. Each key is a
+ • {opt} (`table`) Names of parameters to validate. Each key is a
parameter name; each value is a tuple in one of these forms:
1. (arg_value, type_name, optional)
• arg_value: argument value
@@ -2447,9 +2448,9 @@ vim.loader.find({modname}, {opts}) *vim.loader.find()*
Finds Lua modules for the given module name.
Parameters: ~
- • {modname} (string) Module name, or `"*"` to find the top-level
+ • {modname} (`string`) Module name, or `"*"` to find the top-level
modules instead
- • {opts} (table|nil) Options for finding a module:
+ • {opts} (`table?`) Options for finding a module:
• rtp: (boolean) Search for modname in the runtime path
(defaults to `true`)
• paths: (string[]) Extra paths to search for modname
@@ -2462,7 +2463,7 @@ vim.loader.find({modname}, {opts}) *vim.loader.find()*
first one (defaults to `false`)
Return: ~
- (list) A list of results with the following properties:
+ (`list`) A list of results with the following properties:
• modpath: (string) the path to the module
• modname: (string) the name of the module
• stat: (table|nil) the fs_stat of the module path. Won't be returned
@@ -2472,7 +2473,7 @@ vim.loader.reset({path}) *vim.loader.reset()*
Resets the cache for the path, or all the paths if path is nil.
Parameters: ~
- • {path} string? path to reset
+ • {path} (`string?`) path to reset
==============================================================================
@@ -2482,57 +2483,57 @@ vim.uri_decode({str}) *vim.uri_decode()*
URI-decodes a string containing percent escapes.
Parameters: ~
- • {str} (string) string to decode
+ • {str} (`string`) string to decode
Return: ~
- (string) decoded string
+ (`string`) decoded string
vim.uri_encode({str}, {rfc}) *vim.uri_encode()*
URI-encodes a string using percent escapes.
Parameters: ~
- • {str} (string) string to encode
- • {rfc} "rfc2396" | "rfc2732" | "rfc3986" | nil
+ • {str} (`string`) string to encode
+ • {rfc} (`"rfc2396"|"rfc2732"|"rfc3986"?`)
Return: ~
- (string) encoded string
+ (`string`) encoded string
vim.uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()*
Gets a URI from a bufnr.
Parameters: ~
- • {bufnr} (integer)
+ • {bufnr} (`integer`)
Return: ~
- (string) URI
+ (`string`) URI
vim.uri_from_fname({path}) *vim.uri_from_fname()*
Gets a URI from a file path.
Parameters: ~
- • {path} (string) Path to file
+ • {path} (`string`) Path to file
Return: ~
- (string) URI
+ (`string`) URI
vim.uri_to_bufnr({uri}) *vim.uri_to_bufnr()*
Gets the buffer for a uri. Creates a new unloaded buffer if no buffer for
the uri already exists.
Parameters: ~
- • {uri} (string)
+ • {uri} (`string`)
Return: ~
- (integer) bufnr
+ (`integer`) bufnr
vim.uri_to_fname({uri}) *vim.uri_to_fname()*
Gets a filename from a URI.
Parameters: ~
- • {uri} (string)
+ • {uri} (`string`)
Return: ~
- (string) filename or unchanged URI for non-file URIs
+ (`string`) filename or unchanged URI for non-file URIs
==============================================================================
@@ -2549,7 +2550,7 @@ vim.ui.input({opts}, {on_confirm}) *vim.ui.input()*
<
Parameters: ~
- • {opts} (table) Additional options. See |input()|
+ • {opts} (`table`) Additional options. See |input()|
• prompt (string|nil) Text of the prompt
• default (string|nil) Default reply to the input
• completion (string|nil) Specifies type of completion
@@ -2558,7 +2559,7 @@ vim.ui.input({opts}, {on_confirm}) *vim.ui.input()*
"-complete=" argument. See |:command-completion|
• highlight (function) Function that will be used for
highlighting user inputs.
- • {on_confirm} (function) ((input|nil) -> ()) Called once the user
+ • {on_confirm} (`function`) ((input|nil) -> ()) Called once the user
confirms or abort the input. `input` is what the user
typed (it might be an empty string if nothing was
entered), or `nil` if the user aborted the dialog.
@@ -2577,11 +2578,11 @@ vim.ui.open({path}) *vim.ui.open()*
<
Parameters: ~
- • {path} (string) Path or URL to open
+ • {path} (`string`) Path or URL to open
Return (multiple): ~
- vim.SystemCompleted|nil Command result, or nil if not found.
- (string|nil) Error message on failure
+ (`vim.SystemCompleted?`) Command result, or nil if not found.
+ (`string?`) Error message on failure
See also: ~
• |vim.system()|
@@ -2606,8 +2607,8 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()*
<
Parameters: ~
- • {items} (table) Arbitrary items
- • {opts} (table) Additional options
+ • {items} (`table`) Arbitrary items
+ • {opts} (`table`) Additional options
• prompt (string|nil) Text of the prompt. Defaults to
`Select one of:`
• format_item (function item -> text) Function to format
@@ -2617,7 +2618,7 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()*
item shape. Plugins reimplementing `vim.ui.select` may
wish to use this to infer the structure or semantics of
`items`, or the context in which select() was called.
- • {on_choice} (function) ((item|nil, idx|nil) -> ()) Called once the
+ • {on_choice} (`function`) ((item|nil, idx|nil) -> ()) Called once the
user made a choice. `idx` is the 1-based index of `item`
within `items`. `nil` if the user aborted the dialog.
@@ -2707,7 +2708,7 @@ vim.filetype.add({filetypes}) *vim.filetype.add()*
<
Parameters: ~
- • {filetypes} (table) A table containing new filetype maps (see
+ • {filetypes} (`table`) A table containing new filetype maps (see
example).
*vim.filetype.get_option()*
@@ -2727,11 +2728,11 @@ vim.filetype.get_option({filetype}, {option})
may not reflect later changes.
Parameters: ~
- • {filetype} (string) Filetype
- • {option} (string) Option name
+ • {filetype} (`string`) Filetype
+ • {option} (`string`) Option name
Return: ~
- string|boolean|integer: Option value
+ (`string|boolean|integer`) Option value
vim.filetype.match({args}) *vim.filetype.match()*
Perform filetype detection.
@@ -2763,7 +2764,7 @@ vim.filetype.match({args}) *vim.filetype.match()*
<
Parameters: ~
- • {args} (table) Table specifying which matching strategy to use.
+ • {args} (`table`) Table specifying which matching strategy to use.
Accepted keys are:
• buf (number): Buffer number to use for matching. Mutually
exclusive with {contents}
@@ -2779,8 +2780,8 @@ vim.filetype.match({args}) *vim.filetype.match()*
Mutually exclusive with {buf}.
Return (multiple): ~
- (string|nil) If a match was found, the matched filetype.
- (function|nil) A function that modifies buffer state when called (for
+ (`string?`) If a match was found, the matched filetype.
+ (`function?`) A function that modifies buffer state when called (for
example, to set some filetype specific buffer variables). The function
accepts a buffer number as its only argument.
@@ -2796,7 +2797,7 @@ vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()*
<
Parameters: ~
- • {opts} (table|nil) A table of optional arguments:
+ • {opts} (`table?`) A table of optional arguments:
• "buffer": (integer|boolean) Remove a mapping from the given
buffer. When `0` or `true`, use the current buffer.
@@ -2820,12 +2821,12 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
<
Parameters: ~
- • {mode} string|table Mode short-name, see |nvim_set_keymap()|. Can
+ • {mode} (`string|table`) Mode short-name, see |nvim_set_keymap()|. Can
also be list of modes to create mapping on multiple modes.
- • {lhs} (string) Left-hand side |{lhs}| of the mapping.
- • {rhs} string|function Right-hand side |{rhs}| of the mapping, can be
- a Lua function.
- • {opts} (table|nil) Table of |:map-arguments|.
+ • {lhs} (`string`) Left-hand side |{lhs}| of the mapping.
+ • {rhs} (`string|function`) Right-hand side |{rhs}| of the mapping,
+ can be a Lua function.
+ • {opts} (`table?`) Table of |:map-arguments|.
• Same as |nvim_set_keymap()| {opts}, except:
• "replace_keycodes" defaults to `true` if "expr" is `true`.
• "noremap": inverse of "remap" (see below).
@@ -2850,26 +2851,26 @@ vim.fs.basename({file}) *vim.fs.basename()*
Return the basename of the given path
Parameters: ~
- • {file} (string) Path
+ • {file} (`string`) Path
Return: ~
- (string|nil) Basename of {file}
+ (`string?`) Basename of {file}
vim.fs.dir({path}, {opts}) *vim.fs.dir()*
Return an iterator over the items located in {path}
Parameters: ~
- • {path} (string) An absolute or relative path to the directory to
+ • {path} (`string`) An absolute or relative path to the directory to
iterate over. The path is first normalized
|vim.fs.normalize()|.
- • {opts} (table|nil) Optional keyword arguments:
+ • {opts} (`table?`) Optional keyword arguments:
• depth: integer|nil How deep the traverse (default 1)
• skip: (fun(dir_name: string): boolean)|nil Predicate to
control traversal. Return false to stop searching the
current directory. Only useful when depth > 1
Return: ~
- Iterator over items in {path}. Each iteration yields two values:
+ (`Iterator`) over items in {path}. Each iteration yields two values:
"name" and "type". "name" is the basename of the item relative to
{path}. "type" is one of the following: "file", "directory", "link",
"fifo", "socket", "char", "block", "unknown".
@@ -2878,10 +2879,10 @@ vim.fs.dirname({file}) *vim.fs.dirname()*
Return the parent directory of the given path
Parameters: ~
- • {file} (string) Path
+ • {file} (`string`) Path
Return: ~
- (string|nil) Parent directory of {file}
+ (`string?`) Parent directory of {file}
vim.fs.find({names}, {opts}) *vim.fs.find()*
Find files or directories (or other items as specified by `opts.type`) in
@@ -2917,7 +2918,7 @@ vim.fs.find({names}, {opts}) *vim.fs.find()*
<
Parameters: ~
- • {names} (string|string[]|fun(name: string, path: string): boolean)
+ • {names} (`string|string[]|fun(name: string, path: string): boolean`)
Names of the items to find. Must be base names, paths and
globs are not supported when {names} is a string or a table.
If {names} is a function, it is called for each traversed
@@ -2925,7 +2926,7 @@ vim.fs.find({names}, {opts}) *vim.fs.find()*
• name: base name of the current item
• path: full path of the current item The function should
return `true` if the given item is considered a match.
- • {opts} (table) Optional keyword arguments:
+ • {opts} (`table`) Optional keyword arguments:
• path (string): Path to begin searching from. If omitted,
the |current-directory| is used.
• upward (boolean, default false): If true, search upward
@@ -2940,17 +2941,18 @@ vim.fs.find({names}, {opts}) *vim.fs.find()*
number of matches.
Return: ~
- (string[]) Normalized paths |vim.fs.normalize()| of all matching items
+ (`string[]`) Normalized paths |vim.fs.normalize()| of all matching
+ items
vim.fs.joinpath({...}) *vim.fs.joinpath()*
Concatenate directories and/or file paths into a single path with
normalization (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`)
Parameters: ~
- • {...} (string)
+ • {...} (`string`)
Return: ~
- (string)
+ (`string`)
vim.fs.normalize({path}, {opts}) *vim.fs.normalize()*
Normalize a path to a standard format. A tilde (~) character at the
@@ -2970,13 +2972,13 @@ vim.fs.normalize({path}, {opts}) *vim.fs.normalize()*
<
Parameters: ~
- • {path} (string) Path to normalize
- • {opts} (table|nil) Options:
+ • {path} (`string`) Path to normalize
+ • {opts} (`table?`) Options:
• expand_env: boolean Expand environment variables (default:
true)
Return: ~
- (string) Normalized path
+ (`string`) Normalized path
vim.fs.parents({start}) *vim.fs.parents()*
Iterate over all the parents of the given path.
@@ -2996,12 +2998,12 @@ vim.fs.parents({start}) *vim.fs.parents()*
<
Parameters: ~
- • {start} (string) Initial path.
+ • {start} (`string`) Initial path.
Return (multiple): ~
- fun(_, dir: string): string? Iterator
- nil
- (string|nil)
+ (`fun(_, dir: string): string?`) Iterator
+ (`nil`)
+ (`string?`)
==============================================================================
@@ -3025,10 +3027,11 @@ vim.glob.to_lpeg({pattern}) *vim.glob.to_lpeg()*
`example.0`)
Parameters: ~
- • {pattern} (string) The raw glob pattern
+ • {pattern} (`string`) The raw glob pattern
Return: ~
- vim.lpeg.Pattern pattern An |lua-lpeg| representation of the pattern
+ (`vim.lpeg.Pattern`) pattern An |lua-lpeg| representation of the
+ pattern
==============================================================================
@@ -3040,10 +3043,10 @@ vim.secure.read({path}) *vim.secure.read()*
$XDG_STATE_HOME/nvim/trust.
Parameters: ~
- • {path} (string) Path to a file to read.
+ • {path} (`string`) Path to a file to read.
Return: ~
- (string|nil) The contents of the given file if it exists and is
+ (`string?`) The contents of the given file if it exists and is
trusted, or nil otherwise.
See also: ~
@@ -3055,7 +3058,7 @@ vim.secure.trust({opts}) *vim.secure.trust()*
The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
Parameters: ~
- • {opts} (table)
+ • {opts} (`table`)
• action (string): "allow" to add a file to the trust database
and trust it, "deny" to add a file to the trust database and
deny it, "remove" to remove file from the trust database
@@ -3066,8 +3069,9 @@ vim.secure.trust({opts}) *vim.secure.trust()*
exclusive with {path}.
Return (multiple): ~
- (boolean) success true if operation was successful
- (string) msg full path if operation was successful, else error message
+ (`boolean`) success true if operation was successful
+ (`string`) msg full path if operation was successful, else error
+ message
==============================================================================
@@ -3150,51 +3154,51 @@ vim.version.cmp({v1}, {v2}) *vim.version.cmp()*
otherwise-equivalent versions.
Parameters: ~
- • {v1} Version|number[] Version object.
- • {v2} Version|number[] Version to compare with `v1` .
+ • {v1} (`Version|number[]`) Version object.
+ • {v2} (`Version|number[]`) Version to compare with `v1` .
Return: ~
- (integer) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`.
+ (`integer`) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`.
vim.version.eq({v1}, {v2}) *vim.version.eq()*
- Returns `true` if the given versions are equal. See |vim.version.cmp()|
- for usage.
+ Returns `true` if the given versions are equal. See |vim.version.cmp()| for
+ usage.
Parameters: ~
- • {v1} Version|number[]
- • {v2} Version|number[]
+ • {v1} (`Version|number[]`)
+ • {v2} (`Version|number[]`)
Return: ~
- (boolean)
+ (`boolean`)
vim.version.gt({v1}, {v2}) *vim.version.gt()*
Returns `true` if `v1 > v2` . See |vim.version.cmp()| for usage.
Parameters: ~
- • {v1} Version|number[]
- • {v2} Version|number[]
+ • {v1} (`Version|number[]`)
+ • {v2} (`Version|number[]`)
Return: ~
- (boolean)
+ (`boolean`)
vim.version.last({versions}) *vim.version.last()*
TODO: generalize this, move to func.lua
Parameters: ~
- • {versions} Version []
+ • {versions} (`Version[]`)
Return: ~
- Version ?|nil
+ (`Version?`)
vim.version.lt({v1}, {v2}) *vim.version.lt()*
Returns `true` if `v1 < v2` . See |vim.version.cmp()| for usage.
Parameters: ~
- • {v1} Version|number[]
- • {v2} Version|number[]
+ • {v1} (`Version|number[]`)
+ • {v2} (`Version|number[]`)
Return: ~
- (boolean)
+ (`boolean`)
vim.version.parse({version}, {opts}) *vim.version.parse()*
Parses a semantic version string and returns a version object which can be
@@ -3204,16 +3208,15 @@ vim.version.parse({version}, {opts}) *vim.version.parse()*
<
Parameters: ~
- • {version} (string) Version string to parse.
- • {opts} (table|nil) Optional keyword arguments:
+ • {version} (`string`) Version string to parse.
+ • {opts} (`table?`) Optional keyword arguments:
• strict (boolean): Default false. If `true`, no coercion
is attempted on input not conforming to semver v2.0.0. If
`false`, `parse()` attempts to coerce input such as
"1.0", "0-x", "tmux 3.2a" into valid versions.
Return: ~
- (table|nil) parsed_version Version object or `nil` if input is
- invalid.
+ (`table?`) parsed_version Version object or `nil` if input is invalid.
See also: ~
• # https://semver.org/spec/v2.0.0.html
@@ -3243,7 +3246,7 @@ vim.version.range({spec}) *vim.version.range()*
<
Parameters: ~
- • {spec} (string) Version range "spec"
+ • {spec} (`string`) Version range "spec"
See also: ~
• # https://github.com/npm/node-semver#ranges
@@ -3328,13 +3331,13 @@ filter({f}, {src}, {...}) *vim.iter.filter()*
<
Parameters: ~
- • {f} function(...):bool Filter function. Accepts the current
- iterator or table values as arguments and returns true if those
- values should be kept in the final table
- • {src} table|function Table or iterator function to filter
+ • {f} (`fun(...):bool`) Filter function. Accepts the current iterator
+ or table values as arguments and returns true if those values
+ should be kept in the final table
+ • {src} (`table|function`) Table or iterator function to filter
Return: ~
- (table)
+ (`table`)
See also: ~
• |Iter:filter()|
@@ -3343,7 +3346,7 @@ Iter:all({pred}) *Iter:all()*
Returns true if all items in the iterator match the given predicate.
Parameters: ~
- • {pred} function(...):bool Predicate function. Takes all values
+ • {pred} (`fun(...):bool`) Predicate function. Takes all values
returned from the previous stage in the pipeline as arguments
and returns true if the predicate matches.
@@ -3352,7 +3355,7 @@ Iter:any({pred}) *Iter:any()*
predicate.
Parameters: ~
- • {pred} function(...):bool Predicate function. Takes all values
+ • {pred} (`fun(...):bool`) Predicate function. Takes all values
returned from the previous stage in the pipeline as arguments
and returns true if the predicate matches.
@@ -3364,7 +3367,7 @@ Iter:each({f}) *Iter:each()*
|Iter:map()|.
Parameters: ~
- • {f} function(...) Function to execute for each item in the pipeline.
+ • {f} (`fun(...)`) Function to execute for each item in the pipeline.
Takes all of the values returned by the previous stage in the
pipeline as arguments.
@@ -3391,7 +3394,7 @@ Iter:enumerate() *Iter:enumerate()*
<
Return: ~
- Iter
+ (`Iter`)
Iter:filter({f}) *Iter:filter()*
Filters an iterator pipeline.
@@ -3401,12 +3404,12 @@ Iter:filter({f}) *Iter:filter()*
<
Parameters: ~
- • {f} function(...):bool Takes all values returned from the previous
+ • {f} (`fun(...):bool`) Takes all values returned from the previous
stage in the pipeline and returns false or nil if the current
iterator element should be removed.
Return: ~
- Iter
+ (`Iter`)
Iter:find({f}) *Iter:find()*
Find the first value in the iterator that satisfies the given predicate.
@@ -3429,7 +3432,7 @@ Iter:find({f}) *Iter:find()*
<
Return: ~
- any
+ (`any`)
Iter:flatten({depth}) *Iter:flatten()*
Flattens a |list-iterator|, un-nesting nested values up to the given
@@ -3447,11 +3450,11 @@ Iter:flatten({depth}) *Iter:flatten()*
<
Parameters: ~
- • {depth} (number|nil) Depth to which |list-iterator| should be
+ • {depth} (`number?`) Depth to which |list-iterator| should be
flattened (defaults to 1)
Return: ~
- Iter
+ (`Iter`)
Iter:fold({init}, {f}) *Iter:fold()*
Folds ("reduces") an iterator into a single value.
@@ -3469,11 +3472,11 @@ Iter:fold({init}, {f}) *Iter:fold()*
<
Parameters: ~
- • {init} any Initial value of the accumulator.
- • {f} function(acc:any, ...):A Accumulation function.
+ • {init} (`any`) Initial value of the accumulator.
+ • {f} (`fun(acc:any, ...):any`) Accumulation function.
Return: ~
- any
+ (`any`)
Iter:join({delim}) *Iter:join()*
Collect the iterator into a delimited string.
@@ -3483,10 +3486,10 @@ Iter:join({delim}) *Iter:join()*
Consumes the iterator.
Parameters: ~
- • {delim} (string) Delimiter
+ • {delim} (`string`) Delimiter
Return: ~
- (string)
+ (`string`)
Iter:last() *Iter:last()*
Drains the iterator and returns the last item.
@@ -3502,7 +3505,7 @@ Iter:last() *Iter:last()*
<
Return: ~
- any
+ (`any`)
Iter:map({f}) *Iter:map()*
Maps the items of an iterator pipeline to the values returned by `f`.
@@ -3520,13 +3523,13 @@ Iter:map({f}) *Iter:map()*
<
Parameters: ~
- • {f} function(...):any Mapping function. Takes all values returned
- from the previous stage in the pipeline as arguments and returns
- one or more new values, which are used in the next pipeline
- stage. Nil return values are filtered from the output.
+ • {f} (`fun(...):any`) Mapping function. Takes all values returned from
+ the previous stage in the pipeline as arguments and returns one
+ or more new values, which are used in the next pipeline stage.
+ Nil return values are filtered from the output.
Return: ~
- Iter
+ (`Iter`)
Iter:next() *Iter:next()*
Gets the next value from the iterator.
@@ -3542,7 +3545,7 @@ Iter:next() *Iter:next()*
<
Return: ~
- any
+ (`any`)
Iter:nextback() *Iter:nextback()*
"Pops" a value from a |list-iterator| (gets the last value and decrements
@@ -3557,7 +3560,7 @@ Iter:nextback() *Iter:nextback()*
<
Return: ~
- any
+ (`any`)
Iter:nth({n}) *Iter:nth()*
Gets the nth value of an iterator (and advances to it).
@@ -3571,10 +3574,10 @@ Iter:nth({n}) *Iter:nth()*
<
Parameters: ~
- • {n} (number) The index of the value to return.
+ • {n} (`number`) The index of the value to return.
Return: ~
- any
+ (`any`)
Iter:nthback({n}) *Iter:nthback()*
Gets the nth value from the end of a |list-iterator| (and advances to it).
@@ -3588,10 +3591,10 @@ Iter:nthback({n}) *Iter:nthback()*
<
Parameters: ~
- • {n} (number) The index of the value to return.
+ • {n} (`number`) The index of the value to return.
Return: ~
- any
+ (`any`)
Iter:peek() *Iter:peek()*
Gets the next value in a |list-iterator| without consuming it.
@@ -3607,7 +3610,7 @@ Iter:peek() *Iter:peek()*
<
Return: ~
- any
+ (`any`)
Iter:peekback() *Iter:peekback()*
Gets the last value of a |list-iterator| without consuming it.
@@ -3625,7 +3628,7 @@ Iter:peekback() *Iter:peekback()*
<
Return: ~
- any
+ (`any`)
Iter:rev() *Iter:rev()*
Reverses a |list-iterator| pipeline.
@@ -3637,7 +3640,7 @@ Iter:rev() *Iter:rev()*
<
Return: ~
- Iter
+ (`Iter`)
Iter:rfind({f}) *Iter:rfind()*
Gets the first value in a |list-iterator| that satisfies a predicate,
@@ -3655,7 +3658,7 @@ Iter:rfind({f}) *Iter:rfind()*
<
Return: ~
- any
+ (`any`)
See also: ~
• Iter.find
@@ -3670,10 +3673,10 @@ Iter:skip({n}) *Iter:skip()*
<
Parameters: ~
- • {n} (number) Number of values to skip.
+ • {n} (`number`) Number of values to skip.
Return: ~
- Iter
+ (`Iter`)
Iter:skipback({n}) *Iter:skipback()*
Skips `n` values backwards from the end of a |list-iterator| pipeline.
@@ -3687,10 +3690,10 @@ Iter:skipback({n}) *Iter:skipback()*
<
Parameters: ~
- • {n} (number) Number of values to skip.
+ • {n} (`number`) Number of values to skip.
Return: ~
- Iter
+ (`Iter`)
Iter:slice({first}, {last}) *Iter:slice()*
Sets the start and end of a |list-iterator| pipeline.
@@ -3698,11 +3701,11 @@ Iter:slice({first}, {last}) *Iter:slice()*
Equivalent to `:skip(first - 1):skipback(len - last + 1)`.
Parameters: ~
- • {first} (number)
- • {last} (number)
+ • {first} (`number`)
+ • {last} (`number`)
Return: ~
- Iter
+ (`Iter`)
Iter:take({n}) *Iter:take()*
Transforms an iterator to yield only the first n values.
@@ -3718,10 +3721,10 @@ Iter:take({n}) *Iter:take()*
<
Parameters: ~
- • {n} (integer)
+ • {n} (`integer`)
Return: ~
- Iter
+ (`Iter`)
Iter:totable() *Iter:totable()*
Collect the iterator into a table.
@@ -3747,7 +3750,7 @@ Iter:totable() *Iter:totable()*
|Iter:fold()|.
Return: ~
- (table)
+ (`table`)
map({f}, {src}, {...}) *vim.iter.map()*
Maps a table or other |iterable|. >lua
@@ -3756,13 +3759,13 @@ map({f}, {src}, {...}) *vim.iter.map()*
<
Parameters: ~
- • {f} function(...):?any Map function. Accepts the current iterator
+ • {f} (`fun(...): any?`) Map function. Accepts the current iterator
or table values as arguments and returns one or more new
values. Nil values are removed from the final table.
- • {src} table|function Table or iterator function to filter
+ • {src} (`table|function`) Table or iterator function to filter
Return: ~
- (table)
+ (`table`)
See also: ~
• |Iter:map()|
@@ -3774,10 +3777,10 @@ totable({f}, {...}) *vim.iter.totable()*
<
Parameters: ~
- • {f} (function) Iterator function
+ • {f} (`function`) Iterator function
Return: ~
- (table)
+ (`table`)
==============================================================================
@@ -3787,7 +3790,7 @@ vim.snippet.active() *vim.snippet.active()*
Returns `true` if there's an active snippet in the current buffer.
Return: ~
- (boolean)
+ (`boolean`)
vim.snippet.exit() *vim.snippet.exit()*
Exits the current snippet.
@@ -3799,7 +3802,7 @@ vim.snippet.expand({input}) *vim.snippet.expand()*
Tabstops are highlighted with hl-SnippetTabstop.
Parameters: ~
- • {input} (string)
+ • {input} (`string`)
vim.snippet.jump({direction}) *vim.snippet.jump()*
Jumps within the active snippet in the given direction. If the jump isn't
@@ -3816,7 +3819,7 @@ vim.snippet.jump({direction}) *vim.snippet.jump()*
<
Parameters: ~
- • {direction} (vim.snippet.Direction) Navigation direction. -1 for
+ • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for
previous, 1 for next.
vim.snippet.jumpable({direction}) *vim.snippet.jumpable()*
@@ -3833,11 +3836,11 @@ vim.snippet.jumpable({direction}) *vim.snippet.jumpable()*
<
Parameters: ~
- • {direction} (vim.snippet.Direction) Navigation direction. -1 for
+ • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for
previous, 1 for next.
Return: ~
- (boolean)
+ (`boolean`)
==============================================================================
@@ -3847,18 +3850,18 @@ vim.text.hexdecode({enc}) *vim.text.hexdecode()*
Hex decode a string.
Parameters: ~
- • {enc} (string) String to decode
+ • {enc} (`string`) String to decode
Return: ~
- (string) Decoded string
+ (`string`) Decoded string
vim.text.hexencode({str}) *vim.text.hexencode()*
Hex encode a string.
Parameters: ~
- • {str} (string) String to encode
+ • {str} (`string`) String to encode
Return: ~
- (string) Hex encoded string
+ (`string`) Hex encoded string
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 8702b98f76..14dedbcbd9 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -567,10 +567,10 @@ foldexpr({lnum}) *vim.treesitter.foldexpr()*
<
Parameters: ~
- • {lnum} (integer|nil) Line number to calculate fold level for
+ • {lnum} (`integer?`) Line number to calculate fold level for
Return: ~
- (string)
+ (`string`)
foldtext() *vim.treesitter.foldtext()*
Returns the highlighted content of the first line of the fold or falls
@@ -580,17 +580,17 @@ foldtext() *vim.treesitter.foldtext()*
<
Return: ~
- `{ [1]: string, [2]: string[] }[]` | string
+ (`{ [1]: string, [2]: string[] }[]|string`)
*vim.treesitter.get_captures_at_cursor()*
get_captures_at_cursor({winnr})
Returns a list of highlight capture names under the cursor
Parameters: ~
- • {winnr} (integer|nil) Window handle or 0 for current window (default)
+ • {winnr} (`integer?`) Window handle or 0 for current window (default)
Return: ~
- string[] List of capture names
+ (`string[]`) List of capture names
*vim.treesitter.get_captures_at_pos()*
get_captures_at_pos({bufnr}, {row}, {col})
@@ -601,12 +601,13 @@ get_captures_at_pos({bufnr}, {row}, {col})
if none are defined).
Parameters: ~
- • {bufnr} (integer) Buffer number (0 for current buffer)
- • {row} (integer) Position row
- • {col} (integer) Position column
+ • {bufnr} (`integer`) Buffer number (0 for current buffer)
+ • {row} (`integer`) Position row
+ • {col} (`integer`) Position column
Return: ~
- table[] List of captures `{ capture = "name", metadata = { ... } }`
+ (`table[]`) List of captures `{ capture = "name", metadata = { ... }
+ }`
get_node({opts}) *vim.treesitter.get_node()*
Returns the smallest named node at the given position
@@ -618,7 +619,7 @@ get_node({opts}) *vim.treesitter.get_node()*
<
Parameters: ~
- • {opts} (table|nil) Optional keyword arguments:
+ • {opts} (`table?`) Optional keyword arguments:
• bufnr integer|nil Buffer number (nil or 0 for current
buffer)
• pos table|nil 0-indexed (row, col) tuple. Defaults to cursor
@@ -630,35 +631,35 @@ get_node({opts}) *vim.treesitter.get_node()*
true)
Return: ~
- |TSNode| | nil Node at the given position
+ (`TSNode?`) Node at the given position
get_node_range({node_or_range}) *vim.treesitter.get_node_range()*
Returns the node's range or an unpacked range table
Parameters: ~
- • {node_or_range} (|TSNode| | table) Node or table of positions
+ • {node_or_range} (`TSNode|table`) Node or table of positions
Return (multiple): ~
- (integer) start_row
- (integer) start_col
- (integer) end_row
- (integer) end_col
+ (`integer`) start_row
+ (`integer`) start_col
+ (`integer`) end_row
+ (`integer`) end_col
*vim.treesitter.get_node_text()*
get_node_text({node}, {source}, {opts})
Gets the text corresponding to a given node
Parameters: ~
- • {node} |TSNode|
- • {source} (integer|string) Buffer or string from which the {node} is
+ • {node} (`TSNode`)
+ • {source} (`integer|string`) Buffer or string from which the {node} is
extracted
- • {opts} (table|nil) Optional parameters.
+ • {opts} (`table?`) Optional parameters.
• metadata (table) Metadata of a specific capture. This
would be set to `metadata[capture_id]` when using
|vim.treesitter.query.add_directive()|.
Return: ~
- (string)
+ (`string`)
get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()*
Returns the parser for a specific buffer and attaches it to the buffer
@@ -666,39 +667,39 @@ get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()*
If needed, this will create the parser.
Parameters: ~
- • {bufnr} (integer|nil) Buffer the parser should be tied to (default:
+ • {bufnr} (`integer?`) Buffer the parser should be tied to (default:
current buffer)
- • {lang} (string|nil) Filetype of this parser (default: buffer
+ • {lang} (`string?`) Filetype of this parser (default: buffer
filetype)
- • {opts} (table|nil) Options to pass to the created language tree
+ • {opts} (`table?`) Options to pass to the created language tree
Return: ~
- |LanguageTree| object to use for parsing
+ (`LanguageTree`) object to use for parsing
get_range({node}, {source}, {metadata}) *vim.treesitter.get_range()*
Get the range of a |TSNode|. Can also supply {source} and {metadata} to
get the range with directives applied.
Parameters: ~
- • {node} |TSNode|
- • {source} integer|string|nil Buffer or string from which the {node}
+ • {node} (`TSNode`)
+ • {source} (`integer|string?`) Buffer or string from which the {node}
is extracted
- • {metadata} TSMetadata|nil
+ • {metadata} (`TSMetadata?`)
Return: ~
- (table)
+ (`Range6`)
*vim.treesitter.get_string_parser()*
get_string_parser({str}, {lang}, {opts})
Returns a string parser
Parameters: ~
- • {str} (string) Text to parse
- • {lang} (string) Language of this string
- • {opts} (table|nil) Options to pass to the created language tree
+ • {str} (`string`) Text to parse
+ • {lang} (`string`) Language of this string
+ • {opts} (`table?`) Options to pass to the created language tree
Return: ~
- |LanguageTree| object to use for parsing
+ (`LanguageTree`) object to use for parsing
inspect_tree({opts}) *vim.treesitter.inspect_tree()*
Open a window that displays a textual representation of the nodes in the
@@ -712,7 +713,7 @@ inspect_tree({opts}) *vim.treesitter.inspect_tree()*
Can also be shown with `:InspectTree`. *:InspectTree*
Parameters: ~
- • {opts} (table|nil) Optional options table with the following possible
+ • {opts} (`table?`) Optional options table with the following possible
keys:
• lang (string|nil): The language of the source buffer. If
omitted, the filetype of the source buffer is used.
@@ -732,33 +733,33 @@ is_ancestor({dest}, {source}) *vim.treesitter.is_ancestor()*
Determines whether a node is the ancestor of another
Parameters: ~
- • {dest} |TSNode| Possible ancestor
- • {source} |TSNode| Possible descendant
+ • {dest} (`TSNode`) Possible ancestor
+ • {source} (`TSNode`) Possible descendant
Return: ~
- (boolean) True if {dest} is an ancestor of {source}
+ (`boolean`) True if {dest} is an ancestor of {source}
*vim.treesitter.is_in_node_range()*
is_in_node_range({node}, {line}, {col})
Determines whether (line, col) position is in node range
Parameters: ~
- • {node} |TSNode| defining the range
- • {line} (integer) Line (0-based)
- • {col} (integer) Column (0-based)
+ • {node} (`TSNode`) defining the range
+ • {line} (`integer`) Line (0-based)
+ • {col} (`integer`) Column (0-based)
Return: ~
- (boolean) True if the position is in node range
+ (`boolean`) True if the position is in node range
node_contains({node}, {range}) *vim.treesitter.node_contains()*
Determines if a node contains a range
Parameters: ~
- • {node} |TSNode|
- • {range} (table)
+ • {node} (`TSNode`)
+ • {range} (`table`)
Return: ~
- (boolean) True if the {node} contains the {range}
+ (`boolean`) True if the {node} contains the {range}
start({bufnr}, {lang}) *vim.treesitter.start()*
Starts treesitter highlighting for a buffer
@@ -779,16 +780,15 @@ start({bufnr}, {lang}) *vim.treesitter.start()*
<
Parameters: ~
- • {bufnr} (integer|nil) Buffer to be highlighted (default: current
+ • {bufnr} (`integer?`) Buffer to be highlighted (default: current
buffer)
- • {lang} (string|nil) Language of the parser (default: buffer
- filetype)
+ • {lang} (`string?`) Language of the parser (default: buffer filetype)
stop({bufnr}) *vim.treesitter.stop()*
Stops treesitter highlighting for a buffer
Parameters: ~
- • {bufnr} (integer|nil) Buffer to stop highlighting (default: current
+ • {bufnr} (`integer?`) Buffer to stop highlighting (default: current
buffer)
@@ -802,8 +802,8 @@ add({lang}, {opts}) *vim.treesitter.language.add()*
{path}
Parameters: ~
- • {lang} (string) Name of the parser (alphanumerical and `_` only)
- • {opts} (table|nil) Options:
+ • {lang} (`string`) Name of the parser (alphanumerical and `_` only)
+ • {opts} (`table?`) Options:
• filetype (string|string[]) Default filetype the parser
should be associated with. Defaults to {lang}.
• path (string|nil) Optional path the parser is located at
@@ -814,17 +814,17 @@ get_filetypes({lang}) *vim.treesitter.language.get_filetypes()*
Get the filetypes associated with the parser named {lang}.
Parameters: ~
- • {lang} (string) Name of parser
+ • {lang} (`string`) Name of parser
Return: ~
- string[] filetypes
+ (`string[]`) filetypes
get_lang({filetype}) *vim.treesitter.language.get_lang()*
Parameters: ~
- • {filetype} (string)
+ • {filetype} (`string`)
Return: ~
- (string|nil)
+ (`string?`)
inspect({lang}) *vim.treesitter.language.inspect()*
Inspects the provided language.
@@ -833,10 +833,10 @@ inspect({lang}) *vim.treesitter.language.inspect()*
names, ...
Parameters: ~
- • {lang} (string) Language
+ • {lang} (`string`) Language
Return: ~
- (table)
+ (`table`)
register({lang}, {filetype}) *vim.treesitter.language.register()*
Register a parser named {lang} to be used for {filetype}(s).
@@ -845,8 +845,8 @@ register({lang}, {filetype}) *vim.treesitter.language.register()*
mappings from other filetypes to {lang} will be preserved.
Parameters: ~
- • {lang} (string) Name of parser
- • {filetype} string|string[] Filetype(s) to associate with lang
+ • {lang} (`string`) Name of parser
+ • {filetype} (`string|string[]`) Filetype(s) to associate with lang
==============================================================================
@@ -862,9 +862,8 @@ add_directive({name}, {handler}, {force})
`metadata[capture_id].key = value`
Parameters: ~
- • {name} (string) Name of the directive, without leading #
- • {handler} function(match:table<string,|TSNode|>, pattern:string,
- bufnr:integer, predicate:string[], metadata:table)
+ • {name} (`string`) Name of the directive, without leading #
+ • {handler} (`function`)
• match: see |treesitter-query|
• node-level data are accessible via `match[capture_id]`
@@ -872,19 +871,18 @@ add_directive({name}, {handler}, {force})
• predicate: list of strings containing the full directive
being called, e.g. `(node (#set! conceal "-"))` would get
the predicate `{ "#set!", "conceal", "-" }`
- • {force} (boolean|nil)
+ • {force} (`boolean?`)
*vim.treesitter.query.add_predicate()*
add_predicate({name}, {handler}, {force})
Adds a new predicate to be used in queries
Parameters: ~
- • {name} (string) Name of the predicate, without leading #
- • {handler} function(match:table<string,|TSNode|>, pattern:string,
- bufnr:integer, predicate:string[])
+ • {name} (`string`) Name of the predicate, without leading #
+ • {handler} (`function`)
• see |vim.treesitter.query.add_directive()| for argument
meanings
- • {force} (boolean|nil)
+ • {force} (`boolean?`)
edit({lang}) *vim.treesitter.query.edit()*
Opens a live editor to query the buffer you started from.
@@ -897,31 +895,32 @@ edit({lang}) *vim.treesitter.query.edit()*
`$VIMRUNTIME/queries/`.
Parameters: ~
- • {lang} (string|nil) language to open the query editor for. If
- omitted, inferred from the current buffer's filetype.
+ • {lang} (`string?`) language to open the query editor for. If omitted,
+ inferred from the current buffer's filetype.
get({lang}, {query_name}) *vim.treesitter.query.get()*
Returns the runtime query {query_name} for {lang}.
Parameters: ~
- • {lang} (string) Language to use for the query
- • {query_name} (string) Name of the query (e.g. "highlights")
+ • {lang} (`string`) Language to use for the query
+ • {query_name} (`string`) Name of the query (e.g. "highlights")
Return: ~
- Query|nil Parsed query
+ (`Query?`) Parsed query
*vim.treesitter.query.get_files()*
get_files({lang}, {query_name}, {is_included})
Gets the list of files used to make up a query
Parameters: ~
- • {lang} (string) Language to get query for
- • {query_name} (string) Name of the query to load (e.g., "highlights")
- • {is_included} (boolean|nil) Internal parameter, most of the time left
+ • {lang} (`string`) Language to get query for
+ • {query_name} (`string`) Name of the query to load (e.g.,
+ "highlights")
+ • {is_included} (`boolean?`) Internal parameter, most of the time left
as `nil`
Return: ~
- string[] query_files List of files to load for given query and
+ (`string[]`) query_files List of files to load for given query and
language
lint({buf}, {opts}) *vim.treesitter.query.lint()*
@@ -940,8 +939,8 @@ lint({buf}, {opts}) *vim.treesitter.query.lint()*
for the `lua` language will be used.
Parameters: ~
- • {buf} (integer) Buffer handle
- • {opts} (QueryLinterOpts|nil) Optional keyword arguments:
+ • {buf} (`integer`) Buffer handle
+ • {opts} (`table?`) Optional keyword arguments:
• langs (string|string[]|nil) Language(s) to use for checking
the query. If multiple languages are specified, queries are
validated for all of them
@@ -951,13 +950,13 @@ list_directives() *vim.treesitter.query.list_directives()*
Lists the currently available directives to use in queries.
Return: ~
- string[] List of supported directives.
+ (`string[]`) List of supported directives.
list_predicates() *vim.treesitter.query.list_predicates()*
Lists the currently available predicates to use in queries.
Return: ~
- string[] List of supported predicates.
+ (`string[]`) List of supported predicates.
omnifunc({findstart}, {base}) *vim.treesitter.query.omnifunc()*
Omnifunc for completing node names and predicates in treesitter queries.
@@ -980,11 +979,11 @@ parse({lang}, {query}) *vim.treesitter.query.parse()*
• `info.patterns` contains information about predicates.
Parameters: ~
- • {lang} (string) Language to use for the query
- • {query} (string) Query in s-expr syntax
+ • {lang} (`string`) Language to use for the query
+ • {query} (`string`) Query in s-expr syntax
Return: ~
- Query Parsed query
+ (`Query`) Parsed query
*Query:iter_captures()*
Query:iter_captures({node}, {source}, {start}, {stop})
@@ -1010,14 +1009,14 @@ Query:iter_captures({node}, {source}, {start}, {stop})
<
Parameters: ~
- • {node} |TSNode| under which the search will occur
- • {source} (integer|string) Source buffer or string to extract text
+ • {node} (`TSNode`) under which the search will occur
+ • {source} (`integer|string`) Source buffer or string to extract text
from
- • {start} (integer) Starting line for the search
- • {stop} (integer) Stopping line for the search (end-exclusive)
+ • {start} (`integer`) Starting line for the search
+ • {stop} (`integer`) Stopping line for the search (end-exclusive)
Return: ~
- (fun(end_line: integer|nil): integer, TSNode, TSMetadata): capture id,
+ (`fun(end_line: integer?): integer, TSNode, TSMetadata`) capture id,
capture node, metadata
*Query:iter_matches()*
@@ -1044,18 +1043,18 @@ Query:iter_matches({node}, {source}, {start}, {stop}, {opts})
<
Parameters: ~
- • {node} |TSNode| under which the search will occur
- • {source} (integer|string) Source buffer or string to search
- • {start} (integer) Starting line for the search
- • {stop} (integer) Stopping line for the search (end-exclusive)
- • {opts} (table|nil) Options:
+ • {node} (`TSNode`) under which the search will occur
+ • {source} (`integer|string`) Source buffer or string to search
+ • {start} (`integer`) Starting line for the search
+ • {stop} (`integer`) Stopping line for the search (end-exclusive)
+ • {opts} (`table?`) Options:
• max_start_depth (integer) if non-zero, sets the maximum
start depth for each match. This is used to prevent
traversing too deep into a tree. Requires treesitter >=
0.20.9.
Return: ~
- (fun(): integer, table<integer,TSNode>, table): pattern id, match,
+ (`fun(): integer, table<integer,TSNode>, table`) pattern id, match,
metadata
set({lang}, {query_name}, {text}) *vim.treesitter.query.set()*
@@ -1065,9 +1064,9 @@ set({lang}, {query_name}, {text}) *vim.treesitter.query.set()*
by plugins.
Parameters: ~
- • {lang} (string) Language to use for the query
- • {query_name} (string) Name of the query (e.g., "highlights")
- • {text} (string) Query text (unparsed).
+ • {lang} (`string`) Language to use for the query
+ • {query_name} (`string`) Name of the query (e.g., "highlights")
+ • {text} (`string`) Query text (unparsed).
==============================================================================
@@ -1117,10 +1116,10 @@ LanguageTree:contains({range}) *LanguageTree:contains()*
Determines whether {range} is contained in the |LanguageTree|.
Parameters: ~
- • {range} (table) `{ start_line, start_col, end_line, end_col }`
+ • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }`
Return: ~
- (boolean)
+ (`boolean`)
LanguageTree:destroy() *LanguageTree:destroy()*
Destroys this |LanguageTree| and all its children.
@@ -1136,21 +1135,21 @@ LanguageTree:for_each_tree({fn}) *LanguageTree:for_each_tree()*
Note: This includes the invoking tree's child trees as well.
Parameters: ~
- • {fn} fun(tree: TSTree, ltree: LanguageTree)
+ • {fn} (`fun(tree: TSTree, ltree: LanguageTree)`)
LanguageTree:included_regions() *LanguageTree:included_regions()*
- Gets the set of included regions managed by this LanguageTree . This can
- be different from the regions set by injection query, because a partial
+ Gets the set of included regions managed by this LanguageTree . This can be
+ different from the regions set by injection query, because a partial
|LanguageTree:parse()| drops the regions outside the requested range.
Return: ~
- table<integer, Range6[]>
+ (`table<integer, Range6[]>`)
LanguageTree:invalidate({reload}) *LanguageTree:invalidate()*
Invalidates this parser and all its children
Parameters: ~
- • {reload} (boolean|nil)
+ • {reload} (`boolean?`)
LanguageTree:is_valid({exclude_children}) *LanguageTree:is_valid()*
Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()|
@@ -1158,11 +1157,11 @@ LanguageTree:is_valid({exclude_children}) *LanguageTree:is_valid()*
|LanguageTree:parse()|.
Parameters: ~
- • {exclude_children} (boolean|nil) whether to ignore the validity of
+ • {exclude_children} (`boolean?`) whether to ignore the validity of
children (default `false`)
Return: ~
- (boolean)
+ (`boolean`)
LanguageTree:lang() *LanguageTree:lang()*
Gets the language of this tree node.
@@ -1172,23 +1171,23 @@ LanguageTree:language_for_range({range})
Gets the appropriate language that contains {range}.
Parameters: ~
- • {range} (table) `{ start_line, start_col, end_line, end_col }`
+ • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }`
Return: ~
- |LanguageTree| Managing {range}
+ (`LanguageTree`) Managing {range}
*LanguageTree:named_node_for_range()*
LanguageTree:named_node_for_range({range}, {opts})
Gets the smallest named node that contains {range}.
Parameters: ~
- • {range} (table) `{ start_line, start_col, end_line, end_col }`
- • {opts} (table|nil) Optional keyword arguments:
+ • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }`
+ • {opts} (`table?`) Optional keyword arguments:
• ignore_injections boolean Ignore injected languages
(default true)
Return: ~
- |TSNode| | nil Found node
+ (`TSNode?`) Found node
LanguageTree:parse({range}) *LanguageTree:parse()*
Recursively parse all regions in the language tree using
@@ -1201,21 +1200,21 @@ LanguageTree:parse({range}) *LanguageTree:parse()*
if {range} is `true`).
Parameters: ~
- • {range} boolean|Range|nil: Parse this range in the parser's source.
+ • {range} (`boolean|Range?`) Parse this range in the parser's source.
Set to `true` to run a complete parse of the source (Note:
Can be slow!) Set to `false|nil` to only parse regions with
empty ranges (typically only the root tree without
injections).
Return: ~
- table<integer, TSTree>
+ (`table<integer, TSTree>`)
*LanguageTree:register_cbs()*
LanguageTree:register_cbs({cbs}, {recursive})
Registers callbacks for the |LanguageTree|.
Parameters: ~
- • {cbs} (table) An |nvim_buf_attach()|-like table argument with
+ • {cbs} (`table`) An |nvim_buf_attach()|-like table argument with
the following handlers:
• `on_bytes` : see |nvim_buf_attach()|, but this will be
called after the parsers callback.
@@ -1230,7 +1229,7 @@ LanguageTree:register_cbs({cbs}, {recursive})
• `on_detach` : emitted when the buffer is detached, see
|nvim_buf_detach_event|. Takes one argument, the number
of the buffer.
- • {recursive} (boolean|nil) Apply callbacks recursively for all
+ • {recursive} (`boolean?`) Apply callbacks recursively for all
children. Any new children will also inherit the
callbacks.
@@ -1242,13 +1241,13 @@ LanguageTree:tree_for_range({range}, {opts})
Gets the tree that contains {range}.
Parameters: ~
- • {range} (table) `{ start_line, start_col, end_line, end_col }`
- • {opts} (table|nil) Optional keyword arguments:
+ • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }`
+ • {opts} (`table?`) Optional keyword arguments:
• ignore_injections boolean Ignore injected languages
(default true)
Return: ~
- TSTree|nil
+ (`TSTree?`)
LanguageTree:trees() *LanguageTree:trees()*
Returns all trees of the regions parsed by this parser. Does not include
@@ -1258,6 +1257,6 @@ LanguageTree:trees() *LanguageTree:trees()*
• the root LanguageTree is fully parsed.
Return: ~
- table<integer, TSTree>
+ (`table<integer, TSTree>`)
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index cde61697b6..4fe601dfd5 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -95,7 +95,7 @@ vim.log = {
--- throws an error if {cmd} cannot be run.
---
--- @param cmd (string[]) Command to execute
---- @param opts (SystemOpts|nil) Options:
+--- @param opts vim.SystemOpts? Options:
--- - cwd: (string) Set the current working directory for the sub-process.
--- - env: table<string,string> Set environment variables for the new process. Inherits the
--- current environment with `NVIM` set to |v:servername|.
@@ -118,7 +118,7 @@ vim.log = {
--- parent exits. Note that the child process will still keep the parent's event loop alive
--- unless the parent process calls |uv.unref()| on the child's process handle.
---
---- @param on_exit (function|nil) Called when subprocess exits. When provided, the command runs
+--- @param on_exit? fun(out: vim.SystemCompleted) Called when subprocess exits. When provided, the command runs
--- asynchronously. Receives SystemCompleted object, see return of SystemObj:wait().
---
--- @return vim.SystemObj Object with the fields:
@@ -219,10 +219,9 @@ do
--- ```
---
---@see |paste|
- ---@alias paste_phase -1 | 1 | 2 | 3
---
---@param lines string[] # |readfile()|-style list of lines to paste. |channel-lines|
- ---@param phase paste_phase -1: "non-streaming" paste: the call contains all lines.
+ ---@param phase (-1|1|2|3) -1: "non-streaming" paste: the call contains all lines.
--- If paste is "streamed", `phase` indicates the stream state:
--- - 1: starts the paste (exactly once)
--- - 2: continues the paste (zero or more times)
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 19039eb226..3f06d4fd43 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -812,9 +812,8 @@ function vim.api.nvim_complete_set(index, opts) end
--- @return integer
function vim.api.nvim_create_augroup(name, opts) end
---- Creates an `autocommand` event handler, defined by `callback` (Lua
---- function or Vimscript function name string) or `command` (Ex command
---- string).
+--- Creates an `autocommand` event handler, defined by `callback` (Lua function
+--- or Vimscript function name string) or `command` (Ex command string).
--- Example using Lua callback:
---
--- ```lua
diff --git a/runtime/lua/vim/_system.lua b/runtime/lua/vim/_system.lua
index 9279febddf..9e935b7e95 100644
--- a/runtime/lua/vim/_system.lua
+++ b/runtime/lua/vim/_system.lua
@@ -1,6 +1,6 @@
local uv = vim.uv
---- @class SystemOpts
+--- @class vim.SystemOpts
--- @field stdin? string|string[]|true
--- @field stdout? fun(err:string?, data: string?)|false
--- @field stderr? fun(err:string?, data: string?)|false
@@ -302,7 +302,7 @@ end
--- Run a system command
---
--- @param cmd string[]
---- @param opts? SystemOpts
+--- @param opts? vim.SystemOpts
--- @param on_exit? fun(out: vim.SystemCompleted)
--- @return vim.SystemObj
function M.run(cmd, opts, on_exit)
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
index 9141b1e4c6..8cd5f19569 100644
--- a/runtime/lua/vim/filetype.lua
+++ b/runtime/lua/vim/filetype.lua
@@ -2165,7 +2165,7 @@ end
--- }
--- ```
---
----@param filetypes vim.filetype.add.filetypes A table containing new filetype maps (see example).
+---@param filetypes vim.filetype.add.filetypes (table) A table containing new filetype maps (see example).
function M.add(filetypes)
for k, v in pairs(filetypes.extension or {}) do
extension[k] = v
@@ -2300,7 +2300,7 @@ end
--- vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
--- ```
---
----@param args vim.filetype.match.args Table specifying which matching strategy to use.
+---@param args vim.filetype.match.args (table) Table specifying which matching strategy to use.
--- Accepted keys are:
--- * buf (number): Buffer number to use for matching. Mutually exclusive with
--- {contents}
diff --git a/runtime/lua/vim/health.lua b/runtime/lua/vim/health.lua
index d9265f6bd6..f6f7abef8f 100644
--- a/runtime/lua/vim/health.lua
+++ b/runtime/lua/vim/health.lua
@@ -315,7 +315,7 @@ end
--- Run a system command and timeout after 30 seconds.
---
--- @param cmd table List of command arguments to execute
---- @param args ?table Optional arguments:
+--- @param args? table Optional arguments:
--- - stdin (string): Data to write to the job's stdin
--- - stderr (boolean): Append stderr to stdout
--- - ignore_error (boolean): If true, ignore error output
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index c6feeea3dc..a63d5ba565 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -181,9 +181,9 @@ end
--- local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
--- ```
---
----@param f function(...):bool Takes all values returned from the previous stage
---- in the pipeline and returns false or nil if the
---- current iterator element should be removed.
+---@param f fun(...):bool Takes all values returned from the previous stage
+--- in the pipeline and returns false or nil if the
+--- current iterator element should be removed.
---@return Iter
function Iter.filter(self, f)
return self:map(function(...)
@@ -272,11 +272,11 @@ end
--- -- { 6, 12 }
--- ```
---
----@param f function(...):any Mapping function. Takes all values returned from
---- the previous stage in the pipeline as arguments
---- and returns one or more new values, which are used
---- in the next pipeline stage. Nil return values
---- are filtered from the output.
+---@param f fun(...):any Mapping function. Takes all values returned from
+--- the previous stage in the pipeline as arguments
+--- and returns one or more new values, which are used
+--- in the next pipeline stage. Nil return values
+--- are filtered from the output.
---@return Iter
function Iter.map(self, f)
-- Implementation note: the reader may be forgiven for observing that this
@@ -340,9 +340,9 @@ end
---
--- For functions with side effects. To modify the values in the iterator, use |Iter:map()|.
---
----@param f function(...) Function to execute for each item in the pipeline.
---- Takes all of the values returned by the previous stage
---- in the pipeline as arguments.
+---@param f fun(...) Function to execute for each item in the pipeline.
+--- Takes all of the values returned by the previous stage
+--- in the pipeline as arguments.
function Iter.each(self, f)
local function fn(...)
if select(1, ...) ~= nil then
@@ -464,7 +464,7 @@ end
---@generic A
---
---@param init A Initial value of the accumulator.
----@param f function(acc:A, ...):A Accumulation function.
+---@param f fun(acc:A, ...):A Accumulation function.
---@return A
function Iter.fold(self, init, f)
local acc = init
@@ -884,9 +884,9 @@ end
--- Returns true if any of the items in the iterator match the given predicate.
---
----@param pred function(...):bool Predicate function. Takes all values returned from the previous
---- stage in the pipeline as arguments and returns true if the
---- predicate matches.
+---@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+--- stage in the pipeline as arguments and returns true if the
+--- predicate matches.
function Iter.any(self, pred)
local any = false
@@ -908,9 +908,9 @@ end
--- Returns true if all items in the iterator match the given predicate.
---
----@param pred function(...):bool Predicate function. Takes all values returned from the previous
---- stage in the pipeline as arguments and returns true if the
---- predicate matches.
+---@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+--- stage in the pipeline as arguments and returns true if the
+--- predicate matches.
function Iter.all(self, pred)
local all = true
@@ -1106,9 +1106,9 @@ end
---
---@see |Iter:filter()|
---
----@param f function(...):bool Filter function. Accepts the current iterator or table values as
---- arguments and returns true if those values should be kept in the
---- final table
+---@param f fun(...):bool Filter function. Accepts the current iterator or table values as
+--- arguments and returns true if those values should be kept in the
+--- final table
---@param src table|function Table or iterator function to filter
---@return table
function M.filter(f, src, ...)
@@ -1124,9 +1124,9 @@ end
---
---@see |Iter:map()|
---
----@param f function(...):?any Map function. Accepts the current iterator or table values as
---- arguments and returns one or more new values. Nil values are removed
---- from the final table.
+---@param f fun(...): any? Map function. Accepts the current iterator or table values as
+--- arguments and returns one or more new values. Nil values are removed
+--- from the final table.
---@param src table|function Table or iterator function to filter
---@return table
function M.map(f, src, ...)
diff --git a/runtime/lua/vim/lsp/handlers.lua b/runtime/lua/vim/lsp/handlers.lua
index c03a17fa59..daf09b6430 100644
--- a/runtime/lua/vim/lsp/handlers.lua
+++ b/runtime/lua/vim/lsp/handlers.lua
@@ -516,7 +516,7 @@ end
---
--- Displays call hierarchy in the quickfix window.
---
----@param direction `"from"` for incoming calls and `"to"` for outgoing calls
+---@param direction 'from'|'to' `"from"` for incoming calls and `"to"` for outgoing calls
---@return function
--- `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
--- `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,
diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index 44465f6cff..a2cc81781a 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -790,7 +790,7 @@ end
--- Note that if the input is of type `MarkupContent` and its kind is `plaintext`,
--- then the corresponding value is returned without further modifications.
---
----@param input (`MarkedString` | `MarkedString[]` | `MarkupContent`)
+---@param input (lsp.MarkedString | lsp.MarkedString[] | lsp.MarkupContent)
---@param contents (table|nil) List of strings to extend with converted lines. Defaults to {}.
---@return string[] extended with lines of converted markdown.
---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
@@ -2115,8 +2115,8 @@ end
--- Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer.
---
---@param buf integer buffer number (0 for current)
----@param row 0-indexed line
----@param col 0-indexed byte offset in line
+---@param row integer 0-indexed line
+---@param col integer 0-indexed byte offset in line
---@param offset_encoding string utf-8|utf-16|utf-32 defaults to `offset_encoding` of first client of `buf`
---@return integer `offset_encoding` index of the character in line {row} column {col} in buffer {buf}
function M.character_offset(buf, row, col, offset_encoding)
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 24bc97bf8e..e76d148b1b 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -875,7 +875,7 @@ end
--- a.b.c = 1
--- ```
---
----@param createfn function?(key:any):any Provides the value for a missing `key`.
+---@param createfn? fun(key:any):any Provides the value for a missing `key`.
---@return table # Empty table with `__index` metamethod.
function vim.defaulttable(createfn)
createfn = createfn or function(_)
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 8cbbffcd60..cc8fe319e8 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -793,7 +793,7 @@ end
--- of the query file, e.g., if the path ends in `/lua/highlights.scm`, the parser for the
--- `lua` language will be used.
---@param buf (integer) Buffer handle
----@param opts (QueryLinterOpts|nil) Optional keyword arguments:
+---@param opts? QueryLinterOpts (table) Optional keyword arguments:
--- - langs (string|string[]|nil) Language(s) to use for checking the query.
--- If multiple languages are specified, queries are validated for all of them
--- - clear (boolean) if `true`, just clear current lint errors
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index 698336cf3e..01532cc3d3 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -717,12 +717,14 @@ def render_node(n: Element, text: str, prefix='', *,
elif n.nodeName in ('para', 'heading'):
did_prefix = False
for c in n.childNodes:
+ c_text = render_node(c, text, prefix=(prefix if not did_prefix else ''), indent=indent, width=width)
if (is_inline(c)
- and '' != get_text(c).strip()
+ and '' != c_text.strip()
and text
- and ' ' != text[-1]):
+ and text[-1] not in (' ', '(', '|')
+ and not c_text.startswith(')')):
text += ' '
- text += render_node(c, text, prefix=(prefix if not did_prefix else ''), indent=indent, width=width)
+ text += c_text
did_prefix = True
elif n.nodeName == 'itemizedlist':
for c in n.childNodes:
@@ -840,15 +842,17 @@ def para_as_map(parent: Element,
raise RuntimeError('unhandled simplesect: {}\n{}'.format(
child.nodeName, child.toprettyxml(indent=' ', newl='\n')))
else:
+ child_text = render_node(child, text, indent=indent, width=width)
if (prev is not None
and is_inline(self_or_child(prev))
and is_inline(self_or_child(child))
and '' != get_text(self_or_child(child)).strip()
and text
- and ' ' != text[-1]):
+ and text[-1] not in (' ', '(', '|')
+ and not child_text.startswith(')')):
text += ' '
- text += render_node(child, text, indent=indent, width=width)
+ text += child_text
prev = child
chunks['text'] += text
diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua
index c4ad7fbb03..abc9e5b338 100644
--- a/scripts/lua2dox.lua
+++ b/scripts/lua2dox.lua
@@ -55,17 +55,7 @@ The effect is that you will get the function documented, but not with the parame
local TYPES = { 'integer', 'number', 'string', 'table', 'list', 'boolean', 'function' }
-local TAGGED_TYPES = { 'TSNode', 'LanguageTree' }
-
--- Document these as 'table'
-local ALIAS_TYPES = {
- 'Range',
- 'Range4',
- 'Range6',
- 'TSMetadata',
- 'vim.filetype.add.filetypes',
- 'vim.filetype.match.args',
-}
+local luacats_parser = require('src/nvim/generators/luacats_grammar')
local debug_outfile = nil --- @type string?
local debug_output = {}
@@ -161,6 +151,91 @@ local function removeCommentFromLine(line)
return line:sub(1, pos_comment - 1), line:sub(pos_comment)
end
+--- @param parsed luacats.Return
+--- @return string
+local function get_return_type(parsed)
+ local elems = {} --- @type string[]
+ for _, v in ipairs(parsed) do
+ local e = v.type --- @type string
+ if v.name then
+ e = e .. ' ' .. v.name --- @type string
+ end
+ elems[#elems + 1] = e
+ end
+ return '(' .. table.concat(elems, ', ') .. ')'
+end
+
+--- @param name string
+--- @return string
+local function process_name(name, optional)
+ if optional then
+ name = name:sub(1, -2) --- @type string
+ end
+ return name
+end
+
+--- @param ty string
+--- @param generics table<string,string>
+--- @return string
+local function process_type(ty, generics, optional)
+ -- replace generic types
+ for k, v in pairs(generics) do
+ ty = ty:gsub(k, v) --- @type string
+ end
+
+ -- strip parens
+ ty = ty:gsub('^%((.*)%)$', '%1')
+
+ if optional and not ty:find('nil') then
+ ty = ty .. '?'
+ end
+
+ -- remove whitespace in unions
+ ty = ty:gsub('%s*|%s*', '|')
+
+ -- replace '|nil' with '?'
+ ty = ty:gsub('|nil', '?')
+ ty = ty:gsub('nil|(.*)', '%1?')
+
+ return '(`' .. ty .. '`)'
+end
+
+--- @param parsed luacats.Param
+--- @param generics table<string,string>
+--- @return string
+local function process_param(parsed, generics)
+ local name, ty = parsed.name, parsed.type
+ local optional = vim.endswith(name, '?')
+
+ return table.concat({
+ '/// @param',
+ process_name(name, optional),
+ process_type(ty, generics, optional),
+ parsed.desc,
+ }, ' ')
+end
+
+--- @param parsed luacats.Return
+--- @param generics table<string,string>
+--- @return string
+local function process_return(parsed, generics)
+ local ty, name --- @type string, string
+ if #parsed == 1 then
+ ty, name = parsed[1].type, parsed[1].name or ''
+ else
+ ty, name = get_return_type(parsed), ''
+ end
+
+ local optional = vim.endswith(name, '?')
+
+ return table.concat({
+ '/// @return',
+ process_type(ty, generics, optional),
+ process_name(name, optional),
+ parsed.desc,
+ }, ' ')
+end
+
--- Processes "@…" directives in a docstring line.
---
--- @param line string
@@ -175,93 +250,54 @@ local function process_magic(line, generics)
return '/// ' .. line
end
- local magic = line:sub(2)
- local magic_split = vim.split(magic, ' ', { plain = true })
+ local magic_split = vim.split(line, ' ', { plain = true })
local directive = magic_split[1]
if
vim.list_contains({
- 'cast',
- 'diagnostic',
- 'overload',
- 'meta',
- 'type',
+ '@cast',
+ '@diagnostic',
+ '@overload',
+ '@meta',
+ '@type',
}, directive)
then
-- Ignore LSP directives
return '// gg:"' .. line .. '"'
- end
-
- if directive == 'defgroup' or directive == 'addtogroup' then
+ elseif directive == '@defgroup' or directive == '@addtogroup' then
-- Can't use '.' in defgroup, so convert to '--'
- return '/// @' .. magic:gsub('%.', '-dot-')
- end
-
- if directive == 'generic' then
- local generic_name, generic_type = line:match('@generic%s*(%w+)%s*:?%s*(.*)')
- if generic_type == '' then
- generic_type = 'any'
- end
- generics[generic_name] = generic_type
- return
+ return '/// ' .. line:gsub('%.', '-dot-')
end
- local type_index = 2
-
- if directive == 'param' then
+ -- preprocess line before parsing
+ if directive == '@param' or directive == '@return' then
for _, type in ipairs(TYPES) do
- magic = magic:gsub('^param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. ')%)', 'param %1 %2')
- magic = magic:gsub('^param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. '|nil)%)', 'param %1 %2')
- end
- magic_split = vim.split(magic, ' ', { plain = true })
- type_index = 3
- elseif directive == 'return' then
- for _, type in ipairs(TYPES) do
- magic = magic:gsub('^return%s+.*%((' .. type .. ')%)', 'return %1')
- magic = magic:gsub('^return%s+.*%((' .. type .. '|nil)%)', 'return %1')
- end
- -- Remove first "#" comment char, if any. https://github.com/LuaLS/lua-language-server/wiki/Annotations#return
- magic = magic:gsub('# ', '', 1)
- -- handle the return of vim.spell.check
- magic = magic:gsub('({.*}%[%])', '`%1`')
- magic_split = vim.split(magic, ' ', { plain = true })
- end
-
- local ty = magic_split[type_index]
-
- if ty then
- -- fix optional parameters
- if magic_split[2]:find('%?$') then
- if not ty:find('nil') then
- ty = ty .. '|nil'
- end
- magic_split[2] = magic_split[2]:sub(1, -2)
- end
+ line = line:gsub('^@param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. ')%)', '@param %1 %2')
+ line = line:gsub('^@param%s+([a-zA-Z_?]+)%s+.*%((' .. type .. '|nil)%)', '@param %1 %2')
- -- replace generic types
- for k, v in pairs(generics) do
- ty = ty:gsub(k, v) --- @type string
+ line = line:gsub('^@return%s+.*%((' .. type .. ')%)', '@return %1')
+ line = line:gsub('^@return%s+.*%((' .. type .. '|nil)%)', '@return %1')
end
+ end
- for _, type in ipairs(TAGGED_TYPES) do
- ty = ty:gsub(type, '|%1|')
- end
+ local parsed = luacats_parser:match(line)
- for _, type in ipairs(ALIAS_TYPES) do
- ty = ty:gsub('^' .. type .. '$', 'table') --- @type string
- end
+ if not parsed then
+ return '/// ' .. line
+ end
- -- surround some types by ()
- for _, type in ipairs(TYPES) do
- ty = ty:gsub('^(' .. type .. '|nil):?$', '(%1)'):gsub('^(' .. type .. '):?$', '(%1)')
- end
+ local kind = parsed.kind
- magic_split[type_index] = ty
+ if kind == 'generic' then
+ generics[parsed.name] = parsed.type or 'any'
+ return
+ elseif kind == 'param' then
+ return process_param(parsed --[[@as luacats.Param]], generics)
+ elseif kind == 'return' then
+ return process_return(parsed --[[@as luacats.Return]], generics)
end
- magic = table.concat(magic_split, ' ')
-
- return '/// @' .. magic
+ error(string.format('unhandled parsed line %q: %s', line, parsed))
end
--- @param line string
diff --git a/src/nvim/CMakeLists.txt b/src/nvim/CMakeLists.txt
index 53ff761b16..8e52542446 100644
--- a/src/nvim/CMakeLists.txt
+++ b/src/nvim/CMakeLists.txt
@@ -925,6 +925,8 @@ add_custom_command(
${API_SOURCES}
${LUA_SOURCES}
${VIMDOC_FILES}
+ ${PROJECT_SOURCE_DIR}/scripts/gen_vimdoc.py
+ ${PROJECT_SOURCE_DIR}/scripts/lua2dox.lua
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
)
diff --git a/src/nvim/generators/luacats_grammar.lua b/src/nvim/generators/luacats_grammar.lua
new file mode 100644
index 0000000000..dcccd028ce
--- /dev/null
+++ b/src/nvim/generators/luacats_grammar.lua
@@ -0,0 +1,136 @@
+--[[!
+LPEG grammar for LuaCATS
+
+Currently only partially supports:
+- @param
+- @return
+]]
+
+local lpeg = vim.lpeg
+local P, R, S = lpeg.P, lpeg.R, lpeg.S
+local Ct, Cg = lpeg.Ct, lpeg.Cg
+
+--- @param x vim.lpeg.Pattern
+local function rep(x)
+ return x ^ 0
+end
+
+--- @param x vim.lpeg.Pattern
+local function rep1(x)
+ return x ^ 1
+end
+
+--- @param x vim.lpeg.Pattern
+local function opt(x)
+ return x ^ -1
+end
+
+local nl = P('\r\n') + P('\n')
+local ws = rep1(S(' \t') + nl)
+local fill = opt(ws)
+
+local any = P(1) -- (consume one character)
+local letter = R('az', 'AZ') + S('_$')
+local num = R('09')
+local ident = letter * rep(letter + num + S '-.')
+local string_single = P "'" * rep(any - P "'") * P "'"
+local string_double = P '"' * rep(any - P '"') * P '"'
+
+local literal = (string_single + string_double + (opt(P '-') * num) + P 'false' + P 'true')
+
+local lname = (ident + P '...') * opt(P '?')
+
+--- @param x string
+local function Pf(x)
+ return fill * P(x) * fill
+end
+
+--- @param x string
+local function Sf(x)
+ return fill * S(x) * fill
+end
+
+--- @param x vim.lpeg.Pattern
+local function comma(x)
+ return x * rep(Pf ',' * x)
+end
+
+--- @param x vim.lpeg.Pattern
+local function parenOpt(x)
+ return (Pf('(') * x ^ -1 * fill * P(')')) + x ^ -1
+end
+
+--- @type table<string,vim.lpeg.Pattern>
+local v = setmetatable({}, {
+ __index = function(_, k)
+ return lpeg.V(k)
+ end,
+})
+
+local desc_delim = Sf '#:' + ws
+
+--- @class luacats.Param
+--- @field kind 'param'
+--- @field name string
+--- @field type string
+--- @field desc? string
+
+--- @class luacats.Return
+--- @field kind 'return'
+--- @field [integer] { type: string, name?: string}
+--- @field desc? string
+
+--- @class luacats.Generic
+--- @field kind 'generic'
+--- @field name string
+--- @field type? string
+
+--- @alias luacats.grammar.result
+--- | luacats.Param
+--- | luacats.Return
+--- | luacats.Generic
+
+--- @class luacats.grammar
+--- @field match fun(self, input: string): luacats.grammar.result?
+
+local grammar = P {
+ rep1(P('@') * v.ats),
+
+ ats = (v.at_param + v.at_return + v.at_generic),
+
+ at_param = Ct(
+ Cg(P('param'), 'kind')
+ * ws
+ * Cg(lname, 'name')
+ * ws
+ * Cg(v.ltype, 'type')
+ * opt(desc_delim * Cg(rep(any), 'desc'))
+ ),
+
+ at_return = Ct(
+ Cg(P('return'), 'kind')
+ * ws
+ * parenOpt(comma(Ct(Cg(v.ltype, 'type') * opt(ws * Cg(ident, 'name')))))
+ * opt(desc_delim * Cg(rep(any), 'desc'))
+ ),
+
+ at_generic = Ct(
+ Cg(P('generic'), 'kind') * ws * Cg(ident, 'name') * opt(Pf ':' * Cg(v.ltype, 'type'))
+ ),
+
+ ltype = v.ty_union + Pf '(' * v.ty_union * fill * P ')',
+
+ ty_union = v.ty_opt * rep(Pf '|' * v.ty_opt),
+ ty = v.ty_fun + ident + v.ty_table + literal,
+ ty_param = Pf '<' * comma(v.ltype) * fill * P '>',
+ ty_opt = v.ty * opt(v.ty_param) * opt(P '[]') * opt(P '?'),
+
+ table_key = (Pf '[' * literal * Pf ']') + lname,
+ table_elem = v.table_key * Pf ':' * v.ltype,
+ ty_table = Pf '{' * comma(v.table_elem) * Pf '}',
+
+ fun_param = lname * opt(Pf ':' * v.ltype),
+ ty_fun = Pf 'fun(' * rep(comma(v.fun_param)) * fill * P ')' * opt(Pf ':' * v.ltype),
+}
+
+return grammar --[[@as luacats.grammar]]
diff --git a/test/functional/luacats_grammar_spec.lua b/test/functional/luacats_grammar_spec.lua
new file mode 100644
index 0000000000..5671848709
--- /dev/null
+++ b/test/functional/luacats_grammar_spec.lua
@@ -0,0 +1,133 @@
+local helpers = require('test.functional.helpers')(after_each)
+local eq = helpers.eq
+
+local grammar = require('src/nvim/generators/luacats_grammar')
+
+describe('luacats grammar', function()
+ --- @param text string
+ --- @param exp table<string,string>
+ local function test(text, exp)
+ it(string.format('can parse %q', text), function()
+ eq(exp, grammar:match(text))
+ end)
+ end
+
+ test('@param hello vim.type', {
+ kind = 'param',
+ name = 'hello',
+ type = 'vim.type',
+ })
+
+ test('@param hello vim.type this is a description', {
+ kind = 'param',
+ name = 'hello',
+ type = 'vim.type',
+ desc = 'this is a description',
+ })
+
+ test('@param hello vim.type|string this is a description', {
+ kind = 'param',
+ name = 'hello',
+ type = 'vim.type|string',
+ desc = 'this is a description',
+ })
+
+ test('@param hello vim.type?|string? this is a description', {
+ kind = 'param',
+ name = 'hello',
+ type = 'vim.type?|string?',
+ desc = 'this is a description',
+ })
+
+ test('@return string hello this is a description', {
+ kind = 'return',
+ {
+ name = 'hello',
+ type = 'string',
+ },
+ desc = 'this is a description',
+ })
+
+ test('@return fun() hello this is a description', {
+ kind = 'return',
+ {
+ name = 'hello',
+ type = 'fun()',
+ },
+ desc = 'this is a description',
+ })
+
+ test('@return fun(a: string[]): string hello this is a description', {
+ kind = 'return',
+ {
+ name = 'hello',
+ type = 'fun(a: string[]): string',
+ },
+ desc = 'this is a description',
+ })
+
+ test('@return fun(a: table<string,any>): string hello this is a description', {
+ kind = 'return',
+ {
+ name = 'hello',
+ type = 'fun(a: table<string,any>): string',
+ },
+ desc = 'this is a description',
+ })
+
+ test('@param ... string desc', {
+ kind = 'param',
+ name = '...',
+ type = 'string',
+ desc = 'desc',
+ })
+
+ test('@param level (integer|string) desc', {
+ kind = 'param',
+ name = 'level',
+ type = '(integer|string)',
+ desc = 'desc',
+ })
+
+ test('@return (string command) the command and arguments', {
+ kind = 'return',
+ {
+ name = 'command',
+ type = 'string',
+ },
+ desc = 'the command and arguments',
+ })
+
+ test('@return (string command, string[] args) the command and arguments', {
+ kind = 'return',
+ {
+ name = 'command',
+ type = 'string',
+ },
+ {
+ name = 'args',
+ type = 'string[]',
+ },
+ desc = 'the command and arguments',
+ })
+
+ test('@param rfc "rfc2396" | "rfc2732" | "rfc3986" | nil', {
+ kind = 'param',
+ name = 'rfc',
+ type = '"rfc2396" | "rfc2732" | "rfc3986" | nil',
+ })
+
+ test('@param offset_encoding "utf-8" | "utf-16" | "utf-32" | nil', {
+ kind = 'param',
+ name = 'offset_encoding',
+ type = '"utf-8" | "utf-16" | "utf-32" | nil',
+ })
+
+ -- handle a : after the param type
+ test('@param a b: desc', {
+ kind = 'param',
+ name = 'a',
+ type = 'b',
+ desc = 'desc',
+ })
+end)
generated by cgit (git 2.34.1) at 2025-04-28 19:23:25 +0000