fix(api): support get autocmds by id in api

Problem: Can not use id as filter condition to get autocmds.

Solution: add id which support integer or array to filter get autocmds

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
+                • buffer: (integer) Buffer number or list of buffer numbers
-                  match against.
+                  for buffer local autocommands |autocmd-buflocal|. Cannot be
-                • event (string|array): event or events to match against
+                  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).
+        • buffer: (integer) the buffer number.
-        • group (integer): the autocommand group id.
+        • buflocal: (boolean) true if the autocommand is buffer local.
-        • group_name (string): the autocommand group name.
+        • command: (string) the autocommand command. Note: this will be empty
-        • 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
+        • callback: (function|string|nil): Lua function or name of a Vim
-          function which is executed when this autocommand is triggered.
+          script function which is executed when this autocommand is
-        • once (boolean): whether the autocommand is only run once.
+          triggered.
-        • pattern (string): the autocommand pattern. If the autocommand is
+        • 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.
 
 
 ==============================================================================

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.
+--- - buffer: (integer) Buffer number or list of buffer numbers for buffer local autocommands
---- - 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
 --- `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).
+--- - buffer: (integer) the buffer number.
---- - group (integer): the autocommand group id.
+--- - buflocal: (boolean) true if the autocommand is buffer local.
---- - group_name (string): the autocommand group name.
+--- - command: (string) the autocommand command. Note: this will be empty if a callback is set.
---- - desc (string): the autocommand description.
+--- - callback: (function|string|nil): Lua function or name of a Vim script function
---- - 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
 ---   which is executed when this autocommand is triggered.
---- - once (boolean): whether the autocommand is only run once.
+--- - desc: (string) the autocommand description.
---- - pattern (string): the autocommand pattern.
+--- - 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.

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

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.
+///             - buffer: (integer) Buffer number or list of buffer numbers for buffer local autocommands
-///             - 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
 ///             |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).
+///             - buffer: (integer) the buffer number.
-///             - group (integer): the autocommand group id.
+///             - buflocal: (boolean) true if the autocommand is buffer local.
-///             - group_name (string): the autocommand group name.
+///             - command: (string) the autocommand command. Note: this will be empty if a callback is set.
-///             - desc (string): the autocommand description.
+///             - callback: (function|string|nil): Lua function or name of a Vim script function
-///             - 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
 ///               which is executed when this autocommand is triggered.
-///             - once (boolean): whether the autocommand is only run once.
+///             - desc: (string) the autocommand description.
-///             - pattern (string): the autocommand pattern.
+///             - 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;

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 {

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()