From 2f9ee9b6cfc61a0504fc0bc22bdf481828e2ea91 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 9 Jan 2024 17:36:46 +0000 Subject: [PATCH] fix(doc): improve doc generation of types using lpeg Added a lpeg grammar for LuaCATS and use it in lua2dox.lua --- runtime/doc/api.txt | 5 +- runtime/doc/diagnostic.txt | 132 ++-- runtime/doc/lsp.txt | 466 +++++++------- runtime/doc/lua.txt | 759 ++++++++++++----------- runtime/doc/treesitter.txt | 233 ++++--- runtime/lua/vim/_editor.lua | 7 +- runtime/lua/vim/_meta/api.lua | 5 +- runtime/lua/vim/_system.lua | 4 +- runtime/lua/vim/filetype.lua | 4 +- runtime/lua/vim/health.lua | 2 +- runtime/lua/vim/iter.lua | 48 +- runtime/lua/vim/lsp/handlers.lua | 2 +- runtime/lua/vim/lsp/util.lua | 6 +- runtime/lua/vim/shared.lua | 2 +- runtime/lua/vim/treesitter/query.lua | 2 +- scripts/gen_vimdoc.py | 14 +- scripts/lua2dox.lua | 202 +++--- src/nvim/CMakeLists.txt | 2 + src/nvim/generators/luacats_grammar.lua | 136 ++++ test/functional/luacats_grammar_spec.lua | 133 ++++ 20 files changed, 1239 insertions(+), 925 deletions(-) create mode 100644 src/nvim/generators/luacats_grammar.lua create mode 100644 test/functional/luacats_grammar_spec.lua 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/.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 Optional parameters: + • {a} (`string`) First string to compare + • {b} (`string`) Second string to compare + • {opts} (`table`) 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|nil Options table with keys: + • {str} (`string`) Stringified JSON data. + • {opts} (`table?`) 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|nil + • {str} (`string`) Text to convert + • {from} (`number`) Encoding of {str} + • {to} (`number`) Target encoding + • {opts} (`table?`) 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 - • {callback} fun() + • {ns} (`integer`) + • {options} (`table`) + • {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 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, 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, 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, table): pattern id, match, + (`fun(): integer, table, 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 + (`table`) 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 + (`table`) *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 + (`table`) 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 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 +--- @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 +--- @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 +--- @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-') + return '/// ' .. line: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' + -- preprocess line before parsing + if directive == '@param' or directive == '@return' then + for _, type in ipairs(TYPES) do + 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') + + line = line:gsub('^@return%s+.*%((' .. type .. ')%)', '@return %1') + line = line:gsub('^@return%s+.*%((' .. type .. '|nil)%)', '@return %1') end - generics[generic_name] = generic_type + end + + local parsed = luacats_parser:match(line) + + if not parsed then + return '/// ' .. line + end + + local kind = parsed.kind + + 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 - local type_index = 2 - - if directive == 'param' 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 - - -- replace generic types - for k, v in pairs(generics) do - ty = ty:gsub(k, v) --- @type string - end - - for _, type in ipairs(TAGGED_TYPES) do - ty = ty:gsub(type, '|%1|') - end - - for _, type in ipairs(ALIAS_TYPES) do - ty = ty:gsub('^' .. type .. '$', 'table') --- @type string - end - - -- surround some types by () - for _, type in ipairs(TYPES) do - ty = ty:gsub('^(' .. type .. '|nil):?$', '(%1)'):gsub('^(' .. type .. '):?$', '(%1)') - end - - magic_split[type_index] = ty - 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 +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 + 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 hello this is a description', { + kind = 'return', + { + name = 'hello', + type = 'fun(a: table): 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)