Merge remote-tracking branch 'upstream/master' into colorcolcharcolorcolchar

36 files changed, 3664 insertions, 2814 deletions

diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index 931363e199..08d9d8e117 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -1,27 +1,27 @@
-// This is an open source non-commercial project. Dear PVS-Studio, please check
-// it. PVS-Studio Static Code Analyzer for C, C++ and C#: http://www.viva64.com
-
 #include <assert.h>
+#include <lauxlib.h>
 #include <stdbool.h>
 #include <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 
-#include "lauxlib.h"
+#include "klib/kvec.h"
 #include "nvim/api/autocmd.h"
+#include "nvim/api/keysets_defs.h"
 #include "nvim/api/private/defs.h"
+#include "nvim/api/private/dispatch.h"
 #include "nvim/api/private/helpers.h"
-#include "nvim/ascii.h"
+#include "nvim/api/private/validate.h"
 #include "nvim/autocmd.h"
 #include "nvim/buffer.h"
 #include "nvim/eval/typval.h"
-#include "nvim/eval/typval_defs.h"
 #include "nvim/ex_cmds_defs.h"
+#include "nvim/func_attr.h"
 #include "nvim/globals.h"
 #include "nvim/lua/executor.h"
 #include "nvim/memory.h"
-#include "nvim/vim.h"
+#include "nvim/vim_defs.h"
 
 #ifdef INCLUDE_GENERATED_DECLARATIONS
 # include "api/autocmd.c.generated.h"
@@ -32,13 +32,11 @@
 // Copy string or array of strings into an empty array.
 // Get the event number, unless it is an error. Then goto `goto_name`.
 #define GET_ONE_EVENT(event_nr, event_str, goto_name) \
-  char *__next_ev; \
   event_T event_nr = \
-    event_name2nr(event_str.data.string.data, &__next_ev); \
-  if (event_nr >= NUM_EVENTS) { \
-    api_set_error(err, kErrorTypeValidation, "unexpected event"); \
+    event_name2nr_str(event_str.data.string); \
+  VALIDATE_S((event_nr < NUM_EVENTS), "event", event_str.data.string.data, { \
     goto goto_name; \
-  }
+  });
 
 // ID for associating autocmds created via nvim_create_autocmd
 // Used to delete autocmds from nvim_del_autocmd
@@ -47,19 +45,20 @@ static int64_t next_autocmd_id = 1;
 /// Get all autocommands that match the corresponding {opts}.
 ///
 /// These examples will get autocommands matching ALL the given criteria:
-/// <pre>lua
-///   -- Matches all criteria
-///   autocommands = vim.api.nvim_get_autocmds({
-///     group = "MyGroup",
-///     event = {"BufEnter", "BufWinEnter"},
-///     pattern = {"*.c", "*.h"}
-///   })
 ///
-///   -- All commands from one group
-///   autocommands = vim.api.nvim_get_autocmds({
-///     group = "MyGroup",
-///   })
-/// </pre>
+/// ```lua
+/// -- Matches all criteria
+/// autocommands = vim.api.nvim_get_autocmds({
+///   group = "MyGroup",
+///   event = {"BufEnter", "BufWinEnter"},
+///   pattern = {"*.c", "*.h"}
+/// })
+///
+/// -- All commands from one group
+/// autocommands = vim.api.nvim_get_autocmds({
+///   group = "MyGroup",
+/// })
+/// ```
 ///
 /// NOTE: When multiple patterns or events are provided, it will find all the autocommands that
 /// match any combination of them.
@@ -107,25 +106,24 @@ Array nvim_get_autocmds(Dict(get_autocmds) *opts, Error *err)
     break;
   case kObjectTypeString:
     group = augroup_find(opts->group.data.string.data);
-    if (group < 0) {
-      api_set_error(err, kErrorTypeValidation, "invalid augroup passed.");
+    VALIDATE_S((group >= 0), "group", opts->group.data.string.data, {
       goto cleanup;
-    }
+    });
     break;
   case kObjectTypeInteger:
     group = (int)opts->group.data.integer;
-    char *name = augroup_name(group);
-    if (!augroup_exists(name)) {
-      api_set_error(err, kErrorTypeValidation, "invalid augroup passed.");
+    char *name = group == 0 ? NULL : augroup_name(group);
+    VALIDATE_INT(augroup_exists(name), "group", opts->group.data.integer, {
       goto cleanup;
-    }
+    });
     break;
   default:
-    api_set_error(err, kErrorTypeValidation, "group must be a string or an integer.");
-    goto cleanup;
+    VALIDATE_EXP(false, "group", "String or Integer", api_typename(opts->group.type), {
+      goto cleanup;
+    });
   }
 
-  if (opts->event.type != kObjectTypeNil) {
+  if (HAS_KEY(opts, get_autocmds, event)) {
     check_event = true;
 
     Object v = opts->event;
@@ -134,57 +132,49 @@ Array nvim_get_autocmds(Dict(get_autocmds) *opts, Error *err)
       event_set[event_nr] = true;
     } else if (v.type == kObjectTypeArray) {
       FOREACH_ITEM(v.data.array, event_v, {
-        if (event_v.type != kObjectTypeString) {
-          api_set_error(err,
-                        kErrorTypeValidation,
-                        "Every event must be a string in 'event'");
+        VALIDATE_T("event item", kObjectTypeString, event_v.type, {
           goto cleanup;
-        }
+        });
 
         GET_ONE_EVENT(event_nr, event_v, cleanup);
         event_set[event_nr] = true;
       })
     } else {
-      api_set_error(err,
-                    kErrorTypeValidation,
-                    "Not a valid 'event' value. Must be a string or an array");
-      goto cleanup;
+      VALIDATE_EXP(false, "event", "String or Array", NULL, {
+        goto cleanup;
+      });
     }
   }
 
-  if (opts->pattern.type != kObjectTypeNil && opts->buffer.type != kObjectTypeNil) {
-    api_set_error(err, kErrorTypeValidation,
-                  "Cannot use both 'pattern' and 'buffer'");
+  VALIDATE((!HAS_KEY(opts, get_autocmds, pattern) || !HAS_KEY(opts, get_autocmds, buffer)),
+           "%s", "Cannot use both 'pattern' and 'buffer'", {
     goto cleanup;
-  }
+  });
 
   int pattern_filter_count = 0;
-  if (opts->pattern.type != kObjectTypeNil) {
+  if (HAS_KEY(opts, get_autocmds, pattern)) {
     Object v = opts->pattern;
     if (v.type == kObjectTypeString) {
       pattern_filters[pattern_filter_count] = v.data.string.data;
       pattern_filter_count += 1;
     } else if (v.type == kObjectTypeArray) {
-      if (v.data.array.size > AUCMD_MAX_PATTERNS) {
-        api_set_error(err, kErrorTypeValidation,
-                      "Too many patterns. Please limit yourself to %d or fewer",
-                      AUCMD_MAX_PATTERNS);
+      VALIDATE((v.data.array.size <= AUCMD_MAX_PATTERNS),
+               "Too many patterns (maximum of %d)", AUCMD_MAX_PATTERNS, {
         goto cleanup;
-      }
+      });
 
       FOREACH_ITEM(v.data.array, item, {
-        if (item.type != kObjectTypeString) {
-          api_set_error(err, kErrorTypeValidation, "Invalid value for 'pattern': must be a string");
+        VALIDATE_T("pattern", kObjectTypeString, item.type, {
           goto cleanup;
-        }
+        });
 
         pattern_filters[pattern_filter_count] = item.data.string.data;
         pattern_filter_count += 1;
       });
     } else {
-      api_set_error(err, kErrorTypeValidation,
-                    "Not a valid 'pattern' value. Must be a string or an array");
-      goto cleanup;
+      VALIDATE_EXP(false, "pattern", "String or Array", api_typename(v.type), {
+        goto cleanup;
+      });
     }
   }
 
@@ -194,34 +184,33 @@ Array nvim_get_autocmds(Dict(get_autocmds) *opts, Error *err)
       goto cleanup;
     }
 
-    snprintf((char *)pattern_buflocal, BUFLOCAL_PAT_LEN, "<buffer=%d>", (int)buf->handle);
-    ADD(buffers, CSTR_TO_OBJ((char *)pattern_buflocal));
+    snprintf(pattern_buflocal, BUFLOCAL_PAT_LEN, "<buffer=%d>", (int)buf->handle);
+    ADD(buffers, CSTR_TO_OBJ(pattern_buflocal));
   } else if (opts->buffer.type == kObjectTypeArray) {
     if (opts->buffer.data.array.size > AUCMD_MAX_PATTERNS) {
-      api_set_error(err,
-                    kErrorTypeValidation,
-                    "Too many buffers. Please limit yourself to %d or fewer", AUCMD_MAX_PATTERNS);
+      api_set_error(err, kErrorTypeValidation, "Too many buffers (maximum of %d)",
+                    AUCMD_MAX_PATTERNS);
       goto cleanup;
     }
 
     FOREACH_ITEM(opts->buffer.data.array, bufnr, {
-      if (bufnr.type != kObjectTypeInteger && bufnr.type != kObjectTypeBuffer) {
-        api_set_error(err, kErrorTypeValidation, "Invalid value for 'buffer': must be an integer");
+      VALIDATE_EXP((bufnr.type == kObjectTypeInteger || bufnr.type == kObjectTypeBuffer),
+                   "buffer", "Integer", api_typename(bufnr.type), {
         goto cleanup;
-      }
+      });
 
       buf_T *buf = find_buffer_by_handle((Buffer)bufnr.data.integer, err);
       if (ERROR_SET(err)) {
         goto cleanup;
       }
 
-      snprintf((char *)pattern_buflocal, BUFLOCAL_PAT_LEN, "<buffer=%d>", (int)buf->handle);
-      ADD(buffers, CSTR_TO_OBJ((char *)pattern_buflocal));
+      snprintf(pattern_buflocal, BUFLOCAL_PAT_LEN, "<buffer=%d>", (int)buf->handle);
+      ADD(buffers, CSTR_TO_OBJ(pattern_buflocal));
+    });
+  } else if (HAS_KEY(opts, get_autocmds, buffer)) {
+    VALIDATE_EXP(false, "buffer", "Integer or Array", api_typename(opts->buffer.type), {
+      goto cleanup;
     });
-  } else if (opts->buffer.type != kObjectTypeNil) {
-    api_set_error(err, kErrorTypeValidation,
-                  "Invalid value for 'buffer': must be an integer or array of integers");
-    goto cleanup;
   }
 
   FOREACH_ITEM(buffers, bufnr, {
@@ -234,8 +223,12 @@ Array nvim_get_autocmds(Dict(get_autocmds) *opts, Error *err)
       continue;
     }
 
-    for (AutoPat *ap = au_get_autopat_for_event(event); ap != NULL; ap = ap->next) {
-      if (ap->cmds == NULL) {
+    AutoCmdVec *acs = au_get_autocmds_for_event(event);
+    for (size_t i = 0; i < kv_size(*acs); i++) {
+      AutoCmd *const ac = &kv_A(*acs, i);
+      AutoPat *const ap = ac->pat;
+
+      if (ap == NULL) {
         continue;
       }
 
@@ -247,19 +240,16 @@ Array nvim_get_autocmds(Dict(get_autocmds) *opts, Error *err)
       // Skip 'pattern' from invalid patterns if passed.
       if (pattern_filter_count > 0) {
         bool passed = false;
-        for (int i = 0; i < pattern_filter_count; i++) {
-          assert(i < AUCMD_MAX_PATTERNS);
-          assert(pattern_filters[i]);
+        for (int j = 0; j < pattern_filter_count; j++) {
+          assert(j < AUCMD_MAX_PATTERNS);
+          assert(pattern_filters[j]);
 
-          char *pat = pattern_filters[i];
+          char *pat = pattern_filters[j];
           int patlen = (int)strlen(pat);
 
           if (aupat_is_buflocal(pat, patlen)) {
-            aupat_normalize_buflocal_pat(pattern_buflocal,
-                                         pat,
-                                         patlen,
+            aupat_normalize_buflocal_pat(pattern_buflocal, pat, patlen,
                                          aupat_get_buflocal_nr(pat, patlen));
-
             pat = pattern_buflocal;
           }
 
@@ -274,85 +264,71 @@ Array nvim_get_autocmds(Dict(get_autocmds) *opts, Error *err)
         }
       }
 
-      for (AutoCmd *ac = ap->cmds; ac != NULL; ac = ac->next) {
-        if (aucmd_exec_is_deleted(ac->exec)) {
-          continue;
-        }
+      Dictionary autocmd_info = ARRAY_DICT_INIT;
 
-        Dictionary autocmd_info = ARRAY_DICT_INIT;
-
-        if (ap->group != AUGROUP_DEFAULT) {
-          PUT(autocmd_info, "group", INTEGER_OBJ(ap->group));
-          PUT(autocmd_info, "group_name", CSTR_TO_OBJ(augroup_name(ap->group)));
-        }
+      if (ap->group != AUGROUP_DEFAULT) {
+        PUT(autocmd_info, "group", INTEGER_OBJ(ap->group));
+        PUT(autocmd_info, "group_name", CSTR_TO_OBJ(augroup_name(ap->group)));
+      }
 
-        if (ac->id > 0) {
-          PUT(autocmd_info, "id", INTEGER_OBJ(ac->id));
-        }
+      if (ac->id > 0) {
+        PUT(autocmd_info, "id", INTEGER_OBJ(ac->id));
+      }
 
-        if (ac->desc != NULL) {
-          PUT(autocmd_info, "desc", CSTR_TO_OBJ(ac->desc));
-        }
+      if (ac->desc != NULL) {
+        PUT(autocmd_info, "desc", CSTR_TO_OBJ(ac->desc));
+      }
 
-        if (ac->exec.type == CALLABLE_CB) {
-          PUT(autocmd_info, "command", STRING_OBJ(STRING_INIT));
+      if (ac->exec.type == CALLABLE_CB) {
+        PUT(autocmd_info, "command", STRING_OBJ(STRING_INIT));
 
-          Callback *cb = &ac->exec.callable.cb;
-          switch (cb->type) {
-          case kCallbackLua:
-            if (nlua_ref_is_function(cb->data.luaref)) {
-              PUT(autocmd_info, "callback", LUAREF_OBJ(api_new_luaref(cb->data.luaref)));
-            }
-            break;
-          case kCallbackFuncref:
-          case kCallbackPartial:
-            PUT(autocmd_info, "callback", STRING_OBJ(cstr_as_string(callback_to_string(cb))));
-            break;
-          default:
-            abort();
+        Callback *cb = &ac->exec.callable.cb;
+        switch (cb->type) {
+        case kCallbackLua:
+          if (nlua_ref_is_function(cb->data.luaref)) {
+            PUT(autocmd_info, "callback", LUAREF_OBJ(api_new_luaref(cb->data.luaref)));
           }
-        } else {
-          PUT(autocmd_info,
-              "command",
-              STRING_OBJ(cstr_as_string(xstrdup(ac->exec.callable.cmd))));
+          break;
+        case kCallbackFuncref:
+        case kCallbackPartial:
+          PUT(autocmd_info, "callback", CSTR_AS_OBJ(callback_to_string(cb)));
+          break;
+        case kCallbackNone:
+          abort();
         }
+      } else {
+        PUT(autocmd_info, "command", CSTR_TO_OBJ(ac->exec.callable.cmd));
+      }
 
-        PUT(autocmd_info,
-            "pattern",
-            STRING_OBJ(cstr_to_string((char *)ap->pat)));
-
-        PUT(autocmd_info,
-            "event",
-            STRING_OBJ(cstr_to_string((char *)event_nr2name(event))));
-
-        PUT(autocmd_info, "once", BOOLEAN_OBJ(ac->once));
-
-        if (ap->buflocal_nr) {
-          PUT(autocmd_info, "buflocal", BOOLEAN_OBJ(true));
-          PUT(autocmd_info, "buffer", INTEGER_OBJ(ap->buflocal_nr));
-        } else {
-          PUT(autocmd_info, "buflocal", BOOLEAN_OBJ(false));
-        }
+      PUT(autocmd_info, "pattern", CSTR_TO_OBJ(ap->pat));
+      PUT(autocmd_info, "event", CSTR_TO_OBJ(event_nr2name(event)));
+      PUT(autocmd_info, "once", BOOLEAN_OBJ(ac->once));
 
-        // TODO(sctx): It would be good to unify script_ctx to actually work with lua
-        //  right now it's just super weird, and never really gives you the info that
-        //  you would expect from this.
-        //
-        //  I think we should be able to get the line number, filename, etc. from lua
-        //  when we're executing something, and it should be easy to then save that
-        //  info here.
-        //
-        //  I think it's a big loss not getting line numbers of where options, autocmds,
-        //  etc. are set (just getting "Sourced (lua)" or something is not that helpful.
-        //
-        //  Once we do that, we can put these into the autocmd_info, but I don't think it's
-        //  useful to do that at this time.
-        //
-        // PUT(autocmd_info, "sid", INTEGER_OBJ(ac->script_ctx.sc_sid));
-        // PUT(autocmd_info, "lnum", INTEGER_OBJ(ac->script_ctx.sc_lnum));
-
-        ADD(autocmd_list, DICTIONARY_OBJ(autocmd_info));
+      if (ap->buflocal_nr) {
+        PUT(autocmd_info, "buflocal", BOOLEAN_OBJ(true));
+        PUT(autocmd_info, "buffer", INTEGER_OBJ(ap->buflocal_nr));
+      } else {
+        PUT(autocmd_info, "buflocal", BOOLEAN_OBJ(false));
       }
+
+      // TODO(sctx): It would be good to unify script_ctx to actually work with lua
+      //  right now it's just super weird, and never really gives you the info that
+      //  you would expect from this.
+      //
+      //  I think we should be able to get the line number, filename, etc. from lua
+      //  when we're executing something, and it should be easy to then save that
+      //  info here.
+      //
+      //  I think it's a big loss not getting line numbers of where options, autocmds,
+      //  etc. are set (just getting "Sourced (lua)" or something is not that helpful.
+      //
+      //  Once we do that, we can put these into the autocmd_info, but I don't think it's
+      //  useful to do that at this time.
+      //
+      // PUT(autocmd_info, "sid", INTEGER_OBJ(ac->script_ctx.sc_sid));
+      // PUT(autocmd_info, "lnum", INTEGER_OBJ(ac->script_ctx.sc_lnum));
+
+      ADD(autocmd_list, DICTIONARY_OBJ(autocmd_info));
     }
   }
 
@@ -365,28 +341,31 @@ cleanup:
 /// function _name_ string) or `command` (Ex command string).
 ///
 /// Example using Lua callback:
-/// <pre>lua
-///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-///       pattern = {"*.c", "*.h"},
-///       callback = function(ev)
-///         print(string.format('event fired: %s', vim.inspect(ev)))
-///       end
-///     })
-/// </pre>
+///
+/// ```lua
+/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
+///   pattern = {"*.c", "*.h"},
+///   callback = function(ev)
+///     print(string.format('event fired: %s', vim.inspect(ev)))
+///   end
+/// })
+/// ```
 ///
 /// Example using an Ex command as the handler:
-/// <pre>lua
-///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
-///       pattern = {"*.c", "*.h"},
-///       command = "echo 'Entering a C or C++ file'",
-///     })
-/// </pre>
+///
+/// ```lua
+/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
+///   pattern = {"*.c", "*.h"},
+///   command = "echo 'Entering a C or C++ file'",
+/// })
+/// ```
 ///
 /// Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like "$HOME"
 /// and "~" must be expanded explicitly:
-/// <pre>lua
-///   pattern = vim.fn.expand("~") .. "/some/path/*.py"
-/// </pre>
+///
+/// ```lua
+/// pattern = vim.fn.expand("~") .. "/some/path/*.py"
+/// ```
 ///
 /// @param event (string|array) Event(s) that will trigger the handler (`callback` or `command`).
 /// @param opts Options dict:
@@ -404,7 +383,7 @@ cleanup:
 ///                 - match: (string) expanded value of |<amatch>|
 ///                 - buf: (number) expanded value of |<abuf>|
 ///                 - file: (string) expanded value of |<afile>|
-///                 - data: (any) arbitrary data passed to |nvim_exec_autocmds()|
+///                 - data: (any) arbitrary data passed from |nvim_exec_autocmds()|
 ///             - command (string) optional: Vim command to execute on event. Cannot be used with
 ///             {callback}
 ///             - once (boolean) optional: defaults to false. Run the autocommand
@@ -421,10 +400,8 @@ Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autoc
 {
   int64_t autocmd_id = -1;
   char *desc = NULL;
-
   Array patterns = ARRAY_DICT_INIT;
   Array event_array = ARRAY_DICT_INIT;
-
   AucmdExecutable aucmd = AUCMD_EXECUTABLE_INIT;
   Callback cb = CALLBACK_NONE;
 
@@ -432,30 +409,23 @@ Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autoc
     goto cleanup;
   }
 
-  if (opts->callback.type != kObjectTypeNil && opts->command.type != kObjectTypeNil) {
-    api_set_error(err, kErrorTypeValidation, "specify either 'callback' or 'command', not both");
+  VALIDATE((!HAS_KEY(opts, create_autocmd, callback) || !HAS_KEY(opts, create_autocmd, command)),
+           "%s", "Cannot use both 'callback' and 'command'", {
     goto cleanup;
-  } else if (opts->callback.type != kObjectTypeNil) {
-    // TODO(tjdevries): It's possible we could accept callable tables,
-    // but we don't do that many other places, so for the moment let's
-    // not do that.
+  });
+
+  if (HAS_KEY(opts, create_autocmd, callback)) {
+    // NOTE: We could accept callable tables, but that isn't common in the API.
 
     Object *callback = &opts->callback;
     switch (callback->type) {
     case kObjectTypeLuaRef:
-      if (callback->data.luaref == LUA_NOREF) {
-        api_set_error(err,
-                      kErrorTypeValidation,
-                      "must pass an actual value");
+      VALIDATE_S((callback->data.luaref != LUA_NOREF), "callback", "<no value>", {
         goto cleanup;
-      }
-
-      if (!nlua_ref_is_function(callback->data.luaref)) {
-        api_set_error(err,
-                      kErrorTypeValidation,
-                      "must pass a function for callback");
+      });
+      VALIDATE_S(nlua_ref_is_function(callback->data.luaref), "callback", "<not a function>", {
         goto cleanup;
-      }
+      });
 
       cb.type = kCallbackLua;
       cb.data.luaref = api_new_luaref(callback->data.luaref);
@@ -465,61 +435,50 @@ Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autoc
       cb.data.funcref = string_to_cstr(callback->data.string);
       break;
     default:
-      api_set_error(err,
-                    kErrorTypeException,
-                    "'callback' must be a lua function or name of vim function");
-      goto cleanup;
+      VALIDATE_EXP(false, "callback", "Lua function or Vim function name",
+                   api_typename(callback->type), {
+        goto cleanup;
+      });
     }
 
     aucmd.type = CALLABLE_CB;
     aucmd.callable.cb = cb;
-  } else if (opts->command.type != kObjectTypeNil) {
-    Object *command = &opts->command;
-    if (command->type == kObjectTypeString) {
-      aucmd.type = CALLABLE_EX;
-      aucmd.callable.cmd = string_to_cstr(command->data.string);
-    } else {
-      api_set_error(err,
-                    kErrorTypeValidation,
-                    "'command' must be a string");
-      goto cleanup;
-    }
+  } else if (HAS_KEY(opts, create_autocmd, command)) {
+    aucmd.type = CALLABLE_EX;
+    aucmd.callable.cmd = string_to_cstr(opts->command);
   } else {
-    api_set_error(err, kErrorTypeValidation, "must pass one of: 'command', 'callback'");
-    goto cleanup;
+    VALIDATE(false, "%s", "Required: 'command' or 'callback'", {
+      goto cleanup;
+    });
   }
 
-  bool is_once = api_object_to_bool(opts->once, "once", false, err);
-  bool is_nested = api_object_to_bool(opts->nested, "nested", false, err);
-
   int au_group = get_augroup_from_object(opts->group, err);
   if (au_group == AUGROUP_ERROR) {
     goto cleanup;
   }
 
-  if (!get_patterns_from_pattern_or_buf(&patterns, opts->pattern, opts->buffer, err)) {
+  bool has_buffer = HAS_KEY(opts, create_autocmd, buffer);
+
+  VALIDATE((!HAS_KEY(opts, create_autocmd, pattern) || !has_buffer),
+           "%s", "Cannot use both 'pattern' and 'buffer' for the same autocmd", {
+    goto cleanup;
+  });
+
+  if (!get_patterns_from_pattern_or_buf(&patterns, opts->pattern, has_buffer, opts->buffer, err)) {
     goto cleanup;
   }
 
-  if (opts->desc.type != kObjectTypeNil) {
-    if (opts->desc.type == kObjectTypeString) {
-      desc = opts->desc.data.string.data;
-    } else {
-      api_set_error(err,
-                    kErrorTypeValidation,
-                    "'desc' must be a string");
-      goto cleanup;
-    }
+  if (HAS_KEY(opts, create_autocmd, desc)) {
+    desc = opts->desc.data;
   }
 
   if (patterns.size == 0) {
-    ADD(patterns, STRING_OBJ(STATIC_CSTR_TO_STRING("*")));
+    ADD(patterns, STATIC_CSTR_TO_OBJ("*"));
   }
 
-  if (event_array.size == 0) {
-    api_set_error(err, kErrorTypeValidation, "'event' is a required key");
+  VALIDATE_R((event_array.size > 0), "event", {
     goto cleanup;
-  }
+  });
 
   autocmd_id = next_autocmd_id++;
   FOREACH_ITEM(event_array, event_str, {
@@ -535,8 +494,8 @@ Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autoc
                                   pat.data.string.data,
                                   (int)pat.data.string.size,
                                   au_group,
-                                  is_once,
-                                  is_nested,
+                                  opts->once,
+                                  opts->nested,
                                   desc,
                                   aucmd);
       });
@@ -556,25 +515,22 @@ cleanup:
   return autocmd_id;
 }
 
-/// Delete an autocommand by id.
+/// Deletes an autocommand by id.
 ///
-/// NOTE: Only autocommands created via the API have an id.
-/// @param id Integer The id returned by nvim_create_autocmd
-/// @see |nvim_create_autocmd()|
+/// @param id Integer Autocommand id returned by |nvim_create_autocmd()|
 void nvim_del_autocmd(Integer id, Error *err)
   FUNC_API_SINCE(9)
 {
-  if (id <= 0) {
-    api_set_error(err, kErrorTypeException, "Invalid autocmd id");
+  VALIDATE_INT((id > 0), "autocmd id", id, {
     return;
-  }
+  });
   if (!autocmd_delete_id(id)) {
     api_set_error(err, kErrorTypeException, "Failed to delete autocmd");
   }
 }
 
-/// Clear all autocommands that match the corresponding {opts}. To delete
-/// a particular autocmd, see |nvim_del_autocmd()|.
+/// Clears all autocommands selected by {opts}. To delete autocmds see |nvim_del_autocmd()|.
+///
 /// @param opts Parameters
 ///         - event: (string|table)
 ///              Examples:
@@ -610,25 +566,26 @@ void nvim_clear_autocmds(Dict(clear_autocmds) *opts, Error *err)
     goto cleanup;
   }
 
-  if (opts->pattern.type != kObjectTypeNil && opts->buffer.type != kObjectTypeNil) {
-    api_set_error(err, kErrorTypeValidation,
-                  "Cannot use both 'pattern' and 'buffer'");
+  bool has_buffer = HAS_KEY(opts, clear_autocmds, buffer);
+
+  VALIDATE((!HAS_KEY(opts, clear_autocmds, pattern) || !has_buffer),
+           "%s", "Cannot use both 'pattern' and 'buffer'", {
     goto cleanup;
-  }
+  });
 
   int au_group = get_augroup_from_object(opts->group, err);
   if (au_group == AUGROUP_ERROR) {
     goto cleanup;
   }
 
-  if (!get_patterns_from_pattern_or_buf(&patterns, opts->pattern, opts->buffer, err)) {
+  if (!get_patterns_from_pattern_or_buf(&patterns, opts->pattern, has_buffer, opts->buffer, err)) {
     goto cleanup;
   }
 
   // When we create the autocmds, we want to say that they are all matched, so that's *
   // but when we clear them, we want to say that we didn't pass a pattern, so that's NUL
   if (patterns.size == 0) {
-    ADD(patterns, STRING_OBJ(STATIC_CSTR_TO_STRING("")));
+    ADD(patterns, STATIC_CSTR_TO_OBJ(""));
   }
 
   // If we didn't pass any events, that means clear all events.
@@ -636,7 +593,7 @@ void nvim_clear_autocmds(Dict(clear_autocmds) *opts, Error *err)
     FOR_ALL_AUEVENTS(event) {
       FOREACH_ITEM(patterns, pat_object, {
         char *pat = pat_object.data.string.data;
-        if (!clear_autocmd(event, (char *)pat, au_group, err)) {
+        if (!clear_autocmd(event, pat, au_group, err)) {
           goto cleanup;
         }
       });
@@ -647,7 +604,7 @@ void nvim_clear_autocmds(Dict(clear_autocmds) *opts, Error *err)
 
       FOREACH_ITEM(patterns, pat_object, {
         char *pat = pat_object.data.string.data;
-        if (!clear_autocmd(event_nr, (char *)pat, au_group, err)) {
+        if (!clear_autocmd(event_nr, pat, au_group, err)) {
           goto cleanup;
         }
       });
@@ -662,11 +619,12 @@ cleanup:
 /// Create or get an autocommand group |autocmd-groups|.
 ///
 /// To get an existing group id, do:
-/// <pre>lua
-///     local id = vim.api.nvim_create_augroup("MyGroup", {
-///         clear = false
-///     })
-/// </pre>
+///
+/// ```lua
+/// local id = vim.api.nvim_create_augroup("MyGroup", {
+///     clear = false
+/// })
+/// ```
 ///
 /// @param name String: The name of the group
 /// @param opts Dictionary Parameters
@@ -691,7 +649,7 @@ Integer nvim_create_augroup(uint64_t channel_id, String name, Dict(create_augrou
 
     if (clear_autocmds) {
       FOR_ALL_AUEVENTS(event) {
-        aupat_del_for_event_and_group(event, augroup);