feat(api): remove Lua autocommand callbacks when they return true (#17784)

This copies the semantics of nvim_buf_attach callbacks, and is a
convenient way to create oneshot autocommands gated by some condition.

1 files changed, 28 insertions, 0 deletions

diff --git a/test/functional/api/autocmd_spec.lua b/test/functional/api/autocmd_spec.lua
index 372cbf2c30..a58ca00a75 100644
--- a/test/functional/api/autocmd_spec.lua
+++ b/test/functional/api/autocmd_spec.lua
@@ -154,6 +154,34 @@ describe('autocmd api', function()
         eq(1, #aus, aus)
       end)
     end)
+
+    it('removes an autocommand if the callback returns true', function()
+      meths.set_var("some_condition", false)
+
+      exec_lua [[
+      vim.api.nvim_create_autocmd("User", {
+        pattern = "Test",
+        desc = "A test autocommand",
+        callback = function()
+          return vim.g.some_condition
+        end,
+      })
+      ]]
+
+      meths.do_autocmd("User", {pattern = "Test"})
+      eq({{
+        buflocal = false,
+        command = 'A test autocommand',
+        desc = 'A test autocommand',
+        event = 'User',
+        id = 1,
+        once = false,
+        pattern = 'Test',
+      }}, meths.get_autocmds({event = "User", pattern = "Test"}))
+      meths.set_var("some_condition", true)
+      meths.do_autocmd("User", {pattern = "Test"})
+      eq({}, meths.get_autocmds({event = "User", pattern = "Test"}))
+    end)
   end)
 
   describe('nvim_get_autocmds', function()