commit 76de3e2d07f20c77b7ee6f72c8ec27b045e51ed1
parent 3eaa6c5a665999a9e374338137841937541ec33e
Author: Lewis Russell <lewis6991@gmail.com>
Date: Mon, 16 Jun 2025 11:45:44 +0100
docs(api): document types using LuaCATS types
- Render Lua types in api.txt.
- Added `DictAs(name)` API type which acts the same as `Dict` (no parens)
when generating the dispatchers, but acts the same as `Dict(name)`
when generating docs.
- Added `Tuple(...)` API type which is the treated the as `Array` for
generating the dispatchers, but is used to document richer types.
- Added `Enum(...)` API type to better document enums
- Improve typing of some API functions.
- Improve c_grammar to properly parse API types and replace string pattern
logic in the parsers.
- Removed all the hardcoded type overrides in gen_eval_files.lua
Diffstat:
21 files changed, 929 insertions(+), 783 deletions(-)
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
@@ -569,8 +569,8 @@ nvim_chan_send({chan}, {data}) *nvim_chan_send()*
Since: 0.5.0
Parameters: ~
- • {chan} id of the channel
- • {data} data to write. 8-bit clean: can contain NUL bytes.
+ • {chan} (`integer`) id of the channel
+ • {data} (`string`) data to write. 8-bit clean: can contain NUL bytes.
nvim_create_buf({listed}, {scratch}) *nvim_create_buf()*
Creates a new, empty, unnamed buffer.
@@ -579,13 +579,13 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()*
Since: 0.4.0
Parameters: ~
- • {listed} Sets 'buflisted'
- • {scratch} Creates a "throwaway" |scratch-buffer| for temporary work
- (always 'nomodified'). Also sets 'nomodeline' on the
- buffer.
+ • {listed} (`boolean`) Sets 'buflisted'
+ • {scratch} (`boolean`) Creates a "throwaway" |scratch-buffer| for
+ temporary work (always 'nomodified'). Also sets
+ 'nomodeline' on the buffer.
Return: ~
- Buffer id, or 0 on error
+ (`integer`) Buffer id, or 0 on error
See also: ~
• buf_open_scratch
@@ -605,6 +605,10 @@ nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()*
Attributes: ~
Since: 0.4.0
+ Parameters: ~
+ • {mode} (`string`)
+ • {lhs} (`string`)
+
See also: ~
• |nvim_set_keymap()|
@@ -618,10 +622,10 @@ nvim_del_mark({name}) *nvim_del_mark()*
Since: 0.6.0
Parameters: ~
- • {name} Mark name
+ • {name} (`string`) Mark name
Return: ~
- true if the mark was deleted, else false.
+ (`boolean`) true if the mark was deleted, else false.
See also: ~
• |nvim_buf_del_mark()|
@@ -634,7 +638,7 @@ nvim_del_var({name}) *nvim_del_var()*
Since: 0.1.0
Parameters: ~
- • {name} Variable name
+ • {name} (`string`) Variable name
nvim_echo({chunks}, {history}, {opts}) *nvim_echo()*
Prints a message given by a list of `[text, hl_group]` "chunks".
@@ -647,10 +651,11 @@ nvim_echo({chunks}, {history}, {opts}) *nvim_echo()*
Since: 0.5.0
Parameters: ~
- • {chunks} List of `[text, hl_group]` pairs, where each is a `text`
- string highlighted by the (optional) name or ID `hl_group`.
- • {history} if true, add to |message-history|.
- • {opts} Optional parameters.
+ • {chunks} (`[string, integer|string][]`) List of `[text, hl_group]`
+ pairs, where each is a `text` string highlighted by the
+ (optional) name or ID `hl_group`.
+ • {history} (`boolean`) if true, add to |message-history|.
+ • {opts} (`vim.api.keyset.echo_opts`) Optional parameters.
• err: Treat the message like `:echoerr`. Sets `hl_group`
to |hl-ErrorMsg| by default.
• kind: Set the |ui-messages| kind with which this message
@@ -667,8 +672,8 @@ nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()*
Since: 0.6.0
Parameters: ~
- • {str} Statusline string (see 'statusline').
- • {opts} Optional parameters.
+ • {str} (`string`) Statusline string (see 'statusline').
+ • {opts} (`vim.api.keyset.eval_statusline`) Optional parameters.
• winid: (number) |window-ID| of the window to use as context
for statusline.
• maxwidth: (number) Maximum width of statusline.
@@ -684,7 +689,8 @@ nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()*
line number instead of statusline.
Return: ~
- Dict containing statusline information, with these keys:
+ (`vim.api.keyset.eval_statusline_ret`) Dict containing statusline
+ information, with these keys:
• str: (string) Characters that will be displayed on the statusline.
• width: (number) Display width of the statusline.
• highlights: Array containing highlight information of the
@@ -708,11 +714,11 @@ nvim_exec_lua({code}, {args}) *nvim_exec_lua()*
Since: 0.5.0
Parameters: ~
- • {code} Lua code to execute
- • {args} Arguments to the code
+ • {code} (`string`) Lua code to execute
+ • {args} (`any[]`) Arguments to the code
Return: ~
- Return value of Lua code if present or NIL.
+ (`any`) Return value of Lua code if present or NIL.
nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()*
Sends input-keys to Nvim, subject to various quirks controlled by `mode`
@@ -733,11 +739,11 @@ nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()*
Since: 0.1.0
Parameters: ~
- • {keys} to be typed
- • {mode} behavior flags, see |feedkeys()|
- • {escape_ks} If true, escape K_SPECIAL bytes in `keys`. This should be
- false if you already used |nvim_replace_termcodes()|, and
- true otherwise.
+ • {keys} (`string`) to be typed
+ • {mode} (`string`) behavior flags, see |feedkeys()|
+ • {escape_ks} (`boolean`) If true, escape K_SPECIAL bytes in `keys`.
+ This should be false if you already used
+ |nvim_replace_termcodes()|, and true otherwise.
See also: ~
• feedkeys()
@@ -753,7 +759,7 @@ nvim_get_api_info() *nvim_get_api_info()*
Since: 0.1.0
Return: ~
- 2-tuple `[{channel-id}, {api-metadata}]`
+ (`[any, any]`) 2-tuple `[{channel-id}, {api-metadata}]`
nvim_get_chan_info({chan}) *nvim_get_chan_info()*
Gets information about a channel.
@@ -764,10 +770,10 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()*
Since: 0.3.0
Parameters: ~
- • {chan} channel_id, or 0 for current channel
+ • {chan} (`integer`) channel_id, or 0 for current channel
Return: ~
- Channel info dict with these keys:
+ (`table<string,any>`) Channel info dict with these keys:
• "id" Channel id.
• "argv" (optional) Job arguments list.
• "stream" Stream underlying the channel.
@@ -799,10 +805,10 @@ nvim_get_color_by_name({name}) *nvim_get_color_by_name()*
Since: 0.1.0
Parameters: ~
- • {name} Color name or "#rrggbb" string
+ • {name} (`string`) Color name or "#rrggbb" string
Return: ~
- 24-bit RGB value, or -1 for invalid argument.
+ (`integer`) 24-bit RGB value, or -1 for invalid argument.
nvim_get_color_map() *nvim_get_color_map()*
Returns a map of color names and RGB values.
@@ -814,7 +820,7 @@ nvim_get_color_map() *nvim_get_color_map()*
Since: 0.1.0
Return: ~
- Map of color names and RGB values.
+ (`table<string,integer>`) Map of color names and RGB values.
nvim_get_context({opts}) *nvim_get_context()*
Gets a map of the current editor state.
@@ -823,12 +829,12 @@ nvim_get_context({opts}) *nvim_get_context()*
Since: 0.4.0
Parameters: ~
- • {opts} Optional parameters.
+ • {opts} (`vim.api.keyset.context`) Optional parameters.
• types: List of |context-types| ("regs", "jumps", "bufs",
"gvars", …) to gather, or empty for "all".
Return: ~
- map of global |context|.
+ (`table<string,any>`) map of global |context|.
nvim_get_current_buf() *nvim_get_current_buf()*
Gets the current buffer.
@@ -837,7 +843,7 @@ nvim_get_current_buf() *nvim_get_current_buf()*
Since: 0.1.0
Return: ~
- Buffer id
+ (`integer`) Buffer id
nvim_get_current_line() *nvim_get_current_line()*
Gets the current line.
@@ -846,7 +852,7 @@ nvim_get_current_line() *nvim_get_current_line()*
Since: 0.1.0
Return: ~
- Current line string
+ (`string`) Current line string
nvim_get_current_tabpage() *nvim_get_current_tabpage()*
Gets the current tabpage.
@@ -855,7 +861,7 @@ nvim_get_current_tabpage() *nvim_get_current_tabpage()*
Since: 0.1.0
Return: ~
- |tab-ID|
+ (`integer`) |tab-ID|
nvim_get_current_win() *nvim_get_current_win()*
Gets the current window.
@@ -864,7 +870,7 @@ nvim_get_current_win() *nvim_get_current_win()*
Since: 0.1.0
Return: ~
- |window-ID|
+ (`integer`) |window-ID|
nvim_get_hl({ns_id}, {opts}) *nvim_get_hl()*
Gets all or specific highlight groups in a namespace.
@@ -877,10 +883,10 @@ nvim_get_hl({ns_id}, {opts}) *nvim_get_hl()*
Since: 0.9.0
Parameters: ~
- • {ns_id} Get highlight groups for namespace ns_id
+ • {ns_id} (`integer`) Get highlight groups for namespace ns_id
|nvim_get_namespaces()|. Use 0 to get global highlight groups
|:highlight|.
- • {opts} Options dict:
+ • {opts} (`vim.api.keyset.get_highlight`) Options dict:
• name: (string) Get a highlight definition by name.
• id: (integer) Get a highlight definition by id.
• link: (boolean, default true) Show linked group name
@@ -889,9 +895,9 @@ nvim_get_hl({ns_id}, {opts}) *nvim_get_hl()*
doesn't exist create it.
Return: ~
- Highlight groups as a map from group name to a highlight definition
- map as in |nvim_set_hl()|, or only a single highlight definition map
- if requested by name or id.
+ (`vim.api.keyset.get_hl_info`) Highlight groups as a map from group
+ name to a highlight definition map as in |nvim_set_hl()|, or only a
+ single highlight definition map if requested by name or id.
nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()*
Gets a highlight group by name
@@ -901,6 +907,12 @@ nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()*
Attributes: ~
Since: 0.5.0
+ Parameters: ~
+ • {name} (`string`)
+
+ Return: ~
+ (`integer`)
+
nvim_get_hl_ns({opts}) *nvim_get_hl_ns()*
Gets the active highlight namespace.
@@ -908,14 +920,14 @@ nvim_get_hl_ns({opts}) *nvim_get_hl_ns()*
Since: 0.10.0
Parameters: ~
- • {opts} Optional parameters
+ • {opts} (`vim.api.keyset.get_ns`) Optional parameters
• winid: (number) |window-ID| for retrieving a window's
highlight namespace. A value of -1 is returned when
|nvim_win_set_hl_ns()| has not been called for the window
(or was called with a namespace of -1).
Return: ~
- Namespace id, or -1
+ (`integer`) Namespace id, or -1
nvim_get_keymap({mode}) *nvim_get_keymap()*
Gets a list of global (non-buffer-local) |mapping| definitions.
@@ -924,11 +936,11 @@ nvim_get_keymap({mode}) *nvim_get_keymap()*
Since: 0.2.1
Parameters: ~
- • {mode} Mode short-name ("n", "i", "v", ...)
+ • {mode} (`string`) Mode short-name ("n", "i", "v", ...)
Return: ~
- Array of |maparg()|-like dictionaries describing mappings. The
- "buffer" key is always zero.
+ (`vim.api.keyset.get_keymap[]`) Array of |maparg()|-like dictionaries
+ describing mappings. The "buffer" key is always zero.
nvim_get_mark({name}, {opts}) *nvim_get_mark()*
Returns a `(row, col, buffer, buffername)` tuple representing the position
@@ -944,12 +956,13 @@ nvim_get_mark({name}, {opts}) *nvim_get_mark()*
Since: 0.6.0
Parameters: ~
- • {name} Mark name
- • {opts} Optional parameters. Reserved for future use.
+ • {name} (`string`) Mark name
+ • {opts} (`vim.api.keyset.empty`) Optional parameters. Reserved for
+ future use.
Return: ~
- 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is
- not set.
+ (`[integer, integer, integer, string]`) 4-tuple (row, col, buffer,
+ buffername), (0, 0, 0, '') if the mark is not set.
See also: ~
• |nvim_buf_set_mark()|
@@ -964,7 +977,8 @@ nvim_get_mode() *nvim_get_mode()*
Since: 0.2.0
Return: ~
- Dict { "mode": String, "blocking": Boolean }
+ (`vim.api.keyset.get_mode`) Dict { "mode": String, "blocking": Boolean
+ }
nvim_get_proc({pid}) *nvim_get_proc()*
Gets info describing process `pid`.
@@ -972,8 +986,11 @@ nvim_get_proc({pid}) *nvim_get_proc()*
Attributes: ~
Since: 0.3.0
+ Parameters: ~
+ • {pid} (`integer`)
+
Return: ~
- Map of process properties, or NIL if process not found.
+ (`any`) Map of process properties, or NIL if process not found.
nvim_get_proc_children({pid}) *nvim_get_proc_children()*
Gets the immediate children of process `pid`.
@@ -981,8 +998,11 @@ nvim_get_proc_children({pid}) *nvim_get_proc_children()*
Attributes: ~
Since: 0.3.0
+ Parameters: ~
+ • {pid} (`integer`)
+
Return: ~
- Array of child process ids, empty if process not found.
+ (`any[]`) Array of child process ids, empty if process not found.
nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()*
Finds files in runtime directories, in 'runtimepath' order.
@@ -999,11 +1019,11 @@ nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()*
Since: 0.5.0
Parameters: ~
- • {name} pattern of files to search for
- • {all} whether to return all matches or only the first
+ • {name} (`string`) pattern of files to search for
+ • {all} (`boolean`) whether to return all matches or only the first
Return: ~
- list of absolute paths to the found files
+ (`string[]`) list of absolute paths to the found files
nvim_get_var({name}) *nvim_get_var()*
Gets a global (g:) variable.
@@ -1012,10 +1032,10 @@ nvim_get_var({name}) *nvim_get_var()*
Since: 0.1.0
Parameters: ~
- • {name} Variable name
+ • {name} (`string`) Variable name
Return: ~
- Variable value
+ (`any`) Variable value
nvim_get_vvar({name}) *nvim_get_vvar()*
Gets a v: variable.
@@ -1024,10 +1044,10 @@ nvim_get_vvar({name}) *nvim_get_vvar()*
Since: 0.1.0
Parameters: ~
- • {name} Variable name
+ • {name} (`string`) Variable name
Return: ~
- Variable value
+ (`any`) Variable value
nvim_input({keys}) *nvim_input()*
Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a low-level
@@ -1050,11 +1070,11 @@ nvim_input({keys}) *nvim_input()*
Since: 0.1.0
Parameters: ~
- • {keys} to be typed
+ • {keys} (`string`) to be typed
Return: ~
- Number of bytes actually written (can be fewer than requested if the
- buffer becomes full).
+ (`integer`) Number of bytes actually written (can be fewer than
+ requested if the buffer becomes full).
*nvim_input_mouse()*
nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
@@ -1075,18 +1095,22 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
Since: 0.4.0
Parameters: ~
- • {button} Mouse button: one of "left", "right", "middle", "wheel",
- "move", "x1", "x2".
- • {action} For ordinary buttons, one of "press", "drag", "release".
- For the wheel, one of "up", "down", "left", "right".
- Ignored for "move".
- • {modifier} String of modifiers each represented by a single char. The
- same specifiers are used as for a key press, except that
- the "-" separator is optional, so "C-A-", "c-a" and "CA"
- can all be used to specify Ctrl+Alt+click.
- • {grid} Grid number if the client uses |ui-multigrid|, else 0.
- • {row} Mouse row-position (zero-based, like redraw events)
- • {col} Mouse column-position (zero-based, like redraw events)
+ • {button} (`string`) Mouse button: one of "left", "right", "middle",
+ "wheel", "move", "x1", "x2".
+ • {action} (`string`) For ordinary buttons, one of "press", "drag",
+ "release". For the wheel, one of "up", "down", "left",
+ "right". Ignored for "move".
+ • {modifier} (`string`) String of modifiers each represented by a
+ single char. The same specifiers are used as for a key
+ press, except that the "-" separator is optional, so
+ "C-A-", "c-a" and "CA" can all be used to specify
+ Ctrl+Alt+click.
+ • {grid} (`integer`) Grid number if the client uses |ui-multigrid|,
+ else 0.
+ • {row} (`integer`) Mouse row-position (zero-based, like redraw
+ events)
+ • {col} (`integer`) Mouse column-position (zero-based, like redraw
+ events)
nvim_list_bufs() *nvim_list_bufs()*
Gets the current list of buffers.
@@ -1098,7 +1122,7 @@ nvim_list_bufs() *nvim_list_bufs()*
Since: 0.1.0
Return: ~
- List of buffer ids
+ (`integer[]`) List of buffer ids
nvim_list_chans() *nvim_list_chans()*
Get information about all open channels.
@@ -1107,8 +1131,8 @@ nvim_list_chans() *nvim_list_chans()*
Since: 0.3.0
Return: ~
- Array of Dictionaries, each describing a channel with the format
- specified at |nvim_get_chan_info()|.
+ (`table<string,any>[]`) Array of Dictionaries, each describing a
+ channel with the format specified at |nvim_get_chan_info()|.
nvim_list_runtime_paths() *nvim_list_runtime_paths()*
Gets the paths contained in |runtime-search-path|.
@@ -1117,7 +1141,7 @@ nvim_list_runtime_paths() *nvim_list_runtime_paths()*
Since: 0.1.0
Return: ~
- List of paths
+ (`string[]`) List of paths
nvim_list_tabpages() *nvim_list_tabpages()*
Gets the current list of |tab-ID|s.
@@ -1126,7 +1150,7 @@ nvim_list_tabpages() *nvim_list_tabpages()*
Since: 0.1.0
Return: ~
- List of |tab-ID|s
+ (`integer[]`) List of |tab-ID|s
nvim_list_uis() *nvim_list_uis()*
Gets a list of dictionaries representing attached UIs.
@@ -1141,7 +1165,8 @@ nvim_list_uis() *nvim_list_uis()*
Since: 0.3.0
Return: ~
- Array of UI dictionaries, each with these keys:
+ (`table<string,any>[]`) Array of UI dictionaries, each with these
+ keys:
• "height" Requested height of the UI
• "width" Requested width of the UI
• "rgb" true if the UI uses RGB colors (false implies |cterm-colors|)
@@ -1155,7 +1180,7 @@ nvim_list_wins() *nvim_list_wins()*
Since: 0.1.0
Return: ~
- List of |window-ID|s
+ (`integer[]`) List of |window-ID|s
nvim_load_context({dict}) *nvim_load_context()*
Sets the current editor state from the given |context| map.
@@ -1164,7 +1189,10 @@ nvim_load_context({dict}) *nvim_load_context()*
Since: 0.4.0
Parameters: ~
- • {dict} |Context| map.
+ • {dict} (`table<string,any>`) |Context| map.
+
+ Return: ~
+ (`any`)
nvim_open_term({buffer}, {opts}) *nvim_open_term()*
Open a terminal instance in a buffer
@@ -1194,9 +1222,9 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()*
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer to use. Buffer contents (if any) will be written to
- the PTY.
- • {opts} Optional parameters.
+ • {buffer} (`integer`) Buffer to use. Buffer contents (if any) will be
+ written to the PTY.
+ • {opts} (`vim.api.keyset.open_term`) Optional parameters.
• on_input: Lua callback for input sent, i e keypresses in
terminal mode. Note: keypresses are sent raw as they would
be to the pty master end. For instance, a carriage return
@@ -1207,7 +1235,7 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()*
"\r\n".
Return: ~
- Channel id, or 0 on error
+ (`integer`) Channel id, or 0 on error
nvim_paste({data}, {crlf}, {phase}) *nvim_paste()*
Pastes at cursor (in any mode), and sets "redo" so dot (|.|) will repeat
@@ -1238,17 +1266,18 @@ nvim_paste({data}, {crlf}, {phase}) *nvim_paste()*
Since: 0.4.0
Parameters: ~
- • {data} Multiline input. Lines break at LF ("\n"). May be binary
- (containing NUL bytes).
- • {crlf} Also break lines at CR and CRLF.
- • {phase} -1: paste in a single call (i.e. without streaming). To
- "stream" a paste, call `nvim_paste` sequentially with these
- `phase` values:
+ • {data} (`string`) Multiline input. Lines break at LF ("\n"). May be
+ binary (containing NUL bytes).
+ • {crlf} (`boolean`) Also break lines at CR and CRLF.
+ • {phase} (`integer`) -1: paste in a single call (i.e. without
+ streaming). To "stream" a paste, call `nvim_paste`
+ sequentially with these `phase` values:
• 1: starts the paste (exactly once)
• 2: continues the paste (zero or more times)
• 3: ends the paste (exactly once)
Return: ~
+ (`boolean`)
• true: Client may continue pasting.
• false: Client should cancel the paste.
@@ -1263,15 +1292,16 @@ nvim_put({lines}, {type}, {after}, {follow}) *nvim_put()*
Since: 0.4.0
Parameters: ~
- • {lines} |readfile()|-style list of lines. |channel-lines|
- • {type} Edit behavior: any |getregtype()| result, or:
+ • {lines} (`string[]`) |readfile()|-style list of lines.
+ |channel-lines|
+ • {type} (`string`) Edit behavior: any |getregtype()| result, or:
• "b" |blockwise-visual| mode (may include width, e.g. "b3")
• "c" |charwise| mode
• "l" |linewise| mode
• "" guess by contents, see |setreg()|
- • {after} If true insert after cursor (like |p|), or before (like
- |P|).
- • {follow} If true place cursor at end of inserted text.
+ • {after} (`boolean`) If true insert after cursor (like |p|), or
+ before (like |P|).
+ • {follow} (`boolean`) If true place cursor at end of inserted text.
*nvim_replace_termcodes()*
nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
@@ -1282,10 +1312,15 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
Since: 0.1.0
Parameters: ~
- • {str} String to be converted.
- • {from_part} Legacy Vim parameter. Usually true.
- • {do_lt} Also translate <lt>. Ignored if `special` is false.
- • {special} Replace |keycodes|, e.g. <CR> becomes a "\r" char.
+ • {str} (`string`) String to be converted.
+ • {from_part} (`boolean`) Legacy Vim parameter. Usually true.
+ • {do_lt} (`boolean`) Also translate <lt>. Ignored if `special` is
+ false.
+ • {special} (`boolean`) Replace |keycodes|, e.g. <CR> becomes a "\r"
+ char.
+
+ Return: ~
+ (`string`)
See also: ~
• replace_termcodes
@@ -1305,13 +1340,15 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
Since: 0.4.0
Parameters: ~
- • {item} Index (zero-based) of the item to select. Value of -1
- selects nothing and restores the original text.
- • {insert} For |ins-completion|, whether the selection should be
- inserted in the buffer. Ignored for |cmdline-completion|.
- • {finish} Finish the completion and dismiss the popup menu. Implies
- {insert}.
- • {opts} Optional parameters. Reserved for future use.
+ • {item} (`integer`) Index (zero-based) of the item to select. Value
+ of -1 selects nothing and restores the original text.
+ • {insert} (`boolean`) For |ins-completion|, whether the selection
+ should be inserted in the buffer. Ignored for
+ |cmdline-completion|.
+ • {finish} (`boolean`) Finish the completion and dismiss the popup
+ menu. Implies {insert}.
+ • {opts} (`vim.api.keyset.empty`) Optional parameters. Reserved for
+ future use.
*nvim_set_client_info()*
nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
@@ -1331,9 +1368,10 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
Since: 0.3.0
Parameters: ~
- • {name} Client short-name. Sets the `client.name` field of
- |nvim_get_chan_info()|.
- • {version} Dict describing the version, with these (optional) keys:
+ • {name} (`string`) Client short-name. Sets the `client.name`
+ field of |nvim_get_chan_info()|.
+ • {version} (`table<string,any>`) Dict describing the version, with
+ these (optional) keys:
• "major" major version (defaults to 0 if not set, for
no release yet)
• "minor" minor version
@@ -1341,9 +1379,9 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
• "prerelease" string describing a prerelease, like
"dev" or "beta1"
• "commit" hash or similar identifier of commit
- • {type} Must be one of the following values. Client libraries
- should default to "remote" unless overridden by the
- user.
+ • {type} (`string`) Must be one of the following values. Client
+ libraries should default to "remote" unless overridden
+ by the user.
• "remote" remote client connected "Nvim flavored"
MessagePack-RPC (responses must be in reverse order of
requests). |msgpack-rpc|
@@ -1354,20 +1392,20 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
example, IDE/editor implementing a vim mode).
• "host" plugin host, typically started by nvim
• "plugin" single plugin, started by nvim
- • {methods} Builtin methods in the client. For a host, this does not
- include plugin methods which will be discovered later.
- The key should be the method name, the values are dicts
- with these (optional) keys (more keys may be added in
- future versions of Nvim, thus unknown keys are ignored.
- Clients must only use keys defined in this or later
- versions of Nvim):
+ • {methods} (`table<string,any>`) Builtin methods in the client. For
+ a host, this does not include plugin methods which will
+ be discovered later. The key should be the method name,
+ the values are dicts with these (optional) keys (more
+ keys may be added in future versions of Nvim, thus
+ unknown keys are ignored. Clients must only use keys
+ defined in this or later versions of Nvim):
• "async" if true, send as a notification. If false or
unspecified, use a blocking request
• "nargs" Number of arguments. Could be a single integer
or an array of two integers, minimum and maximum
inclusive.
- • {attributes} Arbitrary string:string map of informal client
- properties. Suggested keys:
+ • {attributes} (`table<string,any>`) Arbitrary string:string map of
+ informal client properties. Suggested keys:
• "pid": Process id.
• "website": Client homepage URL (e.g. GitHub
repository)
@@ -1384,7 +1422,7 @@ nvim_set_current_buf({buffer}) *nvim_set_current_buf()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id
+ • {buffer} (`integer`) Buffer id
nvim_set_current_dir({dir}) *nvim_set_current_dir()*
Changes the global working directory.
@@ -1393,7 +1431,7 @@ nvim_set_current_dir({dir}) *nvim_set_current_dir()*
Since: 0.1.0
Parameters: ~
- • {dir} Directory path
+ • {dir} (`string`) Directory path
nvim_set_current_line({line}) *nvim_set_current_line()*
Sets the text on the current line.
@@ -1403,7 +1441,7 @@ nvim_set_current_line({line}) *nvim_set_current_line()*
Since: 0.1.0
Parameters: ~
- • {line} Line contents
+ • {line} (`string`) Line contents
nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()*
Sets the current tabpage.
@@ -1413,7 +1451,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()*
Since: 0.1.0
Parameters: ~
- • {tabpage} |tab-ID| to focus
+ • {tabpage} (`integer`) |tab-ID| to focus
nvim_set_current_win({window}) *nvim_set_current_win()*
Sets the current window (and tabpage, implicitly).
@@ -1423,7 +1461,7 @@ nvim_set_current_win({window}) *nvim_set_current_win()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID| to focus
+ • {window} (`integer`) |window-ID| to focus
nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()*
Sets a highlight group.
@@ -1444,13 +1482,14 @@ nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()*
Since: 0.5.0
Parameters: ~
- • {ns_id} Namespace id for this highlight |nvim_create_namespace()|.
- Use 0 to set a highlight group globally |:highlight|.
- Highlights from non-global namespaces are not active by
- default, use |nvim_set_hl_ns()| or |nvim_win_set_hl_ns()| to
- activate them.
- • {name} Highlight group name, e.g. "ErrorMsg"
- • {val} Highlight definition map, accepts the following keys:
+ • {ns_id} (`integer`) Namespace id for this highlight
+ |nvim_create_namespace()|. Use 0 to set a highlight group
+ globally |:highlight|. Highlights from non-global namespaces
+ are not active by default, use |nvim_set_hl_ns()| or
+ |nvim_win_set_hl_ns()| to activate them.
+ • {name} (`string`) Highlight group name, e.g. "ErrorMsg"
+ • {val} (`vim.api.keyset.highlight`) Highlight definition map,
+ accepts the following keys:
• fg: color name or "#RRGGBB", see note.
• bg: color name or "#RRGGBB", see note.
• sp: color name or "#RRGGBB"
@@ -1485,7 +1524,7 @@ nvim_set_hl_ns({ns_id}) *nvim_set_hl_ns()*
Since: 0.8.0
Parameters: ~
- • {ns_id} the namespace to use
+ • {ns_id} (`integer`) the namespace to use
nvim_set_hl_ns_fast({ns_id}) *nvim_set_hl_ns_fast()*
Set active namespace for highlights defined with |nvim_set_hl()| while
@@ -1500,7 +1539,7 @@ nvim_set_hl_ns_fast({ns_id}) *nvim_set_hl_ns_fast()*
Since: 0.8.0
Parameters: ~
- • {ns_id} the namespace to activate
+ • {ns_id} (`integer`) the namespace to activate
nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()*
Sets a global |mapping| for the given mode.
@@ -1522,14 +1561,15 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()*
Since: 0.4.0
Parameters: ~
- • {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …)
- or "!" for |:map!|, or empty string for |:map|. "ia", "ca" or
- "!a" for abbreviation in Insert mode, Cmdline mode, or both,
- respectively
- • {lhs} Left-hand-side |{lhs}| of the mapping.
- • {rhs} Right-hand-side |{rhs}| of the mapping.
- • {opts} Optional parameters map: Accepts all |:map-arguments| as keys
- except <buffer>, values are booleans (default false). Also:
+ • {mode} (`string`) Mode short-name (map command prefix: "n", "i", "v",
+ "x", …) or "!" for |:map!|, or empty string for |:map|.
+ "ia", "ca" or "!a" for abbreviation in Insert mode, Cmdline
+ mode, or both, respectively
+ • {lhs} (`string`) Left-hand-side |{lhs}| of the mapping.
+ • {rhs} (`string`) Right-hand-side |{rhs}| of the mapping.
+ • {opts} (`vim.api.keyset.keymap`) Optional parameters map: Accepts all
+ |:map-arguments| as keys except <buffer>, values are booleans
+ (default false). Also:
• "noremap" disables |recursive_mapping|, like |:noremap|
• "desc" human-readable description.
• "callback" Lua function called in place of {rhs}.
@@ -1545,8 +1585,8 @@ nvim_set_var({name}, {value}) *nvim_set_var()*
Since: 0.1.0
Parameters: ~
- • {name} Variable name
- • {value} Variable value
+ • {name} (`string`) Variable name
+ • {value} (`any`) Variable value
nvim_set_vvar({name}, {value}) *nvim_set_vvar()*
Sets a v: variable, if it is not readonly.
@@ -1555,8 +1595,8 @@ nvim_set_vvar({name}, {value}) *nvim_set_vvar()*
Since: 0.4.0
Parameters: ~
- • {name} Variable name
- • {value} Variable value
+ • {name} (`string`) Variable name
+ • {value} (`any`) Variable value
nvim_strwidth({text}) *nvim_strwidth()*
Calculates the number of display cells occupied by `text`. Control
@@ -1566,10 +1606,10 @@ nvim_strwidth({text}) *nvim_strwidth()*
Since: 0.1.0
Parameters: ~
- • {text} Some text
+ • {text} (`string`) Some text
Return: ~
- Number of cells
+ (`integer`) Number of cells
nvim__complete_set({index}, {opts}) *nvim__complete_set()*
EXPERIMENTAL: this API may change in the future.
@@ -1579,12 +1619,12 @@ nvim__complete_set({index}, {opts}) *nvim__complete_set()*
shown.
Parameters: ~
- • {index} Completion candidate index
- • {opts} Optional parameters.
+ • {index} (`integer`) Completion candidate index
+ • {opts} (`vim.api.keyset.complete_set`) Optional parameters.
• info: (string) info text.
Return: ~
- Dict containing these keys:
+ (`table<string,number>`) Dict containing these keys:
• winid: (number) floating window id
• bufnr: (number) buffer id in floating window
@@ -1596,12 +1636,12 @@ nvim__get_runtime({pat}, {all}, {opts}) *nvim__get_runtime()*
Since: 0.6.0
Parameters: ~
- • {pat} pattern of files to search for
- • {all} whether to return all matches or only the first
- • {opts} is_lua: only search Lua subdirs
+ • {pat} (`string[]`) pattern of files to search for
+ • {all} (`boolean`) whether to return all matches or only the first
+ • {opts} (`vim.api.keyset.runtime`) is_lua: only search Lua subdirs
Return: ~
- list of absolute paths to the found files
+ (`string[]`) list of absolute paths to the found files
nvim__id({obj}) *nvim__id()*
Returns object given as argument.
@@ -1610,10 +1650,10 @@ nvim__id({obj}) *nvim__id()*
in plugins.
Parameters: ~
- • {obj} Object to return.
+ • {obj} (`any`) Object to return.
Return: ~
- its argument.
+ (`any`) its argument.
nvim__id_array({arr}) *nvim__id_array()*
Returns array given as argument.
@@ -1622,10 +1662,10 @@ nvim__id_array({arr}) *nvim__id_array()*
in plugins.
Parameters: ~
- • {arr} Array to return.
+ • {arr} (`any[]`) Array to return.
Return: ~
- its argument.
+ (`any[]`) its argument.
nvim__id_dict({dct}) *nvim__id_dict()*
Returns dict given as argument.
@@ -1634,10 +1674,10 @@ nvim__id_dict({dct}) *nvim__id_dict()*
in plugins.
Parameters: ~
- • {dct} Dict to return.
+ • {dct} (`table<string,any>`) Dict to return.
Return: ~
- its argument.
+ (`table<string,any>`) its argument.
nvim__id_float({flt}) *nvim__id_float()*
Returns floating-point value given as argument.
@@ -1646,15 +1686,23 @@ nvim__id_float({flt}) *nvim__id_float()*
in plugins.
Parameters: ~
- • {flt} Value to return.
+ • {flt} (`number`) Value to return.
Return: ~
- its argument.
+ (`number`) its argument.
nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()*
NB: if your UI doesn't use hlstate, this will not return hlstate first
time.
+ Parameters: ~
+ • {grid} (`integer`)
+ • {row} (`integer`)
+ • {col} (`integer`)
+
+ Return: ~
+ (`any[]`)
+
nvim__invalidate_glyph_cache() *nvim__invalidate_glyph_cache()*
For testing. The condition in schar_cache_clear_if_full is hard to reach,
so this function can be used to force a cache clear in a test.
@@ -1668,7 +1716,7 @@ nvim__redraw({opts}) *nvim__redraw()*
Since: 0.10.0
Parameters: ~
- • {opts} Optional parameters.
+ • {opts} (`vim.api.keyset.redraw`) Optional parameters.
• win: Target a specific |window-ID| as described below.
• buf: Target a specific buffer number as described below.
• flush: Update the screen with pending updates.
@@ -1695,7 +1743,7 @@ nvim__stats() *nvim__stats()*
Gets internal stats.
Return: ~
- Map of various internal stats.
+ (`table<string,any>`) Map of various internal stats.
==============================================================================
@@ -1711,12 +1759,12 @@ nvim_call_dict_function({dict}, {fn}, {args})
Since: 0.3.0
Parameters: ~
- • {dict} Dict, or String evaluating to a Vimscript |self| dict
- • {fn} Name of the function defined on the Vimscript dict
- • {args} Function arguments packed in an Array
+ • {dict} (`any`) Dict, or String evaluating to a Vimscript |self| dict
+ • {fn} (`string`) Name of the function defined on the Vimscript dict
+ • {args} (`any[]`) Function arguments packed in an Array
Return: ~
- Result of the function call
+ (`any`) Result of the function call
nvim_call_function({fn}, {args}) *nvim_call_function()*
Calls a Vimscript function with the given arguments.
@@ -1727,11 +1775,11 @@ nvim_call_function({fn}, {args}) *nvim_call_function()*
Since: 0.1.0
Parameters: ~
- • {fn} Function to call
- • {args} Function arguments packed in an Array
+ • {fn} (`string`) Function to call
+ • {args} (`any[]`) Function arguments packed in an Array
Return: ~
- Result of the function call
+ (`any`) Result of the function call
nvim_command({command}) *nvim_command()*
Executes an Ex command.
@@ -1746,7 +1794,7 @@ nvim_command({command}) *nvim_command()*
Since: 0.1.0
Parameters: ~
- • {command} Ex command string
+ • {command} (`string`) Ex command string
nvim_eval({expr}) *nvim_eval()*
Evaluates a Vimscript |expression|. Dicts and Lists are recursively
@@ -1758,10 +1806,10 @@ nvim_eval({expr}) *nvim_eval()*
Since: 0.1.0
Parameters: ~
- • {expr} Vimscript expression string
+ • {expr} (`string`) Vimscript expression string
Return: ~
- Evaluation result or expanded object
+ (`any`) Evaluation result or expanded object
nvim_exec2({src}, {opts}) *nvim_exec2()*
Executes Vimscript (multiline block of Ex commands), like anonymous
@@ -1776,13 +1824,14 @@ nvim_exec2({src}, {opts}) *nvim_exec2()*
Since: 0.9.0
Parameters: ~
- • {src} Vimscript code
- • {opts} Optional parameters.
+ • {src} (`string`) Vimscript code
+ • {opts} (`vim.api.keyset.exec_opts`) Optional parameters.
• output: (boolean, default false) Whether to capture and
return all (non-error, non-shell |:!|) output.
Return: ~
- Dict containing information about execution, with these keys:
+ (`table<string,any>`) Dict containing information about execution,
+ with these keys:
• output: (string|nil) Output if `opts.output` is true.
See also: ~
@@ -1799,8 +1848,9 @@ nvim_parse_expression({expr}, {flags}, {highlight})
Since: 0.3.0
Parameters: ~
- • {expr} Expression to parse. Always treated as a single line.
- • {flags} Flags:
+ • {expr} (`string`) Expression to parse. Always treated as a
+ single line.
+ • {flags} (`string`) Flags:
• "m" if multiple expressions in a row are allowed (only
the first one will be parsed),
• "E" if EOC tokens are not allowed (determines whether
@@ -1812,14 +1862,15 @@ nvim_parse_expression({expr}, {flags}, {highlight})
• "E" to parse like for `"<C-r>="`.
• empty string for ":call".
• "lm" to parse for ":let".
- • {highlight} If true, return value will also include "highlight" key
- containing array of 4-tuples (arrays) (Integer, Integer,
- Integer, String), where first three numbers define the
- highlighted region and represent line, starting column
- and ending column (latter exclusive: one should highlight
- region [start_col, end_col)).
+ • {highlight} (`boolean`) If true, return value will also include
+ "highlight" key containing array of 4-tuples (arrays)
+ (Integer, Integer, Integer, String), where first three
+ numbers define the highlighted region and represent line,
+ starting column and ending column (latter exclusive: one
+ should highlight region [start_col, end_col)).
Return: ~
+ (`table<string,any>`)
• AST: top-level dict with these keys:
• "error": Dict with error, present only if parser saw some error.
Contains the following keys:
@@ -1880,7 +1931,10 @@ nvim_buf_create_user_command({buffer}, {name}, {command}, {opts})
Since: 0.7.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer.
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer.
+ • {name} (`string`)
+ • {command} (`any`)
+ • {opts} (`vim.api.keyset.user_command`)
See also: ~
• nvim_create_user_command
@@ -1896,8 +1950,8 @@ nvim_buf_del_user_command({buffer}, {name})
Since: 0.7.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer.
- • {name} Name of the command to delete.
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer.
+ • {name} (`string`) Name of the command to delete.
nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()*
Gets a map of buffer-local |user-commands|.
@@ -1906,11 +1960,12 @@ nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()*
Since: 0.3.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {opts} Optional parameters. Currently not used.
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {opts} (`vim.api.keyset.get_commands`) Optional parameters.
+ Currently not used.
Return: ~
- Map of maps describing commands.
+ (`vim.api.keyset.command_info`) Map of maps describing commands.
nvim_cmd({cmd}, {opts}) *nvim_cmd()*
Executes an Ex command.
@@ -1933,17 +1988,18 @@ nvim_cmd({cmd}, {opts}) *nvim_cmd()*
Since: 0.8.0
Parameters: ~
- • {cmd} Command to execute. Must be a Dict that can contain the same
- values as the return value of |nvim_parse_cmd()| except
- "addr", "nargs" and "nextcmd" which are ignored if provided.
- All values except for "cmd" are optional.
- • {opts} Optional parameters.
+ • {cmd} (`vim.api.keyset.cmd`) Command to execute. Must be a Dict that
+ can contain the same values as the return value of
+ |nvim_parse_cmd()| except "addr", "nargs" and "nextcmd" which
+ are ignored if provided. All values except for "cmd" are
+ optional.
+ • {opts} (`vim.api.keyset.cmd_opts`) Optional parameters.
• output: (boolean, default false) Whether to return command
output.
Return: ~
- Command output (non-error, non-shell |:!|) if `output` is true, else
- empty string.
+ (`string`) Command output (non-error, non-shell |:!|) if `output` is
+ true, else empty string.
See also: ~
• |nvim_exec2()|
@@ -1965,9 +2021,10 @@ nvim_create_user_command({name}, {command}, {opts})
Since: 0.7.0
Parameters: ~
- • {name} Name of the new user command. Must begin with an uppercase
- letter.
- • {command} Replacement command to execute when this user command is
+ • {name} (`string`) Name of the new user command. Must begin with an
+ uppercase letter.
+ • {command} (`string|fun(args: vim.api.keyset.create_user_command.command_args)`)
+ Replacement command to execute when this user command is
executed. When called from Lua, the command can also be a
Lua function. The function is called with a single table
argument that contains the following keys:
@@ -1991,7 +2048,8 @@ nvim_create_user_command({name}, {command}, {opts})
• smods: (table) Command modifiers in a structured format.
Has the same structure as the "mods" key of
|nvim_parse_cmd()|.
- • {opts} Optional |command-attributes|.
+ • {opts} (`vim.api.keyset.user_command`) Optional
+ |command-attributes|.
• Set boolean attributes such as |:command-bang| or
|:command-bar| to true (but not |:command-buffer|, use
|nvim_buf_create_user_command()| instead).
@@ -2013,7 +2071,7 @@ nvim_del_user_command({name}) *nvim_del_user_command()*
Since: 0.7.0
Parameters: ~
- • {name} Name of the command to delete.
+ • {name} (`string`) Name of the command to delete.
nvim_get_commands({opts}) *nvim_get_commands()*
Gets a map of global (non-buffer-local) Ex commands.
@@ -2024,10 +2082,12 @@ nvim_get_commands({opts}) *nvim_get_commands()*
Since: 0.3.0
Parameters: ~
- • {opts} Optional parameters. Currently only supports {"builtin":false}
+ • {opts} (`vim.api.keyset.get_commands`) Optional parameters. Currently
+ only supports {"builtin":false}
Return: ~
- Map of maps describing commands.
+ (`table<string,vim.api.keyset.command_info>`) Map of maps describing
+ commands.
See also: ~
• |nvim_get_all_options_info()|
@@ -2042,11 +2102,13 @@ nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()*
Since: 0.8.0
Parameters: ~
- • {str} Command line string to parse. Cannot contain "\n".
- • {opts} Optional parameters. Reserved for future use.
+ • {str} (`string`) Command line string to parse. Cannot contain "\n".
+ • {opts} (`vim.api.keyset.empty`) Optional parameters. Reserved for
+ future use.
Return: ~
- Dict containing command information, with these keys:
+ (`vim.api.keyset.cmd`) Dict containing command information, with these
+ keys:
• cmd: (string) Command name.
• range: (array) (optional) Command range (<line1> <line2>). Omitted
if command doesn't accept a range. Otherwise, has no elements if no
@@ -2115,7 +2177,7 @@ nvim_get_all_options_info() *nvim_get_all_options_info()*
Since: 0.5.0
Return: ~
- dict of all options
+ (`table<string,any>`) dict of all options
See also: ~
• |nvim_get_commands()|
@@ -2146,8 +2208,8 @@ nvim_get_option_info2({name}, {opts}) *nvim_get_option_info2()*
Since: 0.9.0
Parameters: ~
- • {name} Option name
- • {opts} Optional parameters
+ • {name} (`string`) Option name
+ • {opts} (`vim.api.keyset.option`) Optional parameters
• scope: One of "global" or "local". Analogous to |:setglobal|
and |:setlocal|, respectively.
• win: |window-ID|. Used for getting window local options.
@@ -2155,7 +2217,7 @@ nvim_get_option_info2({name}, {opts}) *nvim_get_option_info2()*
Implies {scope} is "local".
Return: ~
- Option Information
+ (`vim.api.keyset.get_option_info`) Option Information
nvim_get_option_value({name}, {opts}) *nvim_get_option_value()*
Gets the value of an option. The behavior of this function matches that of
@@ -2167,8 +2229,8 @@ nvim_get_option_value({name}, {opts}) *nvim_get_option_value()*
Since: 0.7.0
Parameters: ~
- • {name} Option name
- • {opts} Optional parameters
+ • {name} (`string`) Option name
+ • {opts} (`vim.api.keyset.option`) Optional parameters
• scope: One of "global" or "local". Analogous to |:setglobal|
and |:setlocal|, respectively.
• win: |window-ID|. Used for getting window local options.
@@ -2180,7 +2242,7 @@ nvim_get_option_value({name}, {opts}) *nvim_get_option_value()*
autocommands for the corresponding filetype.
Return: ~
- Option value
+ (`any`) Option value
*nvim_set_option_value()*
nvim_set_option_value({name}, {value}, {opts})
@@ -2194,9 +2256,9 @@ nvim_set_option_value({name}, {value}, {opts})
Since: 0.7.0
Parameters: ~
- • {name} Option name
- • {value} New option value
- • {opts} Optional parameters
+ • {name} (`string`) Option name
+ • {value} (`any`) New option value
+ • {opts} (`vim.api.keyset.option`) Optional parameters
• scope: One of "global" or "local". Analogous to
|:setglobal| and |:setlocal|, respectively.
• win: |window-ID|. Used for setting window local option.
@@ -2238,13 +2300,13 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Since: 0.3.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {send_buffer} True if the initial notification should contain the
- whole buffer: first notification will be
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {send_buffer} (`boolean`) True if the initial notification should
+ contain the whole buffer: first notification will be
`nvim_buf_lines_event`. Else the first notification
will be `nvim_buf_changedtick_event`. Not for Lua
callbacks.
- • {opts} Optional parameters.
+ • {opts} (`vim.api.keyset.buf_attach`) Optional parameters.
• on_lines: Lua callback invoked on change. Return a
truthy value (not `false` or `nil`) to detach. Args:
• the string "lines"
@@ -2295,8 +2357,8 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
'inccommand') events.
Return: ~
- False if attach failed (invalid parameter, or buffer isn't loaded);
- otherwise True. TODO: LUA_API_NO_EVAL
+ (`boolean`) False if attach failed (invalid parameter, or buffer isn't
+ loaded); otherwise True. TODO: LUA_API_NO_EVAL
See also: ~
• |nvim_buf_detach()|
@@ -2320,12 +2382,12 @@ nvim_buf_call({buffer}, {fun}) *nvim_buf_call()*
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {fun} Function to call inside the buffer (currently Lua callable
- only)
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {fun} (`function`) Function to call inside the buffer (currently
+ Lua callable only)
Return: ~
- Return value of function.
+ (`any`) Return value of function.
nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()*
Unmaps a buffer-local |mapping| for the given mode.
@@ -2334,7 +2396,9 @@ nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()*
Since: 0.4.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {mode} (`string`)
+ • {lhs} (`string`)
See also: ~
• |nvim_del_keymap()|
@@ -2350,11 +2414,11 @@ nvim_buf_del_mark({buffer}, {name}) *nvim_buf_del_mark()*
Since: 0.6.0
Parameters: ~
- • {buffer} Buffer to set the mark on
- • {name} Mark name
+ • {buffer} (`integer`) Buffer to set the mark on
+ • {name} (`string`) Mark name
Return: ~
- true if the mark was deleted, else false.
+ (`boolean`) true if the mark was deleted, else false.
See also: ~
• |nvim_buf_set_mark()|
@@ -2367,8 +2431,8 @@ nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {name} Variable name
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {name} (`string`) Variable name
nvim_buf_delete({buffer}, {opts}) *nvim_buf_delete()*
Deletes a buffer and its metadata (like |:bwipeout|).
@@ -2383,8 +2447,8 @@ nvim_buf_delete({buffer}, {opts}) *nvim_buf_delete()*
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {opts} Optional parameters. Keys:
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {opts} (`vim.api.keyset.buf_delete`) Optional parameters. Keys:
• force: Force deletion, ignore unsaved changes.
• unload: Unloaded only (|:bunload|), do not delete.
@@ -2396,11 +2460,11 @@ nvim_buf_detach({buffer}) *nvim_buf_detach()*
Since: 0.3.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
Return: ~
- False if detach failed (because the buffer isn't loaded); otherwise
- True.
+ (`boolean`) False if detach failed (because the buffer isn't loaded);
+ otherwise True.
See also: ~
• |nvim_buf_attach()|
@@ -2413,10 +2477,10 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()*
Since: 0.2.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
Return: ~
- `b:changedtick` value.
+ (`integer`) `b:changedtick` value.
nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()*
Gets a list of buffer-local |mapping| definitions.
@@ -2425,12 +2489,12 @@ nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()*
Since: 0.2.1
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {mode} Mode short-name ("n", "i", "v", ...)
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {mode} (`string`) Mode short-name ("n", "i", "v", ...)
Return: ~
- Array of |maparg()|-like dictionaries describing mappings. The
- "buffer" key holds the associated buffer id.
+ (`vim.api.keyset.get_keymap[]`) Array of |maparg()|-like dictionaries
+ describing mappings. The "buffer" key holds the associated buffer id.
*nvim_buf_get_lines()*
nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
@@ -2447,13 +2511,14 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {start} First line index
- • {end} Last line index, exclusive
- • {strict_indexing} Whether out-of-bounds should be an error.
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {start} (`integer`) First line index
+ • {end} (`integer`) Last line index, exclusive
+ • {strict_indexing} (`boolean`) Whether out-of-bounds should be an
+ error.
Return: ~
- Array of lines, or empty array for unloaded buffer.
+ (`string[]`) Array of lines, or empty array for unloaded buffer.
See also: ~
• |nvim_buf_get_text()|
@@ -2469,12 +2534,12 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {name} Mark name
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {name} (`string`) Mark name
Return: ~
- (row, col) tuple, (0, 0) if the mark is not set, or is an
- uppercase/file mark set in another buffer.
+ (`[integer, integer]`) (row, col) tuple, (0, 0) if the mark is not
+ set, or is an uppercase/file mark set in another buffer.
See also: ~
• |nvim_buf_set_mark()|
@@ -2487,10 +2552,10 @@ nvim_buf_get_name({buffer}) *nvim_buf_get_name()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
Return: ~
- Buffer name
+ (`string`) Buffer name
nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()*
Returns the byte offset of a line (0-indexed). |api-indexing|
@@ -2507,11 +2572,11 @@ nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()*
Since: 0.3.2
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {index} Line index
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {index} (`integer`) Line index
Return: ~
- Integer byte offset, or -1 for unloaded buffer.
+ (`integer`) Integer byte offset, or -1 for unloaded buffer.
*nvim_buf_get_text()*
nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
@@ -2528,15 +2593,17 @@ nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
Since: 0.7.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {start_row} First line index
- • {start_col} Starting column (byte offset) on first line
- • {end_row} Last line index, inclusive
- • {end_col} Ending column (byte offset) on last line, exclusive
- • {opts} Optional parameters. Currently unused.
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {start_row} (`integer`) First line index
+ • {start_col} (`integer`) Starting column (byte offset) on first line
+ • {end_row} (`integer`) Last line index, inclusive
+ • {end_col} (`integer`) Ending column (byte offset) on last line,
+ exclusive
+ • {opts} (`vim.api.keyset.empty`) Optional parameters. Currently
+ unused.
Return: ~
- Array of lines, or empty array for unloaded buffer.
+ (`string[]`) Array of lines, or empty array for unloaded buffer.
nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()*
Gets a buffer-scoped (b:) variable.
@@ -2545,11 +2612,11 @@ nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {name} Variable name
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {name} (`string`) Variable name
Return: ~
- Variable value
+ (`any`) Variable value
nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()*
Checks if a buffer is valid and loaded. See |api-buffer| for more info
@@ -2559,10 +2626,10 @@ nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()*
Since: 0.3.2
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
Return: ~
- true if the buffer is valid and loaded, false otherwise.
+ (`boolean`) true if the buffer is valid and loaded, false otherwise.
nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()*
Checks if a buffer is valid.
@@ -2575,10 +2642,10 @@ nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
Return: ~
- true if the buffer is valid, false otherwise.
+ (`boolean`) true if the buffer is valid, false otherwise.
nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
Returns the number of lines in the given buffer.
@@ -2587,10 +2654,10 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
Return: ~
- Line count, or 0 for unloaded buffer. |api-buffer|
+ (`integer`) Line count, or 0 for unloaded buffer. |api-buffer|
*nvim_buf_set_keymap()*
nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts})
@@ -2600,7 +2667,11 @@ nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts})
Since: 0.4.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {mode} (`string`)
+ • {lhs} (`string`)
+ • {rhs} (`string`)
+ • {opts} (`vim.api.keyset.keymap`)
See also: ~
• |nvim_set_keymap()|
@@ -2624,11 +2695,12 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement})
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {start} First line index
- • {end} Last line index, exclusive
- • {strict_indexing} Whether out-of-bounds should be an error.
- • {replacement} Array of lines to use as replacement
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {start} (`integer`) First line index
+ • {end} (`integer`) Last line index, exclusive
+ • {strict_indexing} (`boolean`) Whether out-of-bounds should be an
+ error.
+ • {replacement} (`string[]`) Array of lines to use as replacement
See also: ~
• |nvim_buf_set_text()|
@@ -2647,14 +2719,15 @@ nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts})
Since: 0.6.0
Parameters: ~
- • {buffer} Buffer to set the mark on
- • {name} Mark name
- • {line} Line number
- • {col} Column/row number
- • {opts} Optional parameters. Reserved for future use.
+ • {buffer} (`integer`) Buffer to set the mark on
+ • {name} (`string`) Mark name
+ • {line} (`integer`) Line number
+ • {col} (`integer`) Column/row number
+ • {opts} (`vim.api.keyset.empty`) Optional parameters. Reserved for
+ future use.
Return: ~
- true if the mark was set, else false.
+ (`boolean`) true if the mark was set, else false.
See also: ~
• |nvim_buf_del_mark()|
@@ -2667,8 +2740,8 @@ nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {name} Buffer name
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {name} (`string`) Buffer name
*nvim_buf_set_text()*
nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
@@ -2697,12 +2770,13 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {start_row} First line index
- • {start_col} Starting column (byte offset) on first line
- • {end_row} Last line index, inclusive
- • {end_col} Ending column (byte offset) on last line, exclusive
- • {replacement} Array of lines to use as replacement
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {start_row} (`integer`) First line index
+ • {start_col} (`integer`) Starting column (byte offset) on first line
+ • {end_row} (`integer`) Last line index, inclusive
+ • {end_col} (`integer`) Ending column (byte offset) on last line,
+ exclusive
+ • {replacement} (`string[]`) Array of lines to use as replacement
nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*
Sets a buffer-scoped (b:) variable
@@ -2711,9 +2785,9 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {name} Variable name
- • {value} Variable value
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {name} (`string`) Variable name
+ • {value} (`any`) Variable value
==============================================================================
@@ -2731,11 +2805,12 @@ nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end})
Since: 0.3.2
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {ns_id} Namespace to clear, or -1 to clear all namespaces.
- • {line_start} Start of range of lines to clear
- • {line_end} End of range of lines to clear (exclusive) or -1 to
- clear to end of buffer.
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {ns_id} (`integer`) Namespace to clear, or -1 to clear all
+ namespaces.
+ • {line_start} (`integer`) Start of range of lines to clear
+ • {line_end} (`integer`) End of range of lines to clear (exclusive)
+ or -1 to clear to end of buffer.
nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()*
Removes an |extmark|.
@@ -2744,12 +2819,12 @@ nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()*
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {ns_id} Namespace id from |nvim_create_namespace()|
- • {id} Extmark id
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {ns_id} (`integer`) Namespace id from |nvim_create_namespace()|
+ • {id} (`integer`) Extmark id
Return: ~
- true if the extmark was found, else false
+ (`boolean`) true if the extmark was found, else false
*nvim_buf_get_extmark_by_id()*
nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts})
@@ -2759,16 +2834,17 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts})
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {ns_id} Namespace id from |nvim_create_namespace()|
- • {id} Extmark id
- • {opts} Optional parameters. Keys:
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {ns_id} (`integer`) Namespace id from |nvim_create_namespace()|
+ • {id} (`integer`) Extmark id
+ • {opts} (`vim.api.keyset.get_extmark`) Optional parameters. Keys:
• details: Whether to include the details dict
• hl_name: Whether to include highlight group name instead
of id, true if omitted
Return: ~
- 0-indexed (row, col) tuple or empty list () if extmark id was absent
+ (`[integer, integer, vim.api.keyset.extmark_details?]`) 0-indexed
+ (row, col) tuple or empty list () if extmark id was absent
*nvim_buf_get_extmarks()*
nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
@@ -2815,15 +2891,16 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {ns_id} Namespace id from |nvim_create_namespace()| or -1 for all
- namespaces
- • {start} Start of range: a 0-indexed (row, col) or valid extmark id
- (whose position defines the bound). |api-indexing|
- • {end} End of range (inclusive): a 0-indexed (row, col) or valid
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {ns_id} (`integer`) Namespace id from |nvim_create_namespace()| or
+ -1 for all namespaces
+ • {start} (`any`) Start of range: a 0-indexed (row, col) or valid
extmark id (whose position defines the bound).
|api-indexing|
- • {opts} Optional parameters. Keys:
+ • {end} (`any`) End of range (inclusive): a 0-indexed (row, col) or
+ valid extmark id (whose position defines the bound).
+ |api-indexing|
+ • {opts} (`vim.api.keyset.get_extmarks`) Optional parameters. Keys:
• limit: Maximum number of marks to return
• details: Whether to include the details dict
• hl_name: Whether to include highlight group name instead
@@ -2834,7 +2911,8 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
"virt_text" and "virt_lines"
Return: ~
- List of `[extmark_id, row, col]` tuples in "traversal order".
+ (`vim.api.keyset.get_extmark_item[]`) List of `[extmark_id, row, col]`
+ tuples in "traversal order".
*nvim_buf_set_extmark()*
nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
@@ -2858,11 +2936,13 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer id, or 0 for current buffer
- • {ns_id} Namespace id from |nvim_create_namespace()|
- • {line} Line where to place the mark, 0-based. |api-indexing|
- • {col} Column where to place the mark, 0-based. |api-indexing|
- • {opts} Optional parameters.
+ • {buffer} (`integer`) Buffer id, or 0 for current buffer
+ • {ns_id} (`integer`) Namespace id from |nvim_create_namespace()|
+ • {line} (`integer`) Line where to place the mark, 0-based.
+ |api-indexing|
+ • {col} (`integer`) Column where to place the mark, 0-based.
+ |api-indexing|
+ • {opts} (`vim.api.keyset.set_extmark`) Optional parameters.
• id : id of the extmark to edit.
• end_row : ending line of the mark, 0-based inclusive.
• end_col : ending col of the mark, 0-based exclusive.
@@ -2986,7 +3066,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
hyperlink to this URL.
Return: ~
- Id of the created/updated extmark
+ (`integer`) Id of the created/updated extmark
nvim_create_namespace({name}) *nvim_create_namespace()*
Creates a new namespace or gets an existing one. *namespace*
@@ -3002,10 +3082,10 @@ nvim_create_namespace({name}) *nvim_create_namespace()*
Since: 0.3.2
Parameters: ~
- • {name} Namespace name or empty string
+ • {name} (`string`) Namespace name or empty string
Return: ~
- Namespace id
+ (`integer`) Namespace id
nvim_get_namespaces() *nvim_get_namespaces()*
Gets existing, non-anonymous |namespace|s.
@@ -3014,7 +3094,7 @@ nvim_get_namespaces() *nvim_get_namespaces()*
Since: 0.3.2
Return: ~
- dict that maps from names to namespace ids.
+ (`table<string,integer>`) dict that maps from names to namespace ids.
*nvim_set_decoration_provider()*
nvim_set_decoration_provider({ns_id}, {opts})
@@ -3052,8 +3132,9 @@ nvim_set_decoration_provider({ns_id}, {opts})
Since: 0.5.0
Parameters: ~
- • {ns_id} Namespace id from |nvim_create_namespace()|
- • {opts} Table of callbacks:
+ • {ns_id} (`integer`) Namespace id from |nvim_create_namespace()|
+ • {opts} (`vim.api.keyset.set_decoration_provider`) Table of
+ callbacks:
• on_start: called first on each screen redraw >
["start", tick]
<
@@ -3078,10 +3159,11 @@ nvim__ns_get({ns_id}) *nvim__ns_get()*
Get the properties for namespace
Parameters: ~
- • {ns_id} Namespace
+ • {ns_id} (`integer`) Namespace
Return: ~
- Map defining the namespace properties, see |nvim__ns_set()|
+ (`vim.api.keyset.ns_opts`) Map defining the namespace properties, see
+ |nvim__ns_set()|
nvim__ns_set({ns_id}, {opts}) *nvim__ns_set()*
EXPERIMENTAL: this API will change in the future.
@@ -3089,8 +3171,8 @@ nvim__ns_set({ns_id}, {opts}) *nvim__ns_set()*
Set some properties for namespace
Parameters: ~
- • {ns_id} Namespace
- • {opts} Optional parameters to set:
+ • {ns_id} (`integer`) Namespace
+ • {opts} (`vim.api.keyset.ns_opts`) Optional parameters to set:
• wins: a list of windows to be scoped in
@@ -3105,12 +3187,12 @@ nvim_win_call({window}, {fun}) *nvim_win_call()*
Since: 0.5.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
- • {fun} Function to call inside the window (currently Lua callable
- only)
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {fun} (`function`) Function to call inside the window (currently
+ Lua callable only)
Return: ~
- Return value of function.
+ (`any`) Return value of function.
See also: ~
• |win_execute()|
@@ -3124,10 +3206,10 @@ nvim_win_close({window}, {force}) *nvim_win_close()*
Since: 0.4.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
- • {force} Behave like `:close!` The last window of a buffer with
- unwritten changes can be closed. The buffer will become
- hidden, even if 'hidden' is not set.
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {force} (`boolean`) Behave like `:close!` The last window of a
+ buffer with unwritten changes can be closed. The buffer will
+ become hidden, even if 'hidden' is not set.
nvim_win_del_var({window}, {name}) *nvim_win_del_var()*
Removes a window-scoped (w:) variable
@@ -3136,8 +3218,8 @@ nvim_win_del_var({window}, {name}) *nvim_win_del_var()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
- • {name} Variable name
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {name} (`string`) Variable name
nvim_win_get_buf({window}) *nvim_win_get_buf()*
Gets the current buffer in a window
@@ -3146,10 +3228,10 @@ nvim_win_get_buf({window}) *nvim_win_get_buf()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
+ • {window} (`integer`) |window-ID|, or 0 for current window
Return: ~
- Buffer id
+ (`integer`) Buffer id
nvim_win_get_cursor({window}) *nvim_win_get_cursor()*
Gets the (1,0)-indexed, buffer-relative cursor position for a given window
@@ -3160,10 +3242,10 @@ nvim_win_get_cursor({window}) *nvim_win_get_cursor()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
+ • {window} (`integer`) |window-ID|, or 0 for current window
Return: ~
- (row, col) tuple
+ (`[integer, integer]`) (row, col) tuple
See also: ~
• |getcurpos()|
@@ -3175,10 +3257,10 @@ nvim_win_get_height({window}) *nvim_win_get_height()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
+ • {window} (`integer`) |window-ID|, or 0 for current window
Return: ~
- Height as a count of rows
+ (`integer`) Height as a count of rows
nvim_win_get_number({window}) *nvim_win_get_number()*
Gets the window number
@@ -3187,10 +3269,10 @@ nvim_win_get_number({window}) *nvim_win_get_number()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
+ • {window} (`integer`) |window-ID|, or 0 for current window
Return: ~
- Window number
+ (`integer`) Window number
nvim_win_get_position({window}) *nvim_win_get_position()*
Gets the window position in display cells. First position is zero.
@@ -3199,10 +3281,10 @@ nvim_win_get_position({window}) *nvim_win_get_position()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
+ • {window} (`integer`) |window-ID|, or 0 for current window
Return: ~
- (row, col) tuple with the window position
+ (`[integer, integer]`) (row, col) tuple with the window position
nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()*
Gets the window tabpage
@@ -3211,10 +3293,10 @@ nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
+ • {window} (`integer`) |window-ID|, or 0 for current window
Return: ~
- Tabpage that contains the window
+ (`integer`) Tabpage that contains the window
nvim_win_get_var({window}, {name}) *nvim_win_get_var()*
Gets a window-scoped (w:) variable
@@ -3223,11 +3305,11 @@ nvim_win_get_var({window}, {name}) *nvim_win_get_var()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
- • {name} Variable name
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {name} (`string`) Variable name
Return: ~
- Variable value
+ (`any`) Variable value
nvim_win_get_width({window}) *nvim_win_get_width()*
Gets the window width
@@ -3236,10 +3318,10 @@ nvim_win_get_width({window}) *nvim_win_get_width()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
+ • {window} (`integer`) |window-ID|, or 0 for current window
Return: ~
- Width as a count of columns
+ (`integer`) Width as a count of columns
nvim_win_hide({window}) *nvim_win_hide()*
Closes the window and hide the buffer it contains (like |:hide| with a
@@ -3254,7 +3336,7 @@ nvim_win_hide({window}) *nvim_win_hide()*
Since: 0.5.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
+ • {window} (`integer`) |window-ID|, or 0 for current window
nvim_win_is_valid({window}) *nvim_win_is_valid()*
Checks if a window is valid
@@ -3263,10 +3345,10 @@ nvim_win_is_valid({window}) *nvim_win_is_valid()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
+ • {window} (`integer`) |window-ID|, or 0 for current window
Return: ~
- true if the window is valid, false otherwise
+ (`boolean`) true if the window is valid, false otherwise
nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()*
Sets the current buffer in a window, without side effects
@@ -3276,8 +3358,8 @@ nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()*
Since: 0.3.2
Parameters: ~
- • {window} |window-ID|, or 0 for current window
- • {buffer} Buffer id
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {buffer} (`integer`) Buffer id
nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()*
Sets the (1,0)-indexed cursor position in the window. |api-indexing| This
@@ -3287,8 +3369,9 @@ nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
- • {pos} (row, col) tuple representing the new position
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {pos} (`[integer, integer]`) (row, col) tuple representing the new
+ position
nvim_win_set_height({window}, {height}) *nvim_win_set_height()*
Sets the window height.
@@ -3297,8 +3380,8 @@ nvim_win_set_height({window}, {height}) *nvim_win_set_height()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
- • {height} Height as a count of rows
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {height} (`integer`) Height as a count of rows
nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()*
Set highlight namespace for a window. This will use highlights defined
@@ -3311,7 +3394,8 @@ nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()*
Since: 0.8.0
Parameters: ~
- • {ns_id} the namespace to use
+ • {window} (`integer`)
+ • {ns_id} (`integer`) the namespace to use
nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()*
Sets a window-scoped (w:) variable
@@ -3320,9 +3404,9 @@ nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
- • {name} Variable name
- • {value} Variable value
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {name} (`string`) Variable name
+ • {value} (`any`) Variable value
nvim_win_set_width({window}, {width}) *nvim_win_set_width()*
Sets the window width. This will only succeed if the screen is split
@@ -3332,8 +3416,8 @@ nvim_win_set_width({window}, {width}) *nvim_win_set_width()*
Since: 0.1.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
- • {width} Width as a count of columns
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {width} (`integer`) Width as a count of columns
nvim_win_text_height({window}, {opts}) *nvim_win_text_height()*
Computes the number of screen lines occupied by a range of text in a given
@@ -3351,8 +3435,8 @@ nvim_win_text_height({window}, {opts}) *nvim_win_text_height()*
Since: 0.10.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window.
- • {opts} Optional parameters:
+ • {window} (`integer`) |window-ID|, or 0 for current window.
+ • {opts} (`vim.api.keyset.win_text_height`) Optional parameters:
• start_row: Starting line index, 0-based inclusive. When
omitted start at the very top.
• end_row: Ending line index, 0-based inclusive. When
@@ -3372,7 +3456,8 @@ nvim_win_text_height({window}, {opts}) *nvim_win_text_height()*
"end_row" and "end_vcol").
Return: ~
- Dict containing text height information, with these keys:
+ (`vim.api.keyset.win_text_height_ret`) Dict containing text height
+ information, with these keys:
• all: The total number of screen lines occupied by the range.
• fill: The number of diff filler or virtual lines among them.
• end_row: The row on which the returned height is reached (first row
@@ -3444,9 +3529,10 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
Since: 0.4.0
Parameters: ~
- • {buffer} Buffer to display, or 0 for current buffer
- • {enter} Enter the window (make it the current window)
- • {config} Map defining the window configuration. Keys:
+ • {buffer} (`integer`) Buffer to display, or 0 for current buffer
+ • {enter} (`boolean`) Enter the window (make it the current window)
+ • {config} (`vim.api.keyset.win_config`) Map defining the window
+ configuration. Keys:
• relative: Sets the window layout to "floating", placed at
(row,col) coordinates relative to:
• "cursor" Cursor position in current window.
@@ -3563,7 +3649,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
offset in screen cell width.
Return: ~
- |window-ID|, or 0 on error
+ (`integer`) |window-ID|, or 0 on error
nvim_win_get_config({window}) *nvim_win_get_config()*
Gets window configuration.
@@ -3576,10 +3662,11 @@ nvim_win_get_config({window}) *nvim_win_get_config()*
Since: 0.4.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
+ • {window} (`integer`) |window-ID|, or 0 for current window
Return: ~
- Map defining the window configuration, see |nvim_open_win()|
+ (`vim.api.keyset.win_config`) Map defining the window configuration,
+ see |nvim_open_win()|
nvim_win_set_config({window}, {config}) *nvim_win_set_config()*
Configures window layout. Cannot be used to move the last window in a
@@ -3592,8 +3679,9 @@ nvim_win_set_config({window}, {config}) *nvim_win_set_config()*
Since: 0.4.0
Parameters: ~
- • {window} |window-ID|, or 0 for current window
- • {config} Map defining the window configuration, see |nvim_open_win()|
+ • {window} (`integer`) |window-ID|, or 0 for current window
+ • {config} (`vim.api.keyset.win_config`) Map defining the window
+ configuration, see |nvim_open_win()|
See also: ~
• |nvim_open_win()|
@@ -3609,8 +3697,8 @@ nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()*
Since: 0.1.0
Parameters: ~
- • {tabpage} |tab-ID|, or 0 for current tabpage
- • {name} Variable name
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
+ • {name} (`string`) Variable name
nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()*
Gets the tabpage number
@@ -3619,10 +3707,10 @@ nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()*
Since: 0.1.0
Parameters: ~
- • {tabpage} |tab-ID|, or 0 for current tabpage
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
Return: ~
- Tabpage number
+ (`integer`) Tabpage number
nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()*
Gets a tab-scoped (t:) variable
@@ -3631,11 +3719,11 @@ nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()*
Since: 0.1.0
Parameters: ~
- • {tabpage} |tab-ID|, or 0 for current tabpage
- • {name} Variable name
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
+ • {name} (`string`) Variable name
Return: ~
- Variable value
+ (`any`) Variable value
nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()*
Gets the current window in a tabpage
@@ -3644,10 +3732,10 @@ nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()*
Since: 0.1.0
Parameters: ~
- • {tabpage} |tab-ID|, or 0 for current tabpage
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
Return: ~
- |window-ID|
+ (`integer`) |window-ID|
nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()*
Checks if a tabpage is valid
@@ -3656,10 +3744,10 @@ nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()*
Since: 0.1.0
Parameters: ~
- • {tabpage} |tab-ID|, or 0 for current tabpage
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
Return: ~
- true if the tabpage is valid, false otherwise
+ (`boolean`) true if the tabpage is valid, false otherwise
nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()*
Gets the windows in a tabpage
@@ -3668,10 +3756,10 @@ nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()*
Since: 0.1.0
Parameters: ~
- • {tabpage} |tab-ID|, or 0 for current tabpage
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
Return: ~
- List of windows in `tabpage`
+ (`integer[]`) List of windows in `tabpage`
*nvim_tabpage_set_var()*
nvim_tabpage_set_var({tabpage}, {name}, {value})
@@ -3681,9 +3769,9 @@ nvim_tabpage_set_var({tabpage}, {name}, {value})
Since: 0.1.0
Parameters: ~
- • {tabpage} |tab-ID|, or 0 for current tabpage
- • {name} Variable name
- • {value} Variable value
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
+ • {name} (`string`) Variable name
+ • {value} (`any`) Variable value
nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()*
Sets the current window in a tabpage
@@ -3692,8 +3780,8 @@ nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()*
Since: 0.10.0
Parameters: ~
- • {tabpage} |tab-ID|, or 0 for current tabpage
- • {win} |window-ID|, must already belong to {tabpage}
+ • {tabpage} (`integer`) |tab-ID|, or 0 for current tabpage
+ • {win} (`integer`) |window-ID|, must already belong to {tabpage}
==============================================================================
@@ -3707,7 +3795,7 @@ nvim_clear_autocmds({opts}) *nvim_clear_autocmds()*
Since: 0.7.0
Parameters: ~
- • {opts} Parameters
+ • {opts} (`vim.api.keyset.clear_autocmds`) Parameters
• event: (string|table) Examples:
• event: "pat1"
• event: { "pat1" }
@@ -3739,13 +3827,13 @@ nvim_create_augroup({name}, {opts}) *nvim_create_augroup()*
Since: 0.7.0
Parameters: ~
- • {name} String: The name of the group
- • {opts} Dict Parameters
+ • {name} (`string`) String: The name of the group
+ • {opts} (`vim.api.keyset.create_augroup`) Dict Parameters
• clear (bool) optional: defaults to true. Clear existing
commands if the group already exists |autocmd-groups|.
Return: ~
- Integer id of the created group.
+ (`integer`) Integer id of the created group.
See also: ~
• |autocmd-groups|
@@ -3780,9 +3868,9 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()*
Since: 0.7.0
Parameters: ~
- • {event} (string|array) Event(s) that will trigger the handler
+ • {event} (`any`) (string|array) Event(s) that will trigger the handler
(`callback` or `command`).
- • {opts} Options dict:
+ • {opts} (`vim.api.keyset.create_autocmd`) Options dict:
• group (string|integer) optional: autocommand group name or
id to match against.
• pattern (string|array) optional: pattern(s) to match
@@ -3815,7 +3903,7 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()*
autocommands |autocmd-nested|.
Return: ~
- Autocommand id (number)
+ (`integer`) Autocommand id (number)
See also: ~
• |autocommand|
@@ -3834,7 +3922,7 @@ nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()*
Since: 0.7.0
Parameters: ~
- • {id} Integer The id of the group.
+ • {id} (`integer`) Integer The id of the group.
See also: ~
• |nvim_del_augroup_by_name()|
@@ -3851,7 +3939,7 @@ nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()*
Since: 0.7.0
Parameters: ~
- • {name} String The name of the group.
+ • {name} (`string`) String The name of the group.
See also: ~
• |autocmd-groups|
@@ -3863,7 +3951,8 @@ nvim_del_autocmd({id}) *nvim_del_autocmd()*
Since: 0.7.0
Parameters: ~
- • {id} Integer Autocommand id returned by |nvim_create_autocmd()|
+ • {id} (`integer`) Integer Autocommand id returned by
+ |nvim_create_autocmd()|
nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()*
Execute all autocommands for {event} that match the corresponding {opts}
@@ -3873,8 +3962,8 @@ nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()*
Since: 0.7.0
Parameters: ~
- • {event} (String|Array) The event or events to execute
- • {opts} Dict of autocommand options:
+ • {event} (`any`) (String|Array) The event or events to execute
+ • {opts} (`vim.api.keyset.exec_autocmds`) Dict of autocommand options:
• group (string|integer) optional: the autocommand group name
or id to match against. |autocmd-groups|.
• pattern (string|array) optional: defaults to "*"
@@ -3913,7 +4002,8 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()*
Since: 0.7.0
Parameters: ~
- • {opts} Dict with at least one of the following:
+ • {opts} (`vim.api.keyset.get_autocmds`) Dict with at least one of the
+ following:
• buffer: (integer) Buffer number or list of buffer numbers
for buffer local autocommands |autocmd-buflocal|. Cannot be
used with {pattern}
@@ -3926,8 +4016,8 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()*
|autocmd-pattern|. Cannot be used with {buffer}
Return: ~
- Array of autocommands matching the criteria, with each item containing
- the following fields:
+ (`vim.api.keyset.get_autocmds.ret[]`) Array of autocommands matching
+ the criteria, with each item containing the following fields:
• buffer: (integer) the buffer number.
• buflocal: (boolean) true if the autocommand is buffer local.
• command: (string) the autocommand command. Note: this will be empty
@@ -3965,9 +4055,9 @@ nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()*
Since: 0.1.0
Parameters: ~
- • {width} Requested screen columns
- • {height} Requested screen rows
- • {options} |ui-option| map
+ • {width} (`integer`) Requested screen columns
+ • {height} (`integer`) Requested screen rows
+ • {options} (`table<string,any>`) |ui-option| map
nvim_ui_detach() *nvim_ui_detach()*
Deactivates UI events on the channel.
@@ -3995,10 +4085,10 @@ nvim_ui_pum_set_bounds({width}, {height}, {row}, {col})
Since: 0.5.0
Parameters: ~
- • {width} Popupmenu width.
- • {height} Popupmenu height.
- • {row} Popupmenu row.
- • {col} Popupmenu height.
+ • {width} (`number`) Popupmenu width.
+ • {height} (`number`) Popupmenu height.
+ • {row} (`number`) Popupmenu row.
+ • {col} (`number`) Popupmenu height.
nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()*
Tells Nvim the number of elements displaying in the popupmenu, to decide
@@ -4009,7 +4099,7 @@ nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()*
Since: 0.4.0
Parameters: ~
- • {height} Popupmenu height, must be greater than zero.
+ • {height} (`integer`) Popupmenu height, must be greater than zero.
nvim_ui_set_focus({gained}) *nvim_ui_set_focus()*
Tells the nvim server if focus was gained or lost by the GUI
@@ -4018,12 +4108,19 @@ nvim_ui_set_focus({gained}) *nvim_ui_set_focus()*
|RPC| only
Since: 0.9.0
+ Parameters: ~
+ • {gained} (`boolean`)
+
nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()*
Attributes: ~
|RPC| only
Since: 0.1.0
+ Parameters: ~
+ • {name} (`string`)
+ • {value} (`any`)
+
nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()*
Tells Nvim when a terminal event has occurred
@@ -4037,8 +4134,8 @@ nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()*
Since: 0.10.0
Parameters: ~
- • {event} Event name
- • {value} Event payload
+ • {event} (`string`) Event name
+ • {value} (`any`) Event payload
nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()*
@@ -4046,6 +4143,10 @@ nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()*
|RPC| only
Since: 0.1.0
+ Parameters: ~
+ • {width} (`integer`)
+ • {height} (`integer`)
+
*nvim_ui_try_resize_grid()*
nvim_ui_try_resize_grid({grid}, {width}, {height})
Tell Nvim to resize a grid. Triggers a grid_resize event with the
@@ -4058,9 +4159,9 @@ nvim_ui_try_resize_grid({grid}, {width}, {height})
Since: 0.4.0
Parameters: ~
- • {grid} The handle of the grid to be changed.
- • {width} The new requested width.
- • {height} The new requested height.
+ • {grid} (`integer`) The handle of the grid to be changed.
+ • {width} (`integer`) The new requested width.
+ • {height} (`integer`) The new requested height.
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
@@ -27,7 +27,7 @@ function vim.api.nvim__buf_stats(buffer) end
--- @param index integer Completion candidate index
--- @param opts vim.api.keyset.complete_set Optional parameters.
--- - info: (string) info text.
---- @return table<string,any> # Dict containing these keys:
+--- @return table<string,number> # Dict containing these keys:
--- - winid: (number) floating window id
--- - bufnr: (number) buffer id in floating window
function vim.api.nvim__complete_set(index, opts) end
@@ -37,7 +37,7 @@ function vim.api.nvim__get_lib_dir() end
--- Find files in runtime directories
---
---- @param pat any[] pattern of files to search for
+--- @param pat string[] pattern of files to search for
--- @param all boolean whether to return all matches or only the first
--- @param opts vim.api.keyset.runtime is_lua: only search Lua subdirs
--- @return string[] # list of absolute paths to the found files
@@ -348,7 +348,7 @@ function vim.api.nvim_buf_get_changedtick(buffer) end
---
--- @param buffer integer Buffer id, or 0 for current buffer
--- @param opts vim.api.keyset.get_commands Optional parameters. Currently not used.
---- @return table<string,any> # Map of maps describing commands.
+--- @return vim.api.keyset.command_info # Map of maps describing commands.
function vim.api.nvim_buf_get_commands(buffer, opts) end
--- Gets the position (0-indexed) of an `extmark`.
@@ -359,7 +359,7 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end
--- @param opts vim.api.keyset.get_extmark Optional parameters. Keys:
--- - details: Whether to include the details dict
--- - hl_name: Whether to include highlight group name instead of id, true if omitted
---- @return vim.api.keyset.get_extmark_item_by_id # 0-indexed (row, col) tuple or empty list () if extmark id was
+--- @return [integer, integer, vim.api.keyset.extmark_details?] # 0-indexed (row, col) tuple or empty list () if extmark id was
--- absent
function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
@@ -1096,7 +1096,7 @@ function vim.api.nvim_del_var(name) end
--- vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
--- ```
---
---- @param chunks any[] List of `[text, hl_group]` pairs, where each is a `text` string highlighted by
+--- @param chunks [string, integer|string][] List of `[text, hl_group]` pairs, where each is a `text` string highlighted by
--- the (optional) name or ID `hl_group`.
--- @param history boolean if true, add to `message-history`.
--- @param opts vim.api.keyset.echo_opts Optional parameters.
@@ -1327,7 +1327,7 @@ function vim.api.nvim_get_color_map() end
--- @see vim.api.nvim_get_all_options_info
--- @param opts vim.api.keyset.get_commands Optional parameters. Currently only supports
--- {"builtin":false}
---- @return table<string,any> # Map of maps describing commands.
+--- @return table<string,vim.api.keyset.command_info> # Map of maps describing commands.
function vim.api.nvim_get_commands(opts) end
--- Gets a map of the current editor state.
@@ -1427,7 +1427,7 @@ function vim.api.nvim_get_keymap(mode) end
--- @see vim.api.nvim_del_mark
--- @param name string Mark name
--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
---- @return vim.api.keyset.get_mark # 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is
+--- @return [integer, integer, integer, string] # 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is
--- not set.
function vim.api.nvim_get_mark(name, opts) end
@@ -1599,7 +1599,7 @@ function vim.api.nvim_list_bufs() end
--- Get information about all open channels.
---
---- @return any[] # Array of Dictionaries, each describing a channel with
+--- @return table<string,any>[] # Array of Dictionaries, each describing a channel with
--- the format specified at |nvim_get_chan_info()|.
function vim.api.nvim_list_chans() end
@@ -1623,7 +1623,7 @@ function vim.api.nvim_list_tabpages() end
--- vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)
--- ```
---
---- @return any[] # Array of UI dictionaries, each with these keys:
+--- @return table<string,any>[] # Array of UI dictionaries, each with these keys:
--- - "height" Requested height of the UI
--- - "width" Requested width of the UI
--- - "rgb" true if the UI uses RGB colors (false implies |cterm-colors|)
@@ -1865,7 +1865,7 @@ function vim.api.nvim_out_write(str) end
---
--- @param str string Command line string to parse. Cannot contain "\n".
--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use.
---- @return vim.api.keyset.parse_cmd # Dict containing command information, with these keys:
+--- @return vim.api.keyset.cmd # Dict containing command information, with these keys:
--- - cmd: (string) Command name.
--- - range: (array) (optional) Command range ([<line1>] [<line2>]).
--- Omitted if command doesn't accept a range.
diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua
@@ -24,15 +24,15 @@ error('Cannot require a meta file')
--- @class vim.api.keyset.cmd
--- @field cmd? string
---- @field range? any[]
+--- @field range? integer[]
--- @field count? integer
--- @field reg? string
--- @field bang? boolean
--- @field args? string[]
---- @field magic? table<string,any>
---- @field mods? table<string,any>
---- @field nargs? integer|string
---- @field addr? string
+--- @field magic? vim.api.keyset.cmd.magic
+--- @field mods? vim.api.keyset.cmd.mods
+--- @field nargs? integer|"?"|"+"|"*"
+--- @field addr? "line"|"arg"|"buf"|"load"|"win"|"tab"|"qf"|"none"|"?"
--- @field nextcmd? string
--- @class vim.api.keyset.cmd_magic
@@ -79,7 +79,7 @@ error('Cannot require a meta file')
--- @class vim.api.keyset.create_autocmd
--- @field buffer? integer
---- @field callback? string|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean?)
+--- @field callback? string|fun(args: vim.api.keyset.create_autocmd.callback_args): boolean?
--- @field command? string
--- @field desc? string
--- @field group? integer|string
@@ -294,9 +294,9 @@ error('Cannot require a meta file')
--- @field col? number
--- @field width? integer
--- @field height? integer
---- @field anchor? 'NW'|'NE'|'SW'|'SE'
---- @field relative? 'cursor'|'editor'|'laststatus'|'mouse'|'tabline'|'win'
---- @field split? 'left'|'right'|'above'|'below'
+--- @field anchor? "NW"|"NE"|"SW"|"SE"
+--- @field relative? "cursor"|"editor"|"laststatus"|"mouse"|"tabline"|"win"
+--- @field split? "left"|"right"|"above"|"below"
--- @field win? integer
--- @field bufpos? integer[]
--- @field external? boolean
@@ -304,12 +304,12 @@ error('Cannot require a meta file')
--- @field mouse? boolean
--- @field vertical? boolean
--- @field zindex? integer
---- @field border? 'none'|'single'|'double'|'rounded'|'solid'|'shadow'|string[]
+--- @field border? string[]|"none"|"single"|"double"|"rounded"|"solid"|"shadow"
--- @field title? any
---- @field title_pos? 'center'|'left'|'right'
+--- @field title_pos? "center"|"left"|"right"
--- @field footer? any
---- @field footer_pos? 'center'|'left'|'right'
---- @field style? 'minimal'
+--- @field footer_pos? "center"|"left"|"right"
+--- @field style? "minimal"
--- @field noautocmd? boolean
--- @field fixed? boolean
--- @field hide? boolean
diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua
@@ -54,12 +54,6 @@ error('Cannot require a meta file')
--- @field [3] integer col
--- @field [4] vim.api.keyset.extmark_details?
---- @class vim.api.keyset.get_mark
---- @field [1] integer row
---- @field [2] integer col
---- @field [3] integer buffer
---- @field [4] string buffername
-
--- @class vim.api.keyset.get_autocmds.ret
--- @field id? integer
--- @field group? integer
@@ -212,7 +206,7 @@ error('Cannot require a meta file')
--- @field default string|boolean|integer
--- @field allows_duplicates boolean
---- @class vim.api.keyset.parse_cmd.mods
+--- @class vim.api.keyset.cmd.mods
--- @field filter { force: boolean, pattern: string }
--- @field silent boolean
--- @field emsg_silent boolean
@@ -234,18 +228,9 @@ error('Cannot require a meta file')
--- @field horizontal boolean
--- @field split ''|'botright'|'topleft'|'belowright'|'aboveleft'
---- @class vim.api.keyset.parse_cmd
---- @field addr 'line'|'arg'|'buf'|'load'|'win'|'tab'|'qf'|'none'|'?'
---- @field args string[]
---- @field bang boolean
---- @field cmd string
---- @field magic {bar: boolean, file: boolean}
---- @field mods vim.api.keyset.parse_cmd.mods
---- @field nargs '0'|'1'|'?'|'+'|'*'
---- @field nextcmd string
---- @field range? integer[]
---- @field count? integer
---- @field reg? string
+--- @class vim.api.keyset.cmd.magic
+--- @field bar boolean
+--- @field file boolean
--- @class vim.api.keyset.eval_statusline_ret.highlight
--- @field start integer
diff --git a/src/gen/api_types.lua b/src/gen/api_types.lua
@@ -0,0 +1,74 @@
+local API_TYPES = {
+ Window = 'integer',
+ Tabpage = 'integer',
+ Buffer = 'integer',
+ Boolean = 'boolean',
+ Object = 'any',
+ Integer = 'integer',
+ String = 'string',
+ Array = 'any[]',
+ LuaRef = 'function',
+ Dict = 'table<string,any>',
+ Float = 'number',
+ HLGroupID = 'integer|string',
+ void = 'nil',
+}
+
+local typed_container = require('gen.c_grammar').typed_container
+
+--- Convert an API type to Lua
+--- @param t string
+--- @return string
+local function api_type(t)
+ if vim.startswith(t, '*') then
+ return api_type(t:sub(2)) .. '?'
+ end
+
+ --- @type nvim.c_grammar.Container?
+ local t0 = typed_container:match(t)
+
+ if t0 then
+ local container = t0[1]
+
+ if container == 'ArrayOf' then
+ --- @cast t0 nvim.c_grammar.Container.ArrayOf
+ local ty = api_type(t0[2])
+ local count = tonumber(t0[3])
+ if count then
+ return ('[%s]'):format(ty:rep(count, ', '))
+ else
+ return ty .. '[]'
+ end
+ elseif container == 'Dict' or container == 'DictAs' then
+ --- @cast t0 nvim.c_grammar.Container.Dict
+ return 'vim.api.keyset.' .. t0[2]:gsub('__', '.')
+ elseif container == 'DictOf' then
+ --- @cast t0 nvim.c_grammar.Container.DictOf
+ local ty = api_type(t0[2])
+ return ('table<string,%s>'):format(ty)
+ elseif container == 'Tuple' then
+ --- @cast t0 nvim.c_grammar.Container.Tuple
+ return ('[%s]'):format(table.concat(vim.tbl_map(api_type, t0[2]), ', '))
+ elseif container == 'Enum' or container == 'Union' then
+ --- @cast t0 nvim.c_grammar.Container.Enum|nvim.c_grammar.Container.Union
+ return table.concat(vim.tbl_map(api_type, t0[2]), '|')
+ elseif container == 'LuaRefOf' then
+ --- @cast t0 nvim.c_grammar.Container.LuaRefOf
+ local _, as, r = unpack(t0)
+
+ local as1 = {} --- @type string[]
+ for _, a in ipairs(as) do
+ local ty, nm = unpack(a)
+ nm = nm:gsub('%*(.*)$', '%1?')
+ as1[#as1 + 1] = ('%s: %s'):format(nm, api_type(ty))
+ end
+
+ return ('fun(%s)%s'):format(table.concat(as1, ', '), r and ': ' .. api_type(r) or '')
+ end
+ error('Unknown container type: ' .. container)
+ end
+
+ return API_TYPES[t] or t
+end
+
+return api_type
diff --git a/src/gen/c_grammar.lua b/src/gen/c_grammar.lua
@@ -2,21 +2,51 @@
-- ignores comments and preprocessor commands and parses a very small subset
-- of C prototypes with a limited set of types
+---@diagnostic disable: missing-fields
+
--- @class nvim.c_grammar.Proto
--- @field [1] 'proto'
--- @field pos integer
--- @field endpos integer
---- @field fast boolean
--- @field name string
--- @field return_type string
--- @field parameters [string, string][]
+---
+--- Decl modifiers
+---
--- @field static true?
--- @field inline true?
+---
+--- Attributes
+---
+--- @field since integer?
+--- @field deprecated_since integer?
+--- @field fast true?
+--- @field ret_alloc true?
+--- @field noexport true?
+--- @field remote_only true?
+--- @field lua_only true?
+--- @field textlock_allow_cmdwin true?
+--- @field textlock true?
+--- @field remote_impl true?
+--- @field compositor_impl true?
+--- @field client_impl true?
+--- @field client_ignore true?
--- @class nvim.c_grammar.Preproc
--- @field [1] 'preproc'
--- @field content string
+--- @class nvim.c_grammar.Keyset.Field
+--- @field type string
+--- @field name string
+--- @field dict_key? string
+
+--- @class nvim.c_grammar.Keyset
+--- @field [1] 'typedef'
+--- @field keyset_name string
+--- @field fields nvim.c_grammar.Keyset.Field[]
+
--- @class nvim.c_grammar.Empty
--- @field [1] 'empty'
@@ -24,6 +54,7 @@
--- | nvim.c_grammar.Proto
--- | nvim.c_grammar.Preproc
--- | nvim.c_grammar.Empty
+--- | nvim.c_grammar.Keyset
--- @class nvim.c_grammar
--- @field match fun(self, input: string): nvim.c_grammar.result[]
@@ -95,19 +126,44 @@ local braces = P({
S = P('{') * rep(V('A')) * rep(V('S') + V('A')) * P('}'),
})
+--- @alias nvim.c_grammar.Container.Union ['Union', string[]]
+--- @alias nvim.c_grammar.Container.Tuple ['Tuple', string[]]
+--- @alias nvim.c_grammar.Container.Enum ['Enum', string[]]
+--- @alias nvim.c_grammar.Container.ArrayOf ['ArrayOf', string, integer?]
+--- @alias nvim.c_grammar.Container.DictOf ['DictOf', string]
+--- @alias nvim.c_grammar.Container.LuaRefOf ['LuaRefOf', [string, string][], string]
+--- @alias nvim.c_grammar.Container.Dict ['Dict', string]
+--- @alias nvim.c_grammar.Container.DictAs ['DictAs', string]
+
+--- @alias nvim.c_grammar.Container
+--- | nvim.c_grammar.Container.Union
+--- | nvim.c_grammar.Container.Tuple
+--- | nvim.c_grammar.Container.Enum
+--- | nvim.c_grammar.Container.ArrayOf
+--- | nvim.c_grammar.Container.DictOf
+--- | nvim.c_grammar.Container.LuaRefOf
+--- | nvim.c_grammar.Container.Dict
+
-- stylua: ignore start
local typed_container = P({
'S',
- S = (
- (P('Union') * paren(comma1(V('ID'))))
- + (P('ArrayOf') * paren(id * opt(P(',') * fill * rep1(num))))
- + (P('DictOf') * paren(id))
- + (P('LuaRefOf') * paren(
- paren(comma1((V('ID') + str) * rep1(ws) * opt(P('*')) * id))
- * opt(P(',') * fill * opt(P('*')) * V('ID'))
- ))
- + (P('Dict') * paren(id))),
- ID = V('S') + id,
+ S = Ct(
+ Cg(opt(P('*')) * P('Union')) * paren(Ct(comma1(V('TY'))))
+ + Cg(opt(P('*')) * P('Enum')) * paren(Ct(comma1(Cg(str))))
+ + Cg(opt(P('*')) * P('Tuple')) * paren(Ct(comma1(V('TY'))))
+ + Cg(opt(P('*')) * P('ArrayOf')) * paren(V('TY') * opt(P(',') * fill * C(rep1(num))))
+ + Cg(opt(P('*')) * P('DictOf')) * paren(V('TY'))
+ + Cg(opt(P('*')) * P('LuaRefOf'))
+ * paren(
+ Ct(paren(comma1(Ct((V('TY') + C(str)) * rep1(ws) * Cg(V('ID'))))))
+ * opt(P(',') * fill * V('TY'))
+ )
+ + Cg(opt(P('*')) * P('Dict')) * paren(C(id))
+ + Cg(opt(P('*')) * P('DictAs')) * paren(C(id))
+ ),
+ -- Remove captures here (with / 0 ) as api_types will recursively run parse the type.
+ TY = Cg(V('S') / 0 + V('ID')),
+ ID = opt(P('*')) * id,
})
-- stylua: ignore end
@@ -156,7 +212,7 @@ local api_param_type = (
local ctype = C(
opt(word('const'))
* (
- typed_container
+ typed_container / 0
-- 'unsigned' is a type modifier, and a type itself
+ (word('unsigned char') + word('unsigned'))
+ (word('struct') * fill * id)
diff --git a/src/gen/cdoc_parser.lua b/src/gen/cdoc_parser.lua
@@ -1,5 +1,6 @@
local cdoc_grammar = require('gen.cdoc_grammar')
local c_grammar = require('gen.c_grammar')
+local api_type = require('gen.api_types')
--- @class nvim.cdoc.parser.param
--- @field name string
@@ -140,7 +141,7 @@ local function process_proto(item, state)
cur_obj.params = cur_obj.params or {}
for _, p in ipairs(item.parameters) do
- local param = { name = p[2], type = p[1] }
+ local param = { name = p[2], type = api_type(p[1]) }
local added = false
for _, cp in ipairs(cur_obj.params) do
if cp.name == param.name then
@@ -156,7 +157,7 @@ local function process_proto(item, state)
end
cur_obj.returns = cur_obj.returns or { {} }
- cur_obj.returns[1].type = item.return_type
+ cur_obj.returns[1].type = api_type(item.return_type)
for _, a in ipairs({
'fast',
diff --git a/src/gen/gen_api_dispatch.lua b/src/gen/gen_api_dispatch.lua
@@ -7,9 +7,8 @@
-- cd src/nvim
-- nvim -l generators/gen_api_dispatch.lua "../../build/src/nvim/auto/api/private/dispatch_wrappers.generated.h" "../../build/src/nvim/auto/api/private/api_metadata.generated.h" "../../build/funcs_metadata.mpack" "../../build/src/nvim/auto/lua_api_c_bindings.generated.h" "../../build/src/nvim/auto/keysets_defs.generated.h" "../../build/ui_metadata.mpack" "../../build/cmake.config/auto/versiondef_git.h" "./api/autocmd.h" "./api/buffer.h" "./api/command.h" "./api/deprecated.h" "./api/extmark.h" "./api/keysets_defs.h" "./api/options.h" "./api/tabpage.h" "./api/ui.h" "./api/vim.h" "./api/vimscript.h" "./api/win_config.h" "./api/window.h" "../../build/include/api/autocmd.h.generated.h" "../../build/include/api/buffer.h.generated.h" "../../build/include/api/command.h.generated.h" "../../build/include/api/deprecated.h.generated.h" "../../build/include/api/extmark.h.generated.h" "../../build/include/api/options.h.generated.h" "../../build/include/api/tabpage.h.generated.h" "../../build/include/api/ui.h.generated.h" "../../build/include/api/vim.h.generated.h" "../../build/include/api/vimscript.h.generated.h" "../../build/include/api/win_config.h.generated.h" "../../build/include/api/window.h.generated.h"
-local mpack = vim.mpack
-
local hashy = require 'gen.hashy'
+local c_grammar = require('gen.c_grammar')
-- output h file with generated dispatch functions (dispatch_wrappers.generated.h)
local dispatch_outputf = arg[1]
@@ -27,19 +26,59 @@ local dispatch_deprecated_inputf = arg[10]
local pre_args = 10
assert(#arg >= pre_args)
+local function real_type(type, exported)
+ local ptype = c_grammar.typed_container:match(type)
+ if ptype then
+ local container = ptype[1]
+ if container == 'Union' then
+ return 'Object'
+ elseif container == 'Tuple' or container == 'ArrayOf' then
+ return 'Array'
+ elseif container == 'DictOf' or container == 'DictAs' then
+ return 'Dict'
+ elseif container == 'LuaRefOf' then
+ return 'LuaRef'
+ elseif container == 'Enum' then
+ return 'String'
+ elseif container == 'Dict' then
+ if exported then
+ return 'Dict'
+ end
+ -- internal type, used for keysets
+ return 'KeyDict_' .. ptype[2]
+ end
+ end
+ return type
+end
+
+--- @class gen_api_dispatch.Function : nvim.c_grammar.Proto
+--- @field method boolean
+--- @field receives_array_args? true
+--- @field receives_channel_id? true
+--- @field can_fail? true
+--- @field has_lua_imp? true
+--- @field receives_arena? true
+--- @field impl_name? string
+--- @field remote? boolean
+--- @field lua? boolean
+--- @field eval? boolean
+--- @field handler_id? integer
+
+--- @type gen_api_dispatch.Function[]
local functions = {}
--- names of all headers relative to the source root (for inclusion in the
--- generated file)
+--- Names of all headers relative to the source root (for inclusion in the
+--- generated file)
+--- @type string[]
local headers = {}
--- set of function names, used to detect duplicates
+--- Set of function names, used to detect duplicates
+--- @type table<string, true>
local function_names = {}
-local c_grammar = require('gen.c_grammar')
-
local startswith = vim.startswith
+--- @param fn gen_api_dispatch.Function
local function add_function(fn)
local public = startswith(fn.name, 'nvim_') or fn.deprecated_since
if public and not fn.noexport then
@@ -79,12 +118,21 @@ local function add_function(fn)
end
end
+--- @class gen_api_dispatch.Keyset
+--- @field name string
+--- @field keys string[]
+--- @field c_names table<string, string>
+--- @field types table<string, string>
+--- @field has_optional boolean
+
+--- @type gen_api_dispatch.Keyset[]
local keysets = {}
+--- @param val nvim.c_grammar.Keyset
local function add_keyset(val)
- local keys = {}
- local types = {}
- local c_names = {}
+ local keys = {} --- @type string[]
+ local types = {} --- @type table<string, string>
+ local c_names = {} --- @type table<string, string>
local is_set_name = 'is_set__' .. val.keyset_name .. '_'
local has_optional = false
for i, field in ipairs(val.fields) do
@@ -108,13 +156,13 @@ local function add_keyset(val)
has_optional = true
end
end
- table.insert(keysets, {
+ keysets[#keysets + 1] = {
name = val.keyset_name,
keys = keys,
c_names = c_names,
types = types,
has_optional = has_optional,
- })
+ }
end
local ui_options_text = nil
@@ -122,29 +170,35 @@ local ui_options_text = nil
-- read each input file, parse and append to the api metadata
for i = pre_args + 1, #arg do
local full_path = arg[i]
- local parts = {}
- for part in string.gmatch(full_path, '[^/]+') do
+ local parts = {} --- @type string[]
+ for part in full_path:gmatch('[^/]+') do
parts[#parts + 1] = part
end
headers[#headers + 1] = parts[#parts - 1] .. '/' .. parts[#parts]
local input = assert(io.open(full_path, 'rb'))
+ --- @type string
local text = input:read('*all')
- local tmp = c_grammar.grammar:match(text)
- for j = 1, #tmp do
- local val = tmp[j]
+ for _, val in ipairs(c_grammar.grammar:match(text)) do
if val.keyset_name then
+ --- @cast val nvim.c_grammar.Keyset
add_keyset(val)
elseif val.name then
+ --- @cast val gen_api_dispatch.Function
add_function(val)
end
end
- ui_options_text = ui_options_text or string.match(text, 'ui_ext_names%[][^{]+{([^}]+)}')
+ ui_options_text = ui_options_text or text:match('ui_ext_names%[][^{]+{([^}]+)}')
input:close()
end
+--- @cast ui_options_text string
+
+--- @generic T: table
+--- @param orig T
+--- @return T
local function shallowcopy(orig)
local copy = {}
for orig_key, orig_value in pairs(orig) do
@@ -153,9 +207,11 @@ local function shallowcopy(orig)
return copy
end
--- Export functions under older deprecated names.
--- These will be removed eventually.
+--- Export functions under older deprecated names.
+--- These will be removed eventually.
+--- @type table<string, string>
local deprecated_aliases = loadfile(dispatch_deprecated_inputf)()
+
for _, f in ipairs(shallowcopy(functions)) do
local ismethod = false
if startswith(f.name, 'nvim_') then
@@ -217,44 +273,47 @@ for _, f in ipairs(shallowcopy(functions)) do
end
end
--- don't expose internal attributes like "impl_name" in public metadata
-local exported_attributes = { 'name', 'return_type', 'method', 'since', 'deprecated_since' }
+--- don't expose internal attributes like "impl_name" in public metadata
+--- @class gen_api_dispatch.Function.Exported
+--- @field name string
+--- @field parameters [string, string][]
+--- @field return_type string
+--- @field method boolean
+--- @field since integer
+--- @field deprecated_since integer
+
+--- @type gen_api_dispatch.Function.Exported[]
local exported_functions = {}
+
for _, f in ipairs(functions) do
if not (startswith(f.name, 'nvim__') or f.name == 'nvim_error_event' or f.name == 'redraw') then
- local f_exported = {}
- for _, attr in ipairs(exported_attributes) do
- f_exported[attr] = f[attr]
- end
- f_exported.parameters = {}
+ --- @type gen_api_dispatch.Function.Exported
+ local f_exported = {
+ name = f.name,
+ method = f.method,
+ since = f.since,
+ deprecated_since = f.deprecated_since,
+ parameters = {},
+ return_type = real_type(f.return_type, true),
+ }
for i, param in ipairs(f.parameters) do
- if param[1] == 'DictOf(LuaRef)' then
- param = { 'Dict', param[2] }
- elseif startswith(param[1], 'Dict(') then
- param = { 'Dict', param[2] }
- end
- f_exported.parameters[i] = param
- end
- if startswith(f.return_type, 'Dict(') then
- f_exported.return_type = 'Dict'
+ f_exported.parameters[i] = { real_type(param[1], true), param[2] }
end
exported_functions[#exported_functions + 1] = f_exported
end
end
local ui_options = { 'rgb' }
-for x in string.gmatch(ui_options_text, '"([a-z][a-z_]+)"') do
+for x in ui_options_text:gmatch('"([a-z][a-z_]+)"') do
table.insert(ui_options, x)
end
+--- @type integer[]
local version = loadfile(nvim_version_inputf)()
local git_version = io.open(git_version_inputf):read '*a'
-local version_build = string.match(git_version, '#define NVIM_VERSION_BUILD "([^"]+)"') or vim.NIL
+local version_build = git_version:match('#define NVIM_VERSION_BUILD "([^"]+)"') or vim.NIL
--- serialize the API metadata using msgpack and embed into the resulting
--- binary for easy querying by clients
-local api_metadata_output = assert(io.open(api_metadata_outputf, 'wb'))
-local pieces = {}
+local pieces = {} --- @type string[]
-- Naively using mpack.encode({foo=x, bar=y}) will make the build
-- "non-reproducible". Emit maps directly as FIXDICT(2) "foo" x "bar" y instead
@@ -262,12 +321,13 @@ local function fixdict(num)
if num > 15 then
error 'implement more dict codes'
end
- table.insert(pieces, string.char(128 + num))
+ pieces[#pieces + 1] = string.char(128 + num)
end
+
local function put(item, item2)
- table.insert(pieces, mpack.encode(item))
+ table.insert(pieces, vim.mpack.encode(item))
if item2 ~= nil then
- table.insert(pieces, mpack.encode(item2))
+ table.insert(pieces, vim.mpack.encode(item2))
end
end
@@ -305,15 +365,18 @@ for i, item in ipairs(types) do
end
local packed = table.concat(pieces)
+--- @type fun(api_metadata: file*, name: string, packed: string)
local dump_bin_array = loadfile(dump_bin_array_inputf)()
+
+-- serialize the API metadata using msgpack and embed into the resulting
+-- binary for easy querying by clients
+local api_metadata_output = assert(io.open(api_metadata_outputf, 'wb'))
dump_bin_array(api_metadata_output, 'packed_api_metadata', packed)
api_metadata_output:close()
-- start building the dispatch wrapper output
local output = assert(io.open(dispatch_outputf, 'wb'))
-local keysets_defs = assert(io.open(keysets_outputf, 'wb'))
-
-- ===========================================================================
-- NEW API FILES MUST GO HERE.
--
@@ -344,6 +407,8 @@ output:write([[
]])
+local keysets_defs = assert(io.open(keysets_outputf, 'wb'))
+
keysets_defs:write('// IWYU pragma: private, include "nvim/api/private/dispatch.h"\n\n')
for _, k in ipairs(keysets) do
@@ -358,15 +423,10 @@ for _, k in ipairs(keysets) do
return 'kObjectTypeInteger'
elseif not type or vim.startswith(type, 'Union') then
return 'kObjectTypeNil'
- elseif vim.startswith(type, 'LuaRefOf') then
- return 'kObjectTypeLuaRef'
elseif type == 'StringArray' then
return 'kUnpackTypeStringArray'
- elseif vim.startswith(type, 'ArrayOf') then
- return 'kObjectTypeArray'
- else
- return 'kObjectType' .. type
end
+ return 'kObjectType' .. real_type(type)
end
output:write('KeySetLink ' .. k.name .. '_table[] = {\n')
@@ -410,20 +470,7 @@ KeySetLink *KeyDict_]] .. k.name .. [[_get_field(const char *str, size_t len)
]])
end
-local function real_type(type)
- local rv = type
- local rmatch = string.match(type, 'Dict%(([_%w]+)%)')
- if rmatch then
- return 'KeyDict_' .. rmatch
- elseif c_grammar.typed_container:match(rv) then
- if rv:match('Array') then
- rv = 'Array'
- else
- rv = 'Dict'
- end
- end
- return rv
-end
+keysets_defs:close()
local function attr_name(rt)
if rt == 'Float' then
@@ -439,7 +486,7 @@ end
for i = 1, #functions do
local fn = functions[i]
if fn.impl_name == nil and fn.remote then
- local args = {}
+ local args = {} --- @type string[]
output:write(
'Object handle_' .. fn.name .. '(uint64_t channel_id, Array args, Arena* arena, Error *error)'
@@ -653,8 +700,8 @@ for i = 1, #functions do
end
local ret_type = real_type(fn.return_type)
- if string.match(ret_type, '^KeyDict_') then
- local table = string.sub(ret_type, 9) .. '_table'
+ if ret_type:match('^KeyDict_') then
+ local table = ret_type:sub(9) .. '_table'
output:write(
'\n ret = DICT_OBJ(api_keydict_to_dict(&rv, '
.. table
@@ -663,7 +710,7 @@ for i = 1, #functions do
.. '), arena));'
)
elseif ret_type ~= 'void' then
- output:write('\n ret = ' .. string.upper(real_type(fn.return_type)) .. '_OBJ(rv);')
+ output:write('\n ret = ' .. real_type(fn.return_type):upper() .. '_OBJ(rv);')
end
output:write('\n\ncleanup:')
@@ -671,6 +718,7 @@ for i = 1, #functions do
end
end
+--- @type {[string]: gen_api_dispatch.Function, redraw: {impl_name: string, fast: boolean}}
local remote_fns = {}
for _, fn in ipairs(functions) do
if fn.remote then
@@ -706,9 +754,10 @@ output:write(hashfun)
output:close()
+--- @cast functions {[integer]: gen_api_dispatch.Function, keysets: gen_api_dispatch.Keyset[]}
functions.keysets = keysets
local mpack_output = assert(io.open(mpack_outputf, 'wb'))
-mpack_output:write(mpack.encode(functions))
+mpack_output:write(vim.mpack.encode(functions))
mpack_output:close()
local function include_headers(output_handle, headers_to_include)
@@ -719,11 +768,12 @@ local function include_headers(output_handle, headers_to_include)
end
end
+--- @param str string
local function write_shifted_output(str, ...)
str = str:gsub('\n ', '\n')
str = str:gsub('^ ', '')
str = str:gsub(' +$', '')
- output:write(string.format(str, ...))
+ output:write(str:format(...))
end
-- start building lua output
@@ -732,12 +782,14 @@ output = assert(io.open(lua_c_bindings_outputf, 'wb'))
include_headers(output, headers)
output:write('\n')
+--- @type {binding: string, api:string}[]
local lua_c_functions = {}
--- Generates C code to bridge RPC API <=> Lua.
---
--- Inspect the result here:
--- build/src/nvim/auto/api/private/dispatch_wrappers.generated.h
+--- @param fn gen_api_dispatch.Function
local function process_function(fn)
local lua_c_function_name = ('nlua_api_%s'):format(fn.name)
write_shifted_output(
@@ -791,14 +843,14 @@ local function process_function(fn)
end
local cparams = ''
- local free_code = {}
+ local free_code = {} --- @type string[]
for j = #fn.parameters, 1, -1 do
local param = fn.parameters[j]
local cparam = string.format('arg%u', j)
local param_type = real_type(param[1])
local extra = param_type == 'Dict' and 'false, ' or ''
local arg_free_code = ''
- if param[1] == 'Object' then
+ if param_type == 'Object' then
extra = 'true, '
arg_free_code = ' api_luarefs_free_object(' .. cparam .. ');'
elseif param[1] == 'DictOf(LuaRef)' then
@@ -809,7 +861,7 @@ local function process_function(fn)
end
local errshift = 0
local seterr = ''
- if string.match(param_type, '^KeyDict_') then
+ if param_type:match('^KeyDict_') then
write_shifted_output(
[[
%s %s = KEYDICT_INIT;
@@ -825,7 +877,7 @@ local function process_function(fn)
arg_free_code = ' api_luarefs_free_keydict('
.. cparam
.. ', '
- .. string.sub(param_type, 9)
+ .. param_type:sub(9)
.. '_table);'
else
write_shifted_output(
@@ -851,6 +903,7 @@ local function process_function(fn)
cparams = cparam .. ', ' .. cparams
end
if fn.receives_channel_id then
+ --- @type string
cparams = 'LUA_INTERNAL_CALL, ' .. cparams
end
if fn.receives_arena then
@@ -870,7 +923,7 @@ local function process_function(fn)
for i = 1, #free_code do
local rev_i = #free_code - i + 1
local code = free_code[rev_i]
- if i == 1 and not string.match(real_type(fn.parameters[1][1]), '^KeyDict_') then
+ if i == 1 and not real_type(fn.parameters[1][1]):match('^KeyDict_') then
free_at_exit_code = free_at_exit_code .. ('\n%s'):format(code)
else
free_at_exit_code = free_at_exit_code .. ('\nexit_%u:\n%s'):format(rev_i, code)
@@ -893,13 +946,8 @@ exit_0:
return lua_error(lstate);
}
]]
- local return_type
if fn.return_type ~= 'void' then
- if fn.return_type:match('^ArrayOf') then
- return_type = 'Array'
- else
- return_type = fn.return_type
- end
+ local return_type = real_type(fn.return_type)
local free_retval = ''
if fn.ret_alloc then
free_retval = ' api_free_' .. return_type:lower() .. '(ret);'
@@ -919,11 +967,8 @@ exit_0:
return_type,
ret_mode
)
- elseif string.match(ret_type, '^KeyDict_') then
- write_shifted_output(
- ' nlua_push_keydict(lstate, &ret, %s_table);\n',
- string.sub(ret_type, 9)
- )
+ elseif ret_type:match('^KeyDict_') then
+ write_shifted_output(' nlua_push_keydict(lstate, &ret, %s_table);\n', return_type:sub(9))
else
local special = (fn.since ~= nil and fn.since < 11)
write_shifted_output(
@@ -996,4 +1041,3 @@ output:write([[
]])
output:close()
-keysets_defs:close()
diff --git a/src/gen/gen_eval_files.lua b/src/gen/gen_eval_files.lua
@@ -3,6 +3,7 @@
-- Generator for various vimdoc and Lua type files
local util = require('gen.util')
+local api_type = require('gen.api_types')
local fmt = string.format
local DEP_API_METADATA = arg[1]
@@ -23,54 +24,6 @@ local TEXT_WIDTH = 78
--- @field remote boolean
--- @field since integer
-local LUA_API_RETURN_OVERRIDES = {
- nvim_buf_get_command = 'table<string,vim.api.keyset.command_info>',
- nvim_buf_get_extmark_by_id = 'vim.api.keyset.get_extmark_item_by_id',
- nvim_buf_get_extmarks = 'vim.api.keyset.get_extmark_item[]',
- nvim_buf_get_keymap = 'vim.api.keyset.get_keymap[]',
- nvim_get_autocmds = 'vim.api.keyset.get_autocmds.ret[]',
- nvim_get_color_map = 'table<string,integer>',
- nvim_get_command = 'table<string,vim.api.keyset.command_info>',
- nvim_get_keymap = 'vim.api.keyset.get_keymap[]',
- nvim_get_mark = 'vim.api.keyset.get_mark',
- nvim_eval_statusline = 'vim.api.keyset.eval_statusline_ret',
-
- -- Can also return table<string,vim.api.keyset.get_hl_info>, however we need to
- -- pick one to get some benefit.
- -- REVISIT lewrus01 (26/01/24): we can maybe add
- -- @overload fun(ns: integer, {}): table<string,vim.api.keyset.get_hl_info>
- nvim_get_hl = 'vim.api.keyset.get_hl_info',
-
- nvim_get_mode = 'vim.api.keyset.get_mode',
- nvim_get_namespaces = 'table<string,integer>',
- nvim_get_option_info = 'vim.api.keyset.get_option_info',
- nvim_get_option_info2 = 'vim.api.keyset.get_option_info',
- nvim_parse_cmd = 'vim.api.keyset.parse_cmd',
- nvim_win_get_config = 'vim.api.keyset.win_config',
- nvim_win_text_height = 'vim.api.keyset.win_text_height_ret',
-}
-
-local LUA_API_KEYSET_OVERRIDES = {
- create_autocmd = {
- callback = 'string|(fun(args: vim.api.keyset.create_autocmd.callback_args): boolean?)',
- },
- win_config = {
- anchor = "'NW'|'NE'|'SW'|'SE'",
- relative = "'cursor'|'editor'|'laststatus'|'mouse'|'tabline'|'win'",
- split = "'left'|'right'|'above'|'below'",
- border = "'none'|'single'|'double'|'rounded'|'solid'|'shadow'|string[]",
- title_pos = "'center'|'left'|'right'",
- footer_pos = "'center'|'left'|'right'",
- style = "'minimal'",
- },
-}
-
-local LUA_API_PARAM_OVERRIDES = {
- nvim_create_user_command = {
- command = 'string|fun(args: vim.api.keyset.create_user_command.command_args)',
- },
-}
-
local LUA_META_HEADER = {
'--- @meta _',
'-- THIS FILE IS GENERATED',
@@ -134,22 +87,6 @@ local OPTION_TYPES = {
string = 'string',
}
-local API_TYPES = {
- Window = 'integer',
- Tabpage = 'integer',
- Buffer = 'integer',
- Boolean = 'boolean',
- Object = 'any',
- Integer = 'integer',
- String = 'string',
- Array = 'any[]',
- LuaRef = 'function',
- Dict = 'table<string,any>',
- Float = 'number',
- HLGroupID = 'integer|string',
- void = '',
-}
-
--- @param s string
--- @return string
local function luaescape(s)
@@ -166,66 +103,6 @@ local function split(x, sep)
return vim.split(x, sep or '\n', { plain = true })
end
---- Convert an API type to Lua
---- @param t string
---- @return string
-local function api_type(t)
- if vim.startswith(t, '*') then
- return api_type(t:sub(2)) .. '?'
- end
-
- local as0 = t:match('^ArrayOf%((.*)%)')
- if as0 then
- local as = split(as0, ', ')
- local a = api_type(as[1])
- local count = tonumber(as[2])
- if count then
- return fmt('[%s]', a:rep(count, ', '))
- else
- return a .. '[]'
- end
- end
-
- local d = t:match('^Dict%((.*)%)')
- if d then
- return 'vim.api.keyset.' .. d
- end
-
- local d0 = t:match('^DictOf%((.*)%)')
- if d0 then
- return 'table<string,' .. api_type(d0) .. '>'
- end
-
- local u = t:match('^Union%((.*)%)')
- if u then
- local us = vim.split(u, ',%s*')
- return table.concat(vim.tbl_map(api_type, us), '|')
- end
-
- local l = t:match('^LuaRefOf%((.*)%)')
- if l then
- --- @type string
- l = l:gsub('%s+', ' ')
- --- @type string?, string?
- local as, r = l:match('%((.*)%),%s*(.*)')
- if not as then
- --- @type string
- as = assert(l:match('%((.*)%)'))
- end
-
- local as1 = {} --- @type string[]
- for a in vim.gsplit(as, ',%s') do
- local a1 = vim.split(a, '%s+', { trimempty = true })
- local nm = a1[2]:gsub('%*(.*)$', '%1?')
- as1[#as1 + 1] = nm .. ': ' .. api_type(a1[1])
- end
-
- return fmt('fun(%s)%s', table.concat(as1, ', '), r and ': ' .. api_type(r) or '')
- end
-
- return API_TYPES[t] or t
-end
-
--- @param f string
--- @param params [string,string][]|true
--- @return string
@@ -321,13 +198,11 @@ local function get_api_meta()
sees[#sees + 1] = see.desc
end
- local pty_overrides = LUA_API_PARAM_OVERRIDES[fun.name] or {}
-
local params = {} --- @type [string,string][]
for _, p in ipairs(fun.params) do
params[#params + 1] = {
p.name,
- api_type(pty_overrides[p.name] or p.type),
+ p.type,
not deprecated and p.desc or nil,
}
end
@@ -338,7 +213,7 @@ local function get_api_meta()
params = params,
notes = notes,
see = sees,
- returns = api_type(fun.returns[1].type),
+ returns = fun.returns[1].type,
deprecated = deprecated,
}
@@ -429,10 +304,9 @@ local function render_api_meta(_f, fun, write)
end
end
- if fun.returns ~= '' then
+ if fun.returns ~= 'nil' then
local ret_desc = fun.returns_desc and ' # ' .. fun.returns_desc or ''
- local ret = LUA_API_RETURN_OVERRIDES[fun.name] or fun.returns
- write(util.prefix_lines('--- ', '@return ' .. ret .. ret_desc))
+ write(util.prefix_lines('--- ', '@return ' .. fun.returns .. ret_desc))
end
local param_str = table.concat(param_names, ', ')
@@ -450,10 +324,9 @@ local function get_api_keysets_meta()
local keysets = metadata.keysets
for _, k in ipairs(keysets) do
- local pty_overrides = LUA_API_KEYSET_OVERRIDES[k.name] or {}
local params = {}
for _, key in ipairs(k.keys) do
- local pty = pty_overrides[key] or k.types[key] or 'any'
+ local pty = k.types[key] or 'any'
table.insert(params, { key .. '?', api_type(pty) })
end
ret[k.name] = {
diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua
@@ -38,8 +38,6 @@ local INDENTATION = 4
--- List of files/directories for doxygen to read, relative to `base_dir`.
--- @field files string[]
---
---- @field exclude_types? true
----
--- Section name overrides. Key: filename (e.g., vim.c)
--- @field section_name? table<string,string>
---
@@ -119,7 +117,6 @@ local config = {
'autocmd.c',
'ui.c',
},
- exclude_types = true,
fn_name_pat = 'nvim_.*',
files = { 'src/nvim/api' },
section_name = {
@@ -550,9 +547,8 @@ end
--- @param xs (nvim.luacats.parser.param|nvim.luacats.parser.field)[]
--- @param generics? table<string,string>
--- @param classes? table<string,nvim.luacats.parser.class>
---- @param exclude_types? true
--- @param cfg nvim.gen_vimdoc.Config
-local function render_fields_or_params(xs, generics, classes, exclude_types, cfg)
+local function render_fields_or_params(xs, generics, classes, cfg)
local ret = {} --- @type string[]
xs = vim.tbl_filter(should_render_field_or_param, xs)
@@ -562,9 +558,6 @@ local function render_fields_or_params(xs, generics, classes, exclude_types, cfg
if p.type or p.desc then
indent = math.max(indent, #p.name + 3)
end
- if exclude_types then
- p.type = nil
- end
end
for _, p in ipairs(xs) do
@@ -627,7 +620,7 @@ local function render_class(class, classes, cfg)
table.insert(ret, md_to_vimdoc(class.desc, INDENTATION, INDENTATION, TEXT_WIDTH))
end
- local fields_txt = render_fields_or_params(class.fields, nil, classes, nil, cfg)
+ local fields_txt = render_fields_or_params(class.fields, nil, classes, cfg)
if not fields_txt:match('^%s*$') then
table.insert(ret, '\n Fields: ~\n')
table.insert(ret, fields_txt)
@@ -692,15 +685,12 @@ end
--- @param returns nvim.luacats.parser.return[]
--- @param generics? table<string,string>
--- @param classes? table<string,nvim.luacats.parser.class>
---- @param exclude_types boolean
-local function render_returns(returns, generics, classes, exclude_types)
+--- @return string?
+local function render_returns(returns, generics, classes)
local ret = {} --- @type string[]
- returns = vim.deepcopy(returns)
- if exclude_types then
- for _, r in ipairs(returns) do
- r.type = nil
- end
+ if #returns == 1 and returns[1].type == 'nil' then
+ return
end
if #returns > 1 then
@@ -720,7 +710,7 @@ local function render_returns(returns, generics, classes, exclude_types)
blk[#blk + 1] = rnm
blk[#blk + 1] = desc
- table.insert(ret, md_to_vimdoc(table.concat(blk, ' '), 8, 8, TEXT_WIDTH, true))
+ ret[#ret + 1] = md_to_vimdoc(table.concat(blk, ' '), 8, 8, TEXT_WIDTH, true)
end
return table.concat(ret)
@@ -788,8 +778,7 @@ local function render_fun(fun, classes, cfg)
end
if fun.params and #fun.params > 0 then
- local param_txt =
- render_fields_or_params(fun.params, fun.generics, classes, cfg.exclude_types, cfg)
+ local param_txt = render_fields_or_params(fun.params, fun.generics, classes, cfg)
if not param_txt:match('^%s*$') then
table.insert(ret, '\n Parameters: ~\n')
ret[#ret + 1] = param_txt
@@ -804,8 +793,8 @@ local function render_fun(fun, classes, cfg)
end
if fun.returns then
- local txt = render_returns(fun.returns, fun.generics, classes, cfg.exclude_types)
- if not txt:match('^%s*$') then
+ local txt = render_returns(fun.returns, fun.generics, classes)
+ if txt and not txt:match('^%s*$') then
table.insert(ret, '\n')
ret[#ret + 1] = txt
end
diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
@@ -90,7 +90,8 @@ static int64_t next_autocmd_id = 1;
/// - once: (boolean) whether the autocommand is only run once.
/// - pattern: (string) the autocommand pattern.
/// If the autocommand is buffer local |autocmd-buffer-local|:
-Array nvim_get_autocmds(Dict(get_autocmds) *opts, Arena *arena, Error *err)
+ArrayOf(DictAs(get_autocmds__ret)) nvim_get_autocmds(Dict(get_autocmds) *opts, Arena *arena,
+ Error *err)
FUNC_API_SINCE(9)
{
ArrayBuilder autocmd_list = KV_INITIAL_VALUE;
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
@@ -856,7 +856,8 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
/// @param[out] err Error details, if any
/// @returns Array of |maparg()|-like dictionaries describing mappings.
/// The "buffer" key holds the associated buffer id.
-ArrayOf(Dict) nvim_buf_get_keymap(Buffer buffer, String mode, Arena *arena, Error *err)
+ArrayOf(DictAs(get_keymap)) nvim_buf_get_keymap(Buffer buffer, String mode, Arena *arena,
+ Error *err)
FUNC_API_SINCE(3)
{
buf_T *buf = find_buffer_by_handle(buffer, err);
diff --git a/src/nvim/api/command.c b/src/nvim/api/command.c
@@ -927,6 +927,8 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
}
}
+// uncrustify:off
+
/// Creates a global |user-commands| command.
///
/// For Lua usage see |lua-guide-commands-create|.
@@ -968,13 +970,18 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
/// - force: (boolean, default true) Override any previous definition.
/// - preview: (function) Preview callback for 'inccommand' |:command-preview|
/// @param[out] err Error details, if any.
-void nvim_create_user_command(uint64_t channel_id, String name, Object command,
- Dict(user_command) *opts, Error *err)
+void nvim_create_user_command(uint64_t channel_id,
+ String name,
+ Union(String, LuaRefOf((DictAs(create_user_command__command_args) args))) command,
+ Dict(user_command) *opts,
+ Error *err)
FUNC_API_SINCE(9)
{
create_user_command(channel_id, name, command, opts, 0, err);
}
+// uncrustify:on
+
/// Delete a user-defined command.
///
/// @param name Name of the command to delete.
@@ -1045,8 +1052,8 @@ void nvim_buf_del_user_command(Buffer buffer, String name, Error *err)
api_set_error(err, kErrorTypeException, "Invalid command (not found): %s", name.data);
}
-void create_user_command(uint64_t channel_id, String name, Object command, Dict(user_command) *opts,
- int flags, Error *err)
+void create_user_command(uint64_t channel_id, String name, Union(String, LuaRef) command,
+ Dict(user_command) *opts, int flags, Error *err)
{
uint32_t argt = 0;
int64_t def = -1;
@@ -1260,7 +1267,7 @@ err:
/// @param[out] err Error details, if any.
///
/// @returns Map of maps describing commands.
-Dict nvim_get_commands(Dict(get_commands) *opts, Arena *arena, Error *err)
+DictOf(DictAs(command_info)) nvim_get_commands(Dict(get_commands) *opts, Arena *arena, Error *err)
FUNC_API_SINCE(4)
{
return nvim_buf_get_commands(-1, opts, arena, err);
@@ -1273,7 +1280,8 @@ Dict nvim_get_commands(Dict(get_commands) *opts, Arena *arena, Error *err)
/// @param[out] err Error details, if any.
///
/// @returns Map of maps describing commands.
-Dict nvim_buf_get_commands(Buffer buffer, Dict(get_commands) *opts, Arena *arena, Error *err)
+DictAs(command_info) nvim_buf_get_commands(Buffer buffer, Dict(get_commands) *opts, Arena *arena,
+ Error *err)
FUNC_API_SINCE(4)
{
bool global = (buffer == -1);
diff --git a/src/nvim/api/deprecated.c b/src/nvim/api/deprecated.c
@@ -603,7 +603,7 @@ static int64_t convert_index(int64_t index)
/// @param name Option name
/// @param[out] err Error details, if any
/// @return Option Information
-Dict nvim_get_option_info(String name, Arena *arena, Error *err)
+DictAs(get_option_info) nvim_get_option_info(String name, Arena *arena, Error *err)
FUNC_API_SINCE(7)
FUNC_API_DEPRECATED_SINCE(11)
{
diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c
@@ -75,7 +75,7 @@ Integer nvim_create_namespace(String name)
/// Gets existing, non-anonymous |namespace|s.
///
/// @return dict that maps from names to namespace ids.
-Dict nvim_get_namespaces(Arena *arena)
+DictOf(Integer) nvim_get_namespaces(Arena *arena)
FUNC_API_SINCE(5)
{
Dict retval = arena_dict(arena, map_size(&namespace_ids));
@@ -201,9 +201,9 @@ static Array extmark_to_array(MTPair extmark, bool id, bool add_dict, bool hl_na
/// @param[out] err Error details, if any
/// @return 0-indexed (row, col) tuple or empty list () if extmark id was
/// absent
-ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
- Integer id, Dict(get_extmark) *opts,
- Arena *arena, Error *err)
+Tuple(Integer, Integer, *DictAs(extmark_details))
+nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id, Integer id, Dict(get_extmark) * opts,
+ Arena *arena, Error *err)
FUNC_API_SINCE(7)
{
Array rv = ARRAY_DICT_INIT;
@@ -287,8 +287,10 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
/// - type: Filter marks by type: "highlight", "sign", "virt_text" and "virt_lines"
/// @param[out] err Error details, if any
/// @return List of `[extmark_id, row, col]` tuples in "traversal order".
-Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object end,
- Dict(get_extmarks) *opts, Arena *arena, Error *err)
+ArrayOf(DictAs(get_extmark_item)) nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start,
+ Object end,
+ Dict(get_extmarks) *opts, Arena *arena,
+ Error *err)
FUNC_API_SINCE(7)
{
Array rv = ARRAY_DICT_INIT;
diff --git a/src/nvim/api/keysets_defs.h b/src/nvim/api/keysets_defs.h
@@ -116,9 +116,9 @@ typedef struct {
Float col;
Integer width;
Integer height;
- String anchor;
- String relative;
- String split;
+ Enum("NW", "NE", "SW", "SE") anchor;
+ Enum("cursor", "editor", "laststatus", "mouse", "tabline", "win") relative;
+ Enum("left", "right", "above", "below") split;
Window win;
ArrayOf(Integer) bufpos;
Boolean external;
@@ -126,12 +126,12 @@ typedef struct {
Boolean mouse;
Boolean vertical;
Integer zindex;
- Object border;
+ Union(ArrayOf(String), Enum("none", "single", "double", "rounded", "solid", "shadow")) border;
Object title;
- String title_pos;
+ Enum("center", "left", "right") title_pos;
Object footer;
- String footer_pos;
- String style;
+ Enum("center", "left", "right") footer_pos;
+ Enum("minimal") style;
Boolean noautocmd;
Boolean fixed;
Boolean hide;
@@ -244,7 +244,7 @@ typedef struct {
typedef struct {
OptionalKeys is_set__create_autocmd_;
Buffer buffer;
- Object callback;
+ Union(String, LuaRefOf((DictAs(create_autocmd__callback_args) args), *Boolean)) callback;
String command;
String desc;
Union(Integer, String) group;
@@ -279,15 +279,15 @@ typedef struct {
typedef struct {
OptionalKeys is_set__cmd_;
String cmd;
- Array range;
+ ArrayOf(Integer) range;
Integer count;
String reg;
Boolean bang;
ArrayOf(String) args;
- Dict magic;
- Dict mods;
- Union(Integer, String) nargs;
- String addr;
+ DictAs(cmd__magic) magic;
+ DictAs(cmd__mods) mods;
+ Union(Integer, Enum("?", "+", "*")) nargs;
+ Enum("line", "arg", "buf", "load", "win", "tab", "qf", "none", "?") addr;
String nextcmd;
} Dict(cmd);
diff --git a/src/nvim/api/options.c b/src/nvim/api/options.c
@@ -308,7 +308,8 @@ Dict nvim_get_all_options_info(Arena *arena, Error *err)
/// Implies {scope} is "local".
/// @param[out] err Error details, if any
/// @return Option Information
-Dict nvim_get_option_info2(String name, Dict(option) *opts, Arena *arena, Error *err)
+DictAs(get_option_info) nvim_get_option_info2(String name, Dict(option) *opts, Arena *arena,
+ Error *err)
FUNC_API_SINCE(11)
{
OptIndex opt_idx = 0;
diff --git a/src/nvim/api/private/defs.h b/src/nvim/api/private/defs.h
@@ -18,11 +18,14 @@
#ifdef INCLUDE_GENERATED_DECLARATIONS
# define ArrayOf(...) Array
# define DictOf(...) Dict
+# define DictAs(name) Dict
# define Dict(name) KeyDict_##name
+# define Enum(...) String
# define DictHash(name) KeyDict_##name##_get_field
# define DictKey(name)
# define LuaRefOf(...) LuaRef
# define Union(...) Object
+# define Tuple(...) Array
# include "api/private/defs.h.inline.generated.h"
#endif
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
@@ -115,7 +115,7 @@ Integer nvim_get_hl_id_by_name(String name)
/// @param[out] err Error details, if any.
/// @return Highlight groups as a map from group name to a highlight definition map as in |nvim_set_hl()|,
/// or only a single highlight definition map if requested by name or id.
-Dict nvim_get_hl(Integer ns_id, Dict(get_highlight) *opts, Arena *arena, Error *err)
+DictAs(get_hl_info) nvim_get_hl(Integer ns_id, Dict(get_highlight) *opts, Arena *arena, Error *err)
FUNC_API_SINCE(11)
{
return ns_get_hl_defs((NS)ns_id, opts, arena, err);
@@ -607,7 +607,8 @@ String nvim__get_lib_dir(void)
/// @param all whether to return all matches or only the first
/// @param opts is_lua: only search Lua subdirs
/// @return list of absolute paths to the found files
-ArrayOf(String) nvim__get_runtime(Array pat, Boolean all, Dict(runtime) *opts, Arena *arena,
+ArrayOf(String) nvim__get_runtime(ArrayOf(String) pat, Boolean all, Dict(runtime) *opts,
+ Arena *arena,
Error *err)
FUNC_API_SINCE(8)
FUNC_API_FAST
@@ -761,7 +762,8 @@ void nvim_set_vvar(String name, Object value, Error *err)
/// - kind: Set the |ui-messages| kind with which this message will be emitted.
/// - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log`
/// will write the message to the "log" file instead of standard output.
-void nvim_echo(Array chunks, Boolean history, Dict(echo_opts) *opts, Error *err)
+void nvim_echo(ArrayOf(Tuple(String, HLGroupID)) chunks, Boolean history, Dict(echo_opts) *opts,
+ Error *err)
FUNC_API_SINCE(7)
{
HlMessage hl_msg = parse_hl_msg(chunks, opts->err, err);
@@ -1320,10 +1322,10 @@ Integer nvim_get_color_by_name(String name)
/// (e.g. 65535).
///
/// @return Map of color names and RGB values.
-Dict nvim_get_color_map(Arena *arena)
+DictOf(Integer) nvim_get_color_map(Arena *arena)
FUNC_API_SINCE(1)
{
- Dict colors = arena_dict(arena, ARRAY_SIZE(color_name_table));
+ DictOf(Integer) colors = arena_dict(arena, ARRAY_SIZE(color_name_table));
for (int i = 0; color_name_table[i].name != NULL; i++) {
PUT_C(colors, color_name_table[i].name, INTEGER_OBJ(color_name_table[i].color));
@@ -1406,7 +1408,7 @@ Object nvim_load_context(Dict dict, Error *err)
/// "blocking" is true if Nvim is waiting for input.
///
/// @returns Dict { "mode": String, "blocking": Boolean }
-Dict nvim_get_mode(Arena *arena)
+DictAs(get_mode) nvim_get_mode(Arena *arena)
FUNC_API_SINCE(2) FUNC_API_FAST
{
Dict rv = arena_dict(arena, 2);
@@ -1425,7 +1427,7 @@ Dict nvim_get_mode(Arena *arena)
/// @param mode Mode short-name ("n", "i", "v", ...)
/// @returns Array of |maparg()|-like dictionaries describing mappings.
/// The "buffer" key is always zero.
-ArrayOf(Dict) nvim_get_keymap(String mode, Arena *arena)
+ArrayOf(DictAs(get_keymap)) nvim_get_keymap(String mode, Arena *arena)
FUNC_API_SINCE(3)
{
return keymap_array(mode, NULL, arena);
@@ -1487,7 +1489,7 @@ void nvim_del_keymap(uint64_t channel_id, String mode, String lhs, Error *err)
/// 1 is the |api-metadata| map (Dict).
///
/// @returns 2-tuple `[{channel-id}, {api-metadata}]`
-Array nvim_get_api_info(uint64_t channel_id, Arena *arena)
+ArrayOf(Object, 2) nvim_get_api_info(uint64_t channel_id, Arena *arena)
FUNC_API_SINCE(1) FUNC_API_FAST FUNC_API_REMOTE_ONLY
{
Array rv = arena_array(arena, 2);
@@ -1624,7 +1626,7 @@ Dict nvim_get_chan_info(uint64_t channel_id, Integer chan, Arena *arena, Error *
///
/// @returns Array of Dictionaries, each describing a channel with
/// the format specified at |nvim_get_chan_info()|.
-Array nvim_list_chans(Arena *arena)
+ArrayOf(Dict) nvim_list_chans(Arena *arena)
FUNC_API_SINCE(4)
{
return channel_all_info(arena);
@@ -1715,7 +1717,7 @@ Dict nvim__stats(Arena *arena)
/// - "rgb" true if the UI uses RGB colors (false implies |cterm-colors|)
/// - "ext_..." Requested UI extensions, see |ui-option|
/// - "chan" |channel-id| of remote UI
-Array nvim_list_uis(Arena *arena)
+ArrayOf(Dict) nvim_list_uis(Arena *arena)
FUNC_API_SINCE(4)
{
return ui_array(arena);
@@ -1916,7 +1918,8 @@ Boolean nvim_del_mark(String name, Error *err)
/// not set.
/// @see |nvim_buf_set_mark()|
/// @see |nvim_del_mark()|
-Array nvim_get_mark(String name, Dict(empty) *opts, Arena *arena, Error *err)
+Tuple(Integer, Integer, Buffer, String) nvim_get_mark(String name, Dict(empty) *opts, Arena *arena,
+ Error *err)
FUNC_API_SINCE(8)
{
Array rv = ARRAY_DICT_INIT;
@@ -2001,7 +2004,8 @@ Array nvim_get_mark(String name, Dict(empty) *opts, Arena *arena, Error *err)
/// - start: (number) Byte index (0-based) of first character that uses the highlight.
/// - group: (string) Deprecated. Use `groups` instead.
/// - groups: (array) Names of stacked highlight groups (highest priority last).
-Dict nvim_eval_statusline(String str, Dict(eval_statusline) *opts, Arena *arena, Error *err)
+DictAs(eval_statusline_ret) nvim_eval_statusline(String str, Dict(eval_statusline) *opts,
+ Arena *arena, Error *err)
FUNC_API_SINCE(8) FUNC_API_FAST
{
Dict result = ARRAY_DICT_INIT;
@@ -2188,7 +2192,7 @@ void nvim_error_event(uint64_t channel_id, Integer lvl, String data)
/// @return Dict containing these keys:
/// - winid: (number) floating window id
/// - bufnr: (number) buffer id in floating window
-Dict nvim__complete_set(Integer index, Dict(complete_set) *opts, Arena *arena, Error *err)
+DictOf(Float) nvim__complete_set(Integer index, Dict(complete_set) *opts, Arena *arena, Error *err)
{
Dict rv = arena_dict(arena, 2);
if ((get_cot_flags() & kOptCotFlagPopup) == 0) {
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
@@ -500,7 +500,8 @@ void nvim_win_set_hl_ns(Window window, Integer ns_id, Error *err)
/// height is reached. 0 if "end_row" is a closed fold.
///
/// @see |virtcol()| for text width.
-Dict nvim_win_text_height(Window window, Dict(win_text_height) *opts, Arena *arena, Error *err)
+DictAs(win_text_height_ret) nvim_win_text_height(Window window, Dict(win_text_height) *opts,
+ Arena *arena, Error *err)
FUNC_API_SINCE(12)
{
Dict rv = arena_dict(arena, 2);
diff --git a/test/functional/api/version_spec.lua b/test/functional/api/version_spec.lua
@@ -63,12 +63,14 @@ describe('api metadata', function()
-- Dictionary was renamed to Dict. That doesn't break back-compat because clients don't actually
-- use the `return_type` field (evidence: "ArrayOf(…)" didn't break clients).
f.return_type = f.return_type:gsub('Dictionary', 'Dict')
+ f.return_type = f.return_type:gsub('^ArrayOf%(.*', 'Array')
f.deprecated_since = nil
for idx, _ in ipairs(f.parameters) do
-- Dictionary was renamed to Dict. Doesn't break back-compat because clients don't actually
-- use the `parameters` field of API metadata (evidence: "ArrayOf(…)" didn't break clients).
f.parameters[idx][1] = f.parameters[idx][1]:gsub('Dictionary', 'Dict')
+ f.parameters[idx][1] = f.parameters[idx][1]:gsub('ArrayOf%(.*', 'Array')
f.parameters[idx][2] = '' -- Remove parameter name.
end
