diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index cb3b2a3f77..804efb6922 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -3591,33 +3591,35 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()* Parameters: ~ • {opts} Dict with at least one of the following: - • group (string|integer): the autocommand group name or id to - match against. - • event (string|array): event or events to match against + • 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|. - • pattern (string|array): pattern or patterns to match against + • 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|. Cannot be used with {buffer} - • buffer: Buffer number or list of buffer numbers for buffer - local autocommands |autocmd-buflocal|. Cannot be used with - {pattern} Return: ~ Array of autocommands matching the criteria, with each item containing the following fields: - • id (number): the autocommand id (only when defined with the API). - • group (integer): the autocommand group id. - • group_name (string): the autocommand group name. - • desc (string): the autocommand description. - • event (string): the autocommand event. - • command (string): the autocommand command. Note: this will be empty + • buffer: (integer) the buffer number. + • buflocal: (boolean) true if the autocommand is buffer local. + • command: (string) the autocommand command. Note: this will be empty if a callback is set. - • callback (function|string|nil): Lua function or name of a Vim script - function which is executed when this autocommand is triggered. - • once (boolean): whether the autocommand is only run once. - • pattern (string): the autocommand pattern. If the autocommand is + • 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. + • id: (integer) the autocommand id (only when defined with the API). + • group: (integer) the autocommand group id. + • group_name: (string) the autocommand group name. + • once: (boolean) whether the autocommand is only run once. + • pattern: (string) the autocommand pattern. If the autocommand is buffer local |autocmd-buffer-local|: - • buflocal (boolean): true if the autocommand is buffer local. - • buffer (number): the buffer number. ============================================================================== diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index b2385197bd..dd2d4201ce 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1256,27 +1256,28 @@ function vim.api.nvim_get_all_options_info() end --- match any combination of them. --- --- @param opts vim.api.keyset.get_autocmds Dict with at least one of the following: ---- - group (string|integer): the autocommand group name or id to match against. ---- - event (string|array): event or events to match against `autocmd-events`. ---- - pattern (string|array): pattern or patterns to match against `autocmd-pattern`. ---- Cannot be used with {buffer} ---- - buffer: Buffer number or list of buffer numbers for buffer local autocommands +--- - 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`. +--- - 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`. +--- Cannot be used with {buffer} --- @return vim.api.keyset.get_autocmds.ret[] # Array of autocommands matching the criteria, with each item --- containing the following fields: ---- - id (number): the autocommand id (only when defined with the API). ---- - group (integer): the autocommand group id. ---- - group_name (string): the autocommand group name. ---- - desc (string): the autocommand description. ---- - event (string): the autocommand event. ---- - command (string): the autocommand command. Note: this will be empty if a callback is set. ---- - callback (function|string|nil): Lua function or name of a Vim script function +--- - buffer: (integer) the buffer number. +--- - buflocal: (boolean) true if the autocommand is buffer local. +--- - command: (string) the autocommand command. Note: this will be empty if a callback is set. +--- - callback: (function|string|nil): Lua function or name of a Vim script function --- which is executed when this autocommand is triggered. ---- - once (boolean): whether the autocommand is only run once. ---- - pattern (string): the autocommand pattern. +--- - desc: (string) the autocommand description. +--- - event: (string) 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. +--- - once: (boolean) whether the autocommand is only run once. +--- - pattern: (string) the autocommand pattern. --- If the autocommand is buffer local |autocmd-buffer-local|: ---- - buflocal (boolean): true if the autocommand is buffer local. ---- - buffer (number): the buffer number. function vim.api.nvim_get_autocmds(opts) end --- Gets information about a channel. diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua index e11dddb2d3..b9b9e3221f 100644 --- a/runtime/lua/vim/_meta/api_keysets.lua +++ b/runtime/lua/vim/_meta/api_keysets.lua @@ -116,6 +116,7 @@ error('Cannot require a meta file') --- @field group? integer|string --- @field pattern? string|string[] --- @field buffer? integer|integer[] +--- @field id? integer --- @class vim.api.keyset.get_commands --- @field builtin? boolean diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c index 45e2de69e0..5ca5db02e1 100644 --- a/src/nvim/api/autocmd.c +++ b/src/nvim/api/autocmd.c @@ -68,32 +68,31 @@ static int64_t next_autocmd_id = 1; /// match any combination of them. /// /// @param opts Dict with at least one of the following: -/// - group (string|integer): the autocommand group name or id to match against. -/// - event (string|array): event or events to match against |autocmd-events|. -/// - pattern (string|array): pattern or patterns to match against |autocmd-pattern|. -/// Cannot be used with {buffer} -/// - buffer: Buffer number or list of buffer numbers for buffer local autocommands +/// - 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|. +/// - 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|. +/// Cannot be used with {buffer} /// @return Array of autocommands matching the criteria, with each item /// containing the following fields: -/// - id (number): the autocommand id (only when defined with the API). -/// - group (integer): the autocommand group id. -/// - group_name (string): the autocommand group name. -/// - desc (string): the autocommand description. -/// - event (string): the autocommand event. -/// - command (string): the autocommand command. Note: this will be empty if a callback is set. -/// - callback (function|string|nil): Lua function or name of a Vim script function +/// - buffer: (integer) the buffer number. +/// - buflocal: (boolean) true if the autocommand is buffer local. +/// - command: (string) the autocommand command. Note: this will be empty if a callback is set. +/// - callback: (function|string|nil): Lua function or name of a Vim script function /// which is executed when this autocommand is triggered. -/// - once (boolean): whether the autocommand is only run once. -/// - pattern (string): the autocommand pattern. +/// - desc: (string) the autocommand description. +/// - event: (string) 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. +/// - once: (boolean) whether the autocommand is only run once. +/// - pattern: (string) the autocommand pattern. /// If the autocommand is buffer local |autocmd-buffer-local|: -/// - buflocal (boolean): true if the autocommand is buffer local. -/// - buffer (number): the buffer number. Array nvim_get_autocmds(Dict(get_autocmds) *opts, Arena *arena, Error *err) FUNC_API_SINCE(9) { - // TODO(tjdevries): Would be cool to add nvim_get_autocmds({ id = ... }) - ArrayBuilder autocmd_list = KV_INITIAL_VALUE; kvi_init(autocmd_list); char *pattern_filters[AUCMD_MAX_PATTERNS]; @@ -127,6 +126,8 @@ Array nvim_get_autocmds(Dict(get_autocmds) *opts, Arena *arena, Error *err) }); } + int id = (HAS_KEY(opts, get_autocmds, id)) ? (int)opts->id : -1; + if (HAS_KEY(opts, get_autocmds, event)) { check_event = true; @@ -237,6 +238,10 @@ Array nvim_get_autocmds(Dict(get_autocmds) *opts, Arena *arena, Error *err) continue; } + if (id != -1 && ac->id != id) { + continue; + } + // Skip autocmds from invalid groups if passed. if (group != 0 && ap->group != group) { continue; diff --git a/src/nvim/api/keysets_defs.h b/src/nvim/api/keysets_defs.h index 48f5f7246c..4ba8e800ed 100644 --- a/src/nvim/api/keysets_defs.h +++ b/src/nvim/api/keysets_defs.h @@ -262,6 +262,7 @@ typedef struct { Union(Integer, String) group; Union(String, ArrayOf(String)) pattern; Union(Integer, ArrayOf(Integer)) buffer; + Integer id; } Dict(get_autocmds); typedef struct { diff --git a/test/functional/api/autocmd_spec.lua b/test/functional/api/autocmd_spec.lua index bb6456f45b..64b28e7bf7 100644 --- a/test/functional/api/autocmd_spec.lua +++ b/test/functional/api/autocmd_spec.lua @@ -899,6 +899,89 @@ describe('autocmd api', function() eq([[:echo "Buffer"]], normalized_aus[1].command) end) end) + + describe('id', function() + it('gets events by ID', function() + local id = api.nvim_create_autocmd('BufEnter', { + command = 'echo "hello"', + }) + eq({ + { + buflocal = false, + command = 'echo "hello"', + event = 'BufEnter', + id = id, + once = false, + pattern = '*', + }, + }, api.nvim_get_autocmds({ id = id })) + end) + + it('gets events by ID by other filters', function() + local group_name = 'NVIM_GET_AUTOCMDS_ID' + local group = api.nvim_create_augroup(group_name, { clear = true }) + local id = api.nvim_create_autocmd('BufEnter', { + command = 'set number', + group = group, + }) + api.nvim_create_autocmd('WinEnter', { + group = group, + command = 'set cot&', + }) + eq({ + { + buflocal = false, + command = 'set number', + event = 'BufEnter', + group = group, + group_name = group_name, + id = id, + once = false, + pattern = '*', + }, + }, api.nvim_get_autocmds({ id = id, group = group })) + end) + + it('gets events by ID and a specific event', function() + local id = api.nvim_create_autocmd('InsertEnter', { command = 'set number' }) + api.nvim_create_autocmd('InsertEnter', { command = 'set wrap' }) + eq({ + { + buflocal = false, + command = 'set number', + event = 'InsertEnter', + id = id, + once = false, + pattern = '*', + }, + }, api.nvim_get_autocmds({ id = id, event = 'InsertEnter' })) + end) + + it('gets events by ID and a specific pattern', function() + local id = api.nvim_create_autocmd('InsertEnter', { + pattern = '*.c', + command = 'set number', + }) + api.nvim_create_autocmd('InsertEnter', { + pattern = '*.c', + command = 'set wrap', + }) + eq({ + { + buflocal = false, + command = 'set number', + event = 'InsertEnter', + id = id, + once = false, + pattern = '*.c', + }, + }, api.nvim_get_autocmds({ id = id, pattern = '*.c' })) + end) + + it('empty result when id does not found', function() + eq({}, api.nvim_get_autocmds({ id = 255 })) + end) + end) end) describe('nvim_exec_autocmds', function()