autocmd: rename "once" => "-once" #9713

- Rename "nested" to "-nested", but continue to support "nested" for
  backwards-compatibility.
- Allow any order: "-once -nested" or "-nested -once".

ref https://github.com/neovim/neovim/pull/9706#issuecomment-471295747

runtime/doc/autocmd.txt

@@ -40,7 +40,7 @@ effects.  Be careful not to destroy your text.
 2. Defining autocommands				*autocmd-define*
 
 							*:au* *:autocmd*
-:au[tocmd] [group] {event} {pat} [once] [nested] {cmd}
+:au[tocmd] [group] {event} {pat} [-once] [-nested] {cmd}
 			Add {cmd} to the list of commands that Vim will
 			execute automatically on {event} for a file matching
 			{pat} |autocmd-patterns|.
@@ -48,9 +48,9 @@ effects.  Be careful not to destroy your text.
 			:autocmd and won't start a comment.
 			Nvim always adds {cmd} after existing autocommands so
 			they execute in the order in which they were defined.
-			See |autocmd-nested| for [nested].
+			See |autocmd-nested| for [-nested].
 							*autocmd-once*
-			If [once] is supplied the command is executed once,
+			If [-once] is supplied the command is executed once,
 			then removed ("one shot").
 
 The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand.
@@ -119,11 +119,11 @@ prompt.  When one command outputs two messages this can happen anyway.
 ==============================================================================
 3. Removing autocommands				*autocmd-remove*
 
-:au[tocmd]! [group] {event} {pat} [once] [nested] {cmd}
+:au[tocmd]! [group] {event} {pat} [-once] [-nested] {cmd}
 			Remove all autocommands associated with {event} and
 			{pat}, and add the command {cmd}.
-			See |autocmd-once| for [once].
+			See |autocmd-once| for [-once].
-			See |autocmd-nested| for [nested].
+			See |autocmd-nested| for [-nested].
 
 :au[tocmd]! [group] {event} {pat}
 			Remove all autocommands associated with {event} and
@@ -1442,9 +1442,9 @@ instead of ":q!".
 							*autocmd-nested* *E218*
 By default, autocommands do not nest.  If you use ":e" or ":w" in an
 autocommand, Vim does not execute the BufRead and BufWrite autocommands for
-those commands.  If you do want this, use the "nested" flag for those commands
+those commands.  If you do want this, use the "-nested" flag for those
-in which you want nesting.  For example: >
+commands in which you want nesting.  For example: >
-  :autocmd FileChangedShell *.c nested e!
+  :autocmd FileChangedShell *.c -nested e!
 The nesting is limited to 10 levels to get out of recursive loops.
 
 It's possible to use the ":au" command in an autocommand.  This can be a

runtime/doc/nvim_terminal_emulator.txt

@@ -35,7 +35,7 @@ There are 3 ways to create a terminal buffer:
 <
     Note: The "term://" pattern is handled by a BufReadCmd handler, so the
     |autocmd-nested| modifier is required to use it in an autocmd. >
-        autocmd VimEnter * nested split term://sh
+        autocmd VimEnter * -nested split term://sh
 <    This is only mentioned for reference; use |:terminal| instead.
 
 When the terminal starts, the buffer contents are updated and the buffer is

runtime/doc/usr_40.txt

@@ -453,15 +453,15 @@ matching BufWritePre autocommands and executes them, and then it
 performs the ":write".
    The general form of the :autocmd command is as follows: >
 
-	:autocmd [group] {events} {file_pattern} [nested] {command}
+	:autocmd [group] {events} {file_pattern} [-nested] {command}
 
 The [group] name is optional.  It is used in managing and calling the commands
 (more on this later).  The {events} parameter is a list of events (comma
 separated) that trigger the command.
    {file_pattern} is a filename, usually with wildcards.  For example, using
 "*.txt" makes the autocommand be used for all files whose name end in ".txt".
-The optional [nested] flag allows for nesting of autocommands (see below), and
+The optional [-nested] flag allows for nesting of autocommands (see below),
-finally, {command} is the command to be executed.
+and finally, {command} is the command to be executed.
 
 
 EVENTS
@@ -576,9 +576,9 @@ NESTING
 Generally, commands executed as the result of an autocommand event will not
 trigger any new events.  If you read a file in response to a FileChangedShell
 event, it will not trigger the autocommands that would set the syntax, for
-example.  To make the events triggered, add the "nested" argument: >
+example.  To make the events triggered, add the "-nested" flag: >
 
-	:autocmd FileChangedShell * nested  edit
+	:autocmd FileChangedShell * -nested  edit
 
 
 EXECUTING AUTOCOMMANDS

runtime/doc/windows.txt

@@ -880,15 +880,15 @@ CTRL-W g }						*CTRL-W_g}*
 		cursor.  This is less clever than using |:ptag|, but you don't
 		need a tags file and it will also find matches in system
 		include files.  Example: >
-  :au! CursorHold *.[ch] nested exe "silent! psearch " . expand("<cword>")
+  :au! CursorHold *.[ch] -nested exe "silent! psearch " . expand("<cword>")
 <		Warning: This can be slow.
 
 Example						*CursorHold-example*  >
 
-  :au! CursorHold *.[ch] nested exe "silent! ptag " . expand("<cword>")
+  :au! CursorHold *.[ch] -nested exe "silent! ptag " . expand("<cword>")
 
 This will cause a ":ptag" to be executed for the keyword under the cursor,
-when the cursor hasn't moved for the time set with 'updatetime'.  The "nested"
+when the cursor hasn't moved for the time set with 'updatetime'.  "-nested"
 makes other autocommands be executed, so that syntax highlighting works in the
 preview window.  The "silent!" avoids an error message when the tag could not
 be found.  Also see |CursorHold|.  To disable this again: >
@@ -898,7 +898,7 @@ be found.  Also see |CursorHold|.  To disable this again: >
 A nice addition is to highlight the found tag, avoid the ":ptag" when there
 is no word under the cursor, and a few other things: >
 
-  :au! CursorHold *.[ch] nested call PreviewWord()
+  :au! CursorHold *.[ch] -nested call PreviewWord()
   :func PreviewWord()
   :  if &previewwindow			" don't do this in the preview window
   :    return

src/nvim/fileio.c

@@ -6047,20 +6047,23 @@ void do_autocmd(char_u *arg_in, int forceit)
       }
     }
 
-    // Check for "once" flag.
     cmd = skipwhite(cmd);
-    if (*cmd != NUL && STRNCMP(cmd, "once", 4) == 0
+    for (size_t i = 0; i < 2; i++) {
-        && ascii_iswhite(cmd[4])) {
+      if (*cmd != NUL) {
+        // Check for "-once" flag.
+        if (!once && STRNCMP(cmd, "-once", 5) == 0 && ascii_iswhite(cmd[5])) {
           once = true;
-      cmd = skipwhite(cmd + 4);
+          cmd = skipwhite(cmd + 5);
         }
-
+        // Check for "-nested" flag.
-    // Check for "nested" flag.
+        if (!nested
-    cmd = skipwhite(cmd);
+            && ((STRNCMP(cmd, "-nested", 7) == 0 && ascii_iswhite(cmd[7]))
-    if (*cmd != NUL && STRNCMP(cmd, "nested", 6) == 0
+                // Deprecated form (without "-").
-        && ascii_iswhite(cmd[6])) {
+                || (STRNCMP(cmd, "nested", 6) == 0 && ascii_iswhite(cmd[6])))) {
           nested = true;
-      cmd = skipwhite(cmd + 6);
+          cmd = skipwhite(cmd + ('-' == cmd[0] ? 7 : 6));
+        }
+      }
     }
 
     // Find the start of the commands.

test/functional/autocmd/autocmd_spec.lua

@@ -59,9 +59,9 @@ describe('autocmd', function()
     end)
   end)
 
-  it('once', function()  -- :help autocmd-once
+  it('-once', function()  -- :help autocmd-once
     --
-    -- ":autocmd ... once" executes its handler once, then removes the handler.
+    -- ":autocmd ... -once" executes its handler once, then removes the handler.
     --
     local expected = {
       'Many1',
@@ -76,10 +76,10 @@ describe('autocmd', function()
     }
     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, "Once1")')
-    command('autocmd TabNew * once :call add(g:foo, "Once2")')
+    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")')
+    command('autocmd TabNew * -once :call add(g:foo, "Once3")')
     eq(dedent([[
 
        --- Autocommands ---
@@ -103,25 +103,25 @@ describe('autocmd', function()
        funcs.execute('autocmd Tabnew'))
 
     --
-    -- ":autocmd ... once" handlers can be deleted.
+    -- ":autocmd ... -once" handlers can be deleted.
     --
     expected = {}
     command('let g:foo = []')
-    command('autocmd TabNew * once :call add(g:foo, "Once1")')
+    command('autocmd TabNew * -once :call add(g:foo, "Once1")')
     command('autocmd! TabNew')
     command('tabnew')
     eq(expected, eval('g:foo'))
 
     --
-    -- ":autocmd ... <buffer> once nested"
+    -- ":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 OptionSet binary -nested -once :call add(g:foo, "OptionSet-Once")')
-    command('autocmd CursorMoved <buffer> once nested setlocal binary|:call add(g:foo, "CursorMoved-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'))