diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 470722a959..1ab6873376 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -3799,7 +3799,8 @@ nvim_clear_autocmds({opts}) *nvim_clear_autocmds()* Parameters: ~ • {opts} (`vim.api.keyset.clear_autocmds`) Parameters - • event: (string|table) Examples: + • event: (vim.api.keyset.events|vim.api.keyset.events[]) + Examples: • event: "pat1" • event: { "pat1" } • event: { "pat1", "pat2", "pat3" } @@ -3871,8 +3872,8 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* Since: 0.7.0 Parameters: ~ - • {event} (`any`) (string|array) Event(s) that will trigger the handler - (`callback` or `command`). + • {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) Event(s) + that will trigger the handler (`callback` or `command`). • {opts} (`vim.api.keyset.create_autocmd`) Options dict: • group (string|integer) optional: autocommand group name or id to match against. @@ -3890,8 +3891,8 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* receives one argument, a table with these keys: *event-args* • id: (number) autocommand id - • event: (string) name of the triggered event - |autocmd-events| + • event: (vim.api.keyset.events) name of the triggered + event |autocmd-events| • group: (number|nil) autocommand group id, if any • file: (string) (not expanded to a full path) • match: (string) (expanded to a full path) @@ -3965,7 +3966,8 @@ nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()* Since: 0.7.0 Parameters: ~ - • {event} (`any`) (String|Array) The event or events to execute + • {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) 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|. @@ -4010,8 +4012,8 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()* • buffer: (integer) Buffer number or list of buffer numbers for buffer local autocommands |autocmd-buflocal|. Cannot be used with {pattern} - • event: (string|table) event or events to match against - |autocmd-events|. + • event: (vim.api.keyset.events|vim.api.keyset.events[]) event + or events to match against |autocmd-events|. • id: (integer) Autocommand ID to match. • group: (string|table) the autocommand group name or id to match against. @@ -4029,7 +4031,7 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()* script function which is executed when this autocommand is triggered. • desc: (string) the autocommand description. - • event: (string) the autocommand event. + • event: (vim.api.keyset.events) the autocommand event. • id: (integer) the autocommand id (only when defined with the API). • group: (integer) the autocommand group id. • group_name: (string) the autocommand group name. diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 71d188921a..3177244e1a 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -830,7 +830,7 @@ function vim.api.nvim_chan_send(chan, data) end --- Clears all autocommands selected by {opts}. To delete autocmds see `nvim_del_autocmd()`. --- --- @param opts vim.api.keyset.clear_autocmds Parameters ---- - event: (string|table) +--- - event: (vim.api.keyset.events|vim.api.keyset.events[]) --- Examples: --- - event: "pat1" --- - event: { "pat1" } @@ -939,7 +939,7 @@ function vim.api.nvim_create_augroup(name, opts) end --- --- @see `:help autocommand` --- @see vim.api.nvim_del_autocmd ---- @param event any (string|array) Event(s) that will trigger the handler (`callback` or `command`). +--- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) that will trigger the handler (`callback` or `command`). --- @param 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 literally `autocmd-pattern`. @@ -951,7 +951,7 @@ function vim.api.nvim_create_augroup(name, opts) end --- value (not `false` or `nil`) to delete the autocommand, and receives one argument, a --- table with these keys: [event-args]() --- - id: (number) autocommand id ---- - event: (string) name of the triggered event `autocmd-events` +--- - event: (vim.api.keyset.events) name of the triggered event `autocmd-events` --- - group: (number|nil) autocommand group id, if any --- - file: (string) [] (not expanded to a full path) --- - match: (string) [] (expanded to a full path) @@ -1176,7 +1176,7 @@ function vim.api.nvim_exec2(src, opts) end --- Execute all autocommands for {event} that match the corresponding --- {opts} `autocmd-execute`. --- @see `:help :doautocmd` ---- @param event any (String|Array) The event or events to execute +--- @param event vim.api.keyset.events|vim.api.keyset.events[] The event or events to execute --- @param 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`. @@ -1249,7 +1249,8 @@ function vim.api.nvim_get_all_options_info() end --- @param 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} ---- - event: (string|table) event or events to match against `autocmd-events`. +--- - event: (vim.api.keyset.events|vim.api.keyset.events[]) +--- event or events to match against `autocmd-events`. --- - id: (integer) Autocommand ID to match. --- - group: (string|table) the autocommand group name or id to match against. --- - pattern: (string|table) pattern or patterns to match against `autocmd-pattern`. @@ -1262,7 +1263,7 @@ function vim.api.nvim_get_all_options_info() end --- - callback: (function|string|nil): Lua function or name of a Vim script function --- which is executed when this autocommand is triggered. --- - desc: (string) the autocommand description. ---- - event: (string) the autocommand event. +--- - event: (vim.api.keyset.events) the autocommand event. --- - id: (integer) the autocommand id (only when defined with the API). --- - group: (integer) the autocommand group id. --- - group_name: (string) the autocommand group name. diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index 0ddc5fa3b1..64a8b29fea 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -18,7 +18,7 @@ error('Cannot require a meta file') --- @class vim.api.keyset.clear_autocmds --- @field buffer? integer ---- @field event? string|string[] +--- @field event? vim.api.keyset.events|vim.api.keyset.events[] --- @field group? integer|string --- @field pattern? string|string[] @@ -77,6 +77,148 @@ error('Cannot require a meta file') --- @class vim.api.keyset.create_augroup --- @field clear? boolean +--- @alias vim.api.keyset.events +--- |'BufAdd' +--- |'BufCreate' +--- |'BufDelete' +--- |'BufEnter' +--- |'BufFilePost' +--- |'BufFilePre' +--- |'BufHidden' +--- |'BufLeave' +--- |'BufModifiedSet' +--- |'BufNew' +--- |'BufNewFile' +--- |'BufRead' +--- |'BufReadCmd' +--- |'BufReadPost' +--- |'BufReadPre' +--- |'BufUnload' +--- |'BufWinEnter' +--- |'BufWinLeave' +--- |'BufWipeout' +--- |'BufWrite' +--- |'BufWriteCmd' +--- |'BufWritePost' +--- |'BufWritePre' +--- |'ChanInfo' +--- |'ChanOpen' +--- |'CmdUndefined' +--- |'CmdlineChanged' +--- |'CmdlineEnter' +--- |'CmdlineLeave' +--- |'CmdlineLeavePre' +--- |'CmdwinEnter' +--- |'CmdwinLeave' +--- |'ColorScheme' +--- |'ColorSchemePre' +--- |'CompleteChanged' +--- |'CompleteDone' +--- |'CompleteDonePre' +--- |'CursorHold' +--- |'CursorHoldI' +--- |'CursorMoved' +--- |'CursorMovedC' +--- |'CursorMovedI' +--- |'DiagnosticChanged' +--- |'DiffUpdated' +--- |'DirChanged' +--- |'DirChangedPre' +--- |'EncodingChanged' +--- |'ExitPre' +--- |'FileAppendCmd' +--- |'FileAppendPost' +--- |'FileAppendPre' +--- |'FileChangedRO' +--- |'FileChangedShell' +--- |'FileChangedShellPost' +--- |'FileEncoding' +--- |'FileReadCmd' +--- |'FileReadPost' +--- |'FileReadPre' +--- |'FileType' +--- |'FileWriteCmd' +--- |'FileWritePost' +--- |'FileWritePre' +--- |'FilterReadPost' +--- |'FilterReadPre' +--- |'FilterWritePost' +--- |'FilterWritePre' +--- |'FocusGained' +--- |'FocusLost' +--- |'FuncUndefined' +--- |'GUIEnter' +--- |'GUIFailed' +--- |'InsertChange' +--- |'InsertCharPre' +--- |'InsertEnter' +--- |'InsertLeave' +--- |'InsertLeavePre' +--- |'LspAttach' +--- |'LspDetach' +--- |'LspNotify' +--- |'LspProgress' +--- |'LspRequest' +--- |'LspTokenUpdate' +--- |'MenuPopup' +--- |'ModeChanged' +--- |'OptionSet' +--- |'PackChanged' +--- |'PackChangedPre' +--- |'QuickFixCmdPost' +--- |'QuickFixCmdPre' +--- |'QuitPre' +--- |'RecordingEnter' +--- |'RecordingLeave' +--- |'RemoteReply' +--- |'SafeState' +--- |'SearchWrapped' +--- |'SessionLoadPost' +--- |'SessionWritePost' +--- |'ShellCmdPost' +--- |'ShellFilterPost' +--- |'Signal' +--- |'SourceCmd' +--- |'SourcePost' +--- |'SourcePre' +--- |'SpellFileMissing' +--- |'StdinReadPost' +--- |'StdinReadPre' +--- |'SwapExists' +--- |'Syntax' +--- |'TabClosed' +--- |'TabEnter' +--- |'TabLeave' +--- |'TabNew' +--- |'TabNewEntered' +--- |'TermChanged' +--- |'TermClose' +--- |'TermEnter' +--- |'TermLeave' +--- |'TermOpen' +--- |'TermRequest' +--- |'TermResponse' +--- |'TextChanged' +--- |'TextChangedI' +--- |'TextChangedP' +--- |'TextChangedT' +--- |'TextYankPost' +--- |'UIEnter' +--- |'UILeave' +--- |'User' +--- |'VimEnter' +--- |'VimLeave' +--- |'VimLeavePre' +--- |'VimResized' +--- |'VimResume' +--- |'VimSuspend' +--- |'WinClosed' +--- |'WinEnter' +--- |'WinLeave' +--- |'WinNew' +--- |'WinResized' +--- |'WinScrolled' + --- @class vim.api.keyset.create_autocmd --- @field buffer? integer --- @field callback? string|fun(args: vim.api.keyset.create_autocmd.callback_args): boolean? @@ -114,7 +256,7 @@ error('Cannot require a meta file') --- @field output? boolean --- @class vim.api.keyset.get_autocmds ---- @field event? string|string[] +--- @field event? vim.api.keyset.events|vim.api.keyset.events[] --- @field group? integer|string --- @field pattern? string|string[] --- @field buffer? integer|integer[] diff --git a/src/gen/cdoc_parser.lua b/src/gen/cdoc_parser.lua index a3b40fd112..beeb2a3a8f 100644 --- a/src/gen/cdoc_parser.lua +++ b/src/gen/cdoc_parser.lua @@ -141,8 +141,12 @@ 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 = api_type(p[1]) } + local event_type = 'vim.api.keyset.events|vim.api.keyset.events[]' + local event = (item.name == 'nvim_create_autocmd' or item.name == 'nvim_exec_autocmds') + and p[2] == 'event' + local param = { name = p[2], type = event and event_type or api_type(p[1]) } local added = false + for _, cp in ipairs(cur_obj.params) do if cp.name == param.name then cp.type = param.type diff --git a/src/gen/gen_eval_files.lua b/src/gen/gen_eval_files.lua index 0752ce0e4d..4ac4d754da 100755 --- a/src/gen/gen_eval_files.lua +++ b/src/gen/gen_eval_files.lua @@ -322,12 +322,16 @@ local function get_api_keysets_meta() --- @type {name: string, keys: string[], types: table}[] local keysets = metadata.keysets + local event_type = 'vim.api.keyset.events|vim.api.keyset.events[]' for _, k in ipairs(keysets) do local params = {} for _, key in ipairs(k.keys) do local pty = k.types[key] or 'any' - table.insert(params, { key .. '?', api_type(pty) }) + table.insert(params, { + key .. '?', + k.name:find('autocmd') and key == 'event' and event_type or api_type(pty), + }) end ret[k.name] = { signature = 'NA', @@ -346,6 +350,16 @@ end local function render_api_keyset_meta(_f, fun, write) if string.sub(fun.name, 1, 1) == '_' then return -- not exported + elseif fun.name == 'create_autocmd' then + local events = vim.deepcopy(require('nvim.auevents')) + for event in pairs(events.aliases) do + events.events[event] = true + end + write('') + write('--- @alias vim.api.keyset.events') + for event in vim.spairs(events.events) do + write(("--- |'%s'"):format(event)) + end end write('') write('--- @class vim.api.keyset.' .. fun.name) diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c index ef1168b8e5..f215b0c1c8 100644 --- a/src/nvim/api/autocmd.c +++ b/src/nvim/api/autocmd.c @@ -70,7 +70,8 @@ static int64_t next_autocmd_id = 1; /// @param opts 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} -/// - event: (string|table) event or events to match against |autocmd-events|. +/// - event: (vim.api.keyset.events|vim.api.keyset.events[]) +/// event or events to match against |autocmd-events|. /// - id: (integer) Autocommand ID to match. /// - group: (string|table) the autocommand group name or id to match against. /// - pattern: (string|table) pattern or patterns to match against |autocmd-pattern|. @@ -83,7 +84,7 @@ static int64_t next_autocmd_id = 1; /// - callback: (function|string|nil): Lua function or name of a Vim script function /// which is executed when this autocommand is triggered. /// - desc: (string) the autocommand description. -/// - event: (string) the autocommand event. +/// - event: (vim.api.keyset.events) the autocommand event. /// - id: (integer) the autocommand id (only when defined with the API). /// - group: (integer) the autocommand group id. /// - group_name: (string) the autocommand group name. @@ -361,7 +362,7 @@ cleanup: /// pattern = vim.fn.expand('~') .. '/some/path/*.py' /// ``` /// -/// @param event (string|array) Event(s) that will trigger the handler (`callback` or `command`). +/// @param event Event(s) that will trigger the handler (`callback` or `command`). /// @param opts Options dict: /// - group (string|integer) optional: autocommand group name or id to match against. /// - pattern (string|array) optional: pattern(s) to match literally |autocmd-pattern|. @@ -373,7 +374,7 @@ cleanup: /// value (not `false` or `nil`) to delete the autocommand, and receives one argument, a /// table with these keys: [event-args]() /// - id: (number) autocommand id -/// - event: (string) name of the triggered event |autocmd-events| +/// - event: (vim.api.keyset.events) name of the triggered event |autocmd-events| /// - group: (number|nil) autocommand group id, if any /// - file: (string) [] (not expanded to a full path) /// - match: (string) [] (expanded to a full path) @@ -523,7 +524,7 @@ void nvim_del_autocmd(Integer id, Error *err) /// Clears all autocommands selected by {opts}. To delete autocmds see |nvim_del_autocmd()|. /// /// @param opts Parameters -/// - event: (string|table) +/// - event: (vim.api.keyset.events|vim.api.keyset.events[]) /// Examples: /// - event: "pat1" /// - event: { "pat1" } @@ -674,7 +675,7 @@ void nvim_del_augroup_by_name(String name, Error *err) /// Execute all autocommands for {event} that match the corresponding /// {opts} |autocmd-execute|. -/// @param event (String|Array) The event or events to execute +/// @param event The event or events to execute /// @param opts Dict of autocommand options: /// - group (string|integer) optional: the autocommand group name or /// id to match against. |autocmd-groups|.