autocmd: introduce "once" feature

Adds a new feature to :autocmd which sets the handler to be executed at
most one times.

Before:

    augroup FooGroup
      autocmd!
      autocmd FileType foo call Foo() | autocmd! FooGroup * <buffer>
    augroup END

After:

    autocmd FileType foo once call Foo()

1 files changed, 72 insertions, 1 deletions

diff --git a/test/functional/autocmd/autocmd_spec.lua b/test/functional/autocmd/autocmd_spec.lua
index 8ee9462a8d..42e5c46fa5 100644
--- a/test/functional/autocmd/autocmd_spec.lua
+++ b/test/functional/autocmd/autocmd_spec.lua
@@ -1,15 +1,18 @@
 local helpers = require('test.functional.helpers')(after_each)
 
+local dedent = helpers.dedent
 local eq = helpers.eq
 local eval = helpers.eval
+local feed = helpers.feed
 local clear = helpers.clear
 local meths = helpers.meths
+local funcs = helpers.funcs
 local expect = helpers.expect
 local command = helpers.command
 local exc_exec = helpers.exc_exec
 local curbufmeths = helpers.curbufmeths
 
-describe('autocmds:', function()
+describe('autocmd', function()
   before_each(clear)
 
   it(':tabnew triggers events in the correct order', function()
@@ -55,4 +58,72 @@ describe('autocmds:', function()
         end of test file xx]])
     end)
   end)
+
+  it('once', function()  -- :help autocmd-once
+    --
+    -- ":autocmd ... once" executes its handler once, then removes the handler.
+    --
+    local expected = {
+      'Many1',
+      'Once1',
+      'Once2',
+      'Many2',
+      'Once3',
+      'Many1',
+      'Many2',
+      'Many1',
+      'Many2',
+    }
+    command('let g:foo = []')
+    command('autocmd TabNew * :call add(g:foo, "Many1")')
+    command('autocmd TabNew * once :call add(g:foo, "Once1")')
+    command('autocmd TabNew * once :call add(g:foo, "Once2")')
+    command('autocmd TabNew * :call add(g:foo, "Many2")')
+    command('autocmd TabNew * once :call add(g:foo, "Once3")')
+    eq(dedent([[
+
+       --- Autocommands ---
+       TabNew
+           *         :call add(g:foo, "Many1")
+                     :call add(g:foo, "Once1")
+                     :call add(g:foo, "Once2")
+                     :call add(g:foo, "Many2")
+                     :call add(g:foo, "Once3")]]),
+       funcs.execute('autocmd Tabnew'))
+    command('tabnew')
+    command('tabnew')
+    command('tabnew')
+    eq(expected, eval('g:foo'))
+    eq(dedent([[
+
+       --- Autocommands ---
+       TabNew
+           *         :call add(g:foo, "Many1")
+                     :call add(g:foo, "Many2")]]),
+       funcs.execute('autocmd Tabnew'))
+
+    --
+    -- ":autocmd ... once" handlers can be deleted.
+    --
+    expected = {}
+    command('let g:foo = []')
+    command('autocmd TabNew * once :call add(g:foo, "Once1")')
+    command('autocmd! TabNew')
+    command('tabnew')
+    eq(expected, eval('g:foo'))
+
+    --
+    -- ":autocmd ... <buffer> once nested"
+    --
+    expected = {
+      'OptionSet-Once',
+      'CursorMoved-Once',
+    }
+    command('let g:foo = []')
+    command('autocmd OptionSet binary once nested :call add(g:foo, "OptionSet-Once")')
+    command('autocmd CursorMoved <buffer> once nested setlocal binary|:call add(g:foo, "CursorMoved-Once")')
+    command("put ='foo bar baz'")
+    feed('0llhlh')
+    eq(expected, eval('g:foo'))
+  end)
 end)