diff options
| -rw-r--r-- | runtime/lua/vim/_meta/api.lua | 28 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/api_keysets_extra.lua | 167 | ||||
| -rwxr-xr-x | scripts/gen_eval_files.lua | 35 |
3 files changed, 211 insertions, 19 deletions
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 076aae7dbe..f9fa364158 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -320,7 +320,7 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- • details: Whether to include the details dict --- • hl_name: Whether to include highlight group name instead --- of id, true if omitted ---- @return integer[] +--- @return vim.api.keyset.get_extmark_item function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- Gets `extmarks` in "traversal order" from a `charwise` region defined by @@ -376,14 +376,14 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- if their start position is less than `start` --- • type: Filter marks by type: "highlight", "sign", --- "virt_text" and "virt_lines" ---- @return any[] +--- @return vim.api.keyset.get_extmark_item[] function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end --- Gets a list of buffer-local `mapping` definitions. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return table<string,any>[] +--- @return vim.api.keyset.keymap[] function vim.api.nvim_buf_get_keymap(buffer, mode) end --- Gets a line-range from the buffer. @@ -1153,7 +1153,7 @@ function vim.api.nvim_get_all_options_info() end --- • buffer: Buffer number or list of buffer numbers for buffer --- local autocommands `autocmd-buflocal`. Cannot be used with --- {pattern} ---- @return any[] +--- @return vim.api.keyset.get_autocmds.ret[] function vim.api.nvim_get_autocmds(opts) end --- Gets information about a channel. @@ -1179,7 +1179,7 @@ function vim.api.nvim_get_color_by_name(name) end --- Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values --- (e.g. 65535). --- ---- @return table<string,any> +--- @return table<string,integer> function vim.api.nvim_get_color_map() end --- Gets a map of global (non-buffer-local) Ex commands. @@ -1229,7 +1229,7 @@ function vim.api.nvim_get_current_win() end --- instead of effective definition `:hi-link`. --- • create: (boolean, default true) When highlight group --- doesn't exist create it. ---- @return table<string,any> +--- @return vim.api.keyset.hl_info function vim.api.nvim_get_hl(ns_id, opts) end --- @deprecated @@ -1264,7 +1264,7 @@ function vim.api.nvim_get_hl_ns(opts) end --- Gets a list of global (non-buffer-local) `mapping` definitions. --- --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return table<string,any>[] +--- @return vim.api.keyset.keymap[] function vim.api.nvim_get_keymap(mode) end --- Returns a `(row, col, buffer, buffername)` tuple representing the position @@ -1274,18 +1274,18 @@ function vim.api.nvim_get_keymap(mode) end --- --- @param name string Mark name --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. ---- @return any[] +--- @return vim.api.keyset.get_mark function vim.api.nvim_get_mark(name, opts) end --- Gets the current mode. `mode()` "blocking" is true if Nvim is waiting for --- input. --- ---- @return table<string,any> +--- @return vim.api.keyset.get_mode function vim.api.nvim_get_mode() end --- Gets existing, non-anonymous `namespace`s. --- ---- @return table<string,any> +--- @return table<string,integer> function vim.api.nvim_get_namespaces() end --- @deprecated @@ -1295,7 +1295,7 @@ function vim.api.nvim_get_option(name) end --- @deprecated --- @param name string ---- @return table<string,any> +--- @return vim.api.keyset.get_option_info function vim.api.nvim_get_option_info(name) end --- Gets the option information for one option from arbitrary buffer or window @@ -1325,7 +1325,7 @@ function vim.api.nvim_get_option_info(name) end --- • win: `window-ID`. Used for getting window local options. --- • buf: Buffer number. Used for getting buffer local options. --- Implies {scope} is "local". ---- @return table<string,any> +--- @return vim.api.keyset.get_option_info function vim.api.nvim_get_option_info2(name, opts) end --- Gets the value of an option. The behavior of this function matches that of @@ -1637,7 +1637,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 table<string,any> +--- @return vim.api.keyset.parse_cmd function vim.api.nvim_parse_cmd(str, opts) end --- Parse a Vimscript expression. @@ -1985,7 +1985,7 @@ function vim.api.nvim_win_get_buf(window) end --- `relative` is empty for normal windows. --- --- @param window integer Window handle, or 0 for current window ---- @return table<string,any> +--- @return vim.api.keyset.float_config function vim.api.nvim_win_get_config(window) end --- Gets the (1,0)-indexed, buffer-relative cursor position for a given window diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua new file mode 100644 index 0000000000..8e34ee534c --- /dev/null +++ b/runtime/lua/vim/_meta/api_keysets_extra.lua @@ -0,0 +1,167 @@ +--- @meta _ +error('Cannot require a meta file') + +--- Extra types we can't generate keysets for + +--- @class vim.api.keyset.extmark_details +--- @field ns_id integer +--- @field right_gravity boolean +--- +--- @field end_row? integer +--- @field end_col? integer +--- @field end_right_gravity? integer +--- +--- @field priority? integer +--- +--- @field undo_restore? false +--- @field invalidate? true +--- @field invalid? true +--- +--- @field hl_group? string +--- @field hl_eol? boolean +--- +--- @field conceal? boolean +--- @field spell? boolean +--- @field ui_watched? boolean +--- @field url? boolean +--- @field hl_mode? string +--- +--- @field virt_text? {[1]: string, [2]: string}[] +--- @field virt_text_hide? boolean +--- @field virt_text_repeat_linebreak? boolean +--- @field virt_text_win_col? integer +--- @field virt_text_pos? string +--- +--- @field virt_lines? {[1]: string, [2]: string}[][] +--- @field virt_lines_above? boolean +--- @field virt_lines_leftcol? boolean +--- +--- @field sign_text? string +--- @field sign_name? string +--- @field sign_hl_group? string +--- @field number_hl_group? string +--- @field line_hl_group? string +--- @field cursorline_hl_group? string + +--- @class vim.api.keyset.get_extmark_item +--- @field [1] integer row +--- @field [2] integer col +--- @field [3] 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 +--- @field group_name? integer +--- @field desc? string +--- @field event? string +--- @field command? string +--- @field callback? function +--- @field once? boolean +--- @field pattern? string +--- @field buflocal? boolean +--- @field buffer? integer + +--- @class vim.api.keyset.command_info +--- @field name string +--- @field definition string +--- @field script_id integer +--- @field bang boolean +--- @field bar boolean +--- @field register boolean +--- @field keepscript boolean +--- @field preview boolean +--- @field nargs string +--- @field complete? string +--- @field complete_arg? string +--- @field count? string +--- @field range? string +--- @field addr? string + +--- @class vim.api.keyset.hl_info.base +--- @field reverse? true +--- @field bold? true +--- @field italic? true +--- @field underline? true +--- @field undercurl? true +--- @field underdouble? true +--- @field underdotted? true +--- @field underdashed? true +--- @field standout? true +--- @field strikethrough? true +--- @field altfont? true +--- @field nocombine? true + +--- @class vim.api.keyset.hl_info.cterm : vim.api.keyset.hl_info.base +--- @field ctermfg? integer +--- @field ctermbg? integer +--- @field foreground? integer +--- @field background? integer + +--- @class vim.api.keyset.hl_info : vim.api.keyset.hl_info.base +--- @field fg? integer +--- @field bg? integer +--- @field sp? integer +--- @field default? true +--- @field link? string +--- @field blend? integer +--- @field cterm? vim.api.keyset.hl_info.cterm + +--- @class vim.api.keyset.get_mode +--- @field blocking boolean +--- @field mode string + +--- @class vim.api.keyset.get_option_info +--- @field name string +--- @field shortname string +--- @field scope 'buf'|'win'|'global' +--- @field global_local boolean +--- @field commalist boolean +--- @field flaglist boolean +--- @field was_set boolean +--- @field last_set_id integer +--- @field last_set_linenr integer +--- @field last_set_chan integer +--- @field type 'string'|'boolean'|'number' +--- @field default string|boolean|integer +--- @field allow_duplicates boolean + +--- @class vim.api.keyset.parse_cmd.mods +--- @field filter { force: boolean, pattern: string } +--- @field silent boolean +--- @field emsg_silent boolean +--- @field unsilent boolean +--- @field sandbox boolean +--- @field noautocmd boolean +--- @field tab integer +--- @field verbose integer +--- @field browse boolean +--- @field confirm boolean +--- @field hide boolean +--- @field keepalt boolean +--- @field keepjumps boolean +--- @field keepmarks boolean +--- @field keeppatterns boolean +--- @field lockmarks boolean +--- @field noswapfile boolean +--- @field vertical boolean +--- @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 diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua index 499c7dc9a7..78fc1c7d4f 100755 --- a/scripts/gen_eval_files.lua +++ b/scripts/gen_eval_files.lua @@ -1,3 +1,5 @@ +#!/usr/bin/env -S nvim -l + -- Generator for various vimdoc and Lua type files local DEP_API_METADATA = 'build/api_metadata.mpack' @@ -17,6 +19,31 @@ local DEP_API_DOC = 'runtime/doc/api.mpack' --- @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', + nvim_buf_get_extmarks = 'vim.api.keyset.get_extmark_item[]', + nvim_buf_get_keymap = 'vim.api.keyset.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.keymap[]', + nvim_get_mark = 'vim.api.keyset.get_mark', + + -- Can also return table<string,vim.api.keyset.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.hl_info> + nvim_get_hl = 'vim.api.keyset.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.float_config', +} + local LUA_META_HEADER = { '--- @meta _', '-- THIS FILE IS GENERATED', @@ -289,11 +316,9 @@ local function render_api_meta(_f, fun, write) end end if fun.returns ~= '' then - if fun.returns_desc then - write('--- @return ' .. fun.returns .. ' : ' .. fun.returns_desc) - else - write('--- @return ' .. fun.returns) - end + local ret_desc = fun.returns_desc and ' : ' .. fun.returns_desc or '' + local ret = LUA_API_RETURN_OVERRIDES[fun.name] or fun.returns + write('--- @return ' .. ret .. ret_desc) end local param_str = table.concat(param_names, ', ') |