commit d2098057a774167ed2552cb498530a01fc907a84
parent 34fbfa3586c2684b3601c9df3b73c20542545a47
Author: luukvbaal <luukvbaal@gmail.com>
Date: Sat, 12 Jul 2025 16:46:13 +0200
docs(autocmd): generate events enum type #34883
Diffstat:
6 files changed, 189 insertions(+), 25 deletions(-)
diff --git 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) <afile> (not expanded to a full path)
• match: (string) <amatch> (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
@@ -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) [<afile>] (not expanded to a full path)
--- - match: (string) [<amatch>] (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
@@ -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
@@ -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
@@ -322,12 +322,16 @@ local function get_api_keysets_meta()
--- @type {name: string, keys: string[], types: table<string,string>}[]
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
@@ -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) [<afile>] (not expanded to a full path)
/// - match: (string) [<amatch>] (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|.
