Merge #11021 from justinmk/ctx-rename-buflist

API: Context: "opts" param, et al.

9 files changed, 98 insertions, 67 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 18129e8c39..98dd330b48 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1027,13 +1027,14 @@ nvim_get_color_map()                                    *nvim_get_color_map()*
                 Return: ~
                     Map of color names and RGB values.
 
-nvim_get_context({types})                                 *nvim_get_context()*
+nvim_get_context({opts})                                  *nvim_get_context()*
                 Gets a map of the current editor state.
 
                 Parameters: ~
-                    {types}  Context types ("regs", "jumps", "buflist",
-                             "gvars", ...) to gather, or NIL for all (see
-                             |context-types|).
+                    {opts}  Optional parameters.
+                            • types: List of |context-types| ("regs", "jumps",
+                              "bufs", "gvars", …) to gather, or empty for
+                              "all".
 
                 Return: ~
                     map of global |context|.
diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt
index 8f6d3aec2e..d4b6324bc3 100644
--- a/runtime/doc/repeat.txt
+++ b/runtime/doc/repeat.txt
@@ -1003,14 +1003,14 @@ like the current |jumplist|, values of |registers|, and more, described below.
 The following Context items are supported:
 	"jumps"		|jumplist|
 	"regs"		|registers|
-	"buflist"	|buffer-list|
+	"bufs"		|buffer-list|
 	"gvars"		|global-variable|s
 	"sfuncs"	|script-local| functions
 	"funcs"		global and |script-local| functions
 
 							*context-dict*
 Context objects are dictionaries with the following key-value pairs:
-- "jumps", "regs", "buflist", "gvars":
+- "jumps", "regs", "bufs", "gvars":
       |readfile()|-style |List| representation of corresponding msgpack
       objects (see |msgpackdump()| and |msgpackparse()|).
 - "funcs" (includes |script-local| functions as well):
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 5480bb5173..602733fd31 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1418,32 +1418,52 @@ Dictionary nvim_get_color_map(void)
 
 /// Gets a map of the current editor state.
 ///
-/// @param  types  Context types ("regs", "jumps", "buflist", "gvars", ...)
-///                to gather, or NIL for all (see |context-types|).
+/// @param opts  Optional parameters.
+///               - types:  List of |context-types| ("regs", "jumps", "bufs",
+///                 "gvars", …) to gather, or empty for "all".
+/// @param[out]  err  Error details, if any
 ///
 /// @return map of global |context|.
-Dictionary nvim_get_context(Array types)
+Dictionary nvim_get_context(Dictionary opts, Error *err)
   FUNC_API_SINCE(6)
 {
-  int int_types = 0;
-  if (types.size == 1 && types.items[0].type == kObjectTypeNil) {
-    int_types = kCtxAll;
-  } else {
+  Array types = ARRAY_DICT_INIT;
+  for (size_t i = 0; i < opts.size; i++) {
+    String k = opts.items[i].key;
+    Object v = opts.items[i].value;
+    if (strequal("types", k.data)) {
+      if (v.type != kObjectTypeArray) {
+        api_set_error(err, kErrorTypeValidation, "invalid value for key: %s",
+                      k.data);
+        return (Dictionary)ARRAY_DICT_INIT;
+      }
+      types = v.data.array;
+    } else {
+      api_set_error(err, kErrorTypeValidation, "unexpected key: %s", k.data);
+      return (Dictionary)ARRAY_DICT_INIT;
+    }
+  }
+
+  int int_types = types.size > 0 ? 0 : kCtxAll;
+  if (types.size > 0) {
     for (size_t i = 0; i < types.size; i++) {
       if (types.items[i].type == kObjectTypeString) {
-        const char *const current = types.items[i].data.string.data;
-        if (strequal(current, "regs")) {
+        const char *const s = types.items[i].data.string.data;
+        if (strequal(s, "regs")) {
           int_types |= kCtxRegs;
-        } else if (strequal(current, "jumps")) {
+        } else if (strequal(s, "jumps")) {
           int_types |= kCtxJumps;
-        } else if (strequal(current, "buflist")) {
-          int_types |= kCtxBuflist;
-        } else if (strequal(current, "gvars")) {
+        } else if (strequal(s, "bufs")) {
+          int_types |= kCtxBufs;
+        } else if (strequal(s, "gvars")) {
           int_types |= kCtxGVars;
-        } else if (strequal(current, "sfuncs")) {
+        } else if (strequal(s, "sfuncs")) {
           int_types |= kCtxSFuncs;
-        } else if (strequal(current, "funcs")) {
+        } else if (strequal(s, "funcs")) {
           int_types |= kCtxFuncs;
+        } else {
+          api_set_error(err, kErrorTypeValidation, "unexpected type: %s", s);
+          return (Dictionary)ARRAY_DICT_INIT;
         }
       }
     }
diff --git a/src/nvim/context.c b/src/nvim/context.c
index b2a2fd3fd9..2f872ff2bf 100644
--- a/src/nvim/context.c
+++ b/src/nvim/context.c
@@ -15,7 +15,7 @@
 # include "context.c.generated.h"
 #endif
 
-int kCtxAll = (kCtxRegs | kCtxJumps | kCtxBuflist | kCtxGVars | kCtxSFuncs
+int kCtxAll = (kCtxRegs | kCtxJumps | kCtxBufs | kCtxGVars | kCtxSFuncs
                | kCtxFuncs);
 
 static ContextVec ctx_stack = KV_INITIAL_VALUE;
@@ -57,8 +57,8 @@ void ctx_free(Context *ctx)
   if (ctx->jumps.data) {
     msgpack_sbuffer_destroy(&ctx->jumps);
   }
-  if (ctx->buflist.data) {
-    msgpack_sbuffer_destroy(&ctx->buflist);
+  if (ctx->bufs.data) {
+    msgpack_sbuffer_destroy(&ctx->bufs);
   }
   if (ctx->gvars.data) {
     msgpack_sbuffer_destroy(&ctx->gvars);
@@ -90,8 +90,8 @@ void ctx_save(Context *ctx, const int flags)
     ctx_save_jumps(ctx);
   }
 
-  if (flags & kCtxBuflist) {
-    ctx_save_buflist(ctx);
+  if (flags & kCtxBufs) {
+    ctx_save_bufs(ctx);
   }
 
   if (flags & kCtxGVars) {
@@ -137,8 +137,8 @@ bool ctx_restore(Context *ctx, const int flags)
     ctx_restore_jumps(ctx);
   }
 
-  if (flags & kCtxBuflist) {
-    ctx_restore_buflist(ctx);
+  if (flags & kCtxBufs) {
+    ctx_restore_bufs(ctx);
   }
 
   if (flags & kCtxGVars) {
@@ -200,20 +200,20 @@ static inline void ctx_restore_jumps(Context *ctx)
 /// Saves the buffer list to a context.
 ///
 /// @param  ctx  Save to this context.
-static inline void ctx_save_buflist(Context *ctx)
+static inline void ctx_save_bufs(Context *ctx)
   FUNC_ATTR_NONNULL_ALL
 {
-  msgpack_sbuffer_init(&ctx->buflist);
-  shada_encode_buflist(&ctx->buflist);
+  msgpack_sbuffer_init(&ctx->bufs);
+  shada_encode_buflist(&ctx->bufs);
 }
 
 /// Restores the buffer list from a context.
 ///
 /// @param  ctx  Restore from this context.
-static inline void ctx_restore_buflist(Context *ctx)
+static inline void ctx_restore_bufs(Context *ctx)
   FUNC_ATTR_NONNULL_ALL
 {
-  shada_read_sbuf(&ctx->buflist, kShaDaWantInfo | kShaDaForceit);
+  shada_read_sbuf(&ctx->bufs, kShaDaWantInfo | kShaDaForceit);
 }
 
 /// Saves global variables to a context.
@@ -337,7 +337,7 @@ Dictionary ctx_to_dict(Context *ctx)
 
   PUT(rv, "regs", ARRAY_OBJ(sbuf_to_array(ctx->regs)));
   PUT(rv, "jumps", ARRAY_OBJ(sbuf_to_array(ctx->jumps)));
-  PUT(rv, "buflist", ARRAY_OBJ(sbuf_to_array(ctx->buflist)));
+  PUT(rv, "bufs", ARRAY_OBJ(sbuf_to_array(ctx->bufs)));
   PUT(rv, "gvars", ARRAY_OBJ(sbuf_to_array(ctx->gvars)));
   PUT(rv, "funcs", ARRAY_OBJ(copy_array(ctx->funcs)));
 
@@ -367,9 +367,9 @@ int ctx_from_dict(Dictionary dict, Context *ctx)
     } else if (strequal(item.key.data, "jumps")) {
       types |= kCtxJumps;
       ctx->jumps = array_to_sbuf(item.value.data.array);
-    } else if (strequal(item.key.data, "buflist")) {
-      types |= kCtxBuflist;
-      ctx->buflist = array_to_sbuf(item.value.data.array);
+    } else if (strequal(item.key.data, "bufs")) {
+      types |= kCtxBufs;
+      ctx->bufs = array_to_sbuf(item.value.data.array);
     } else if (strequal(item.key.data, "gvars")) {
       types |= kCtxGVars;
       ctx->gvars = array_to_sbuf(item.value.data.array);
diff --git a/src/nvim/context.h b/src/nvim/context.h
index 328e12c6a6..7edd63ced2 100644
--- a/src/nvim/context.h
+++ b/src/nvim/context.h
@@ -8,7 +8,7 @@
 typedef struct {
   msgpack_sbuffer regs;     ///< Registers.
   msgpack_sbuffer jumps;    ///< Jumplist.
-  msgpack_sbuffer buflist;  ///< Buffer list.
+  msgpack_sbuffer bufs;     ///< Buffer list.
   msgpack_sbuffer gvars;    ///< Global variables.
   Array funcs;              ///< Functions.
 } Context;
@@ -23,7 +23,7 @@ typedef kvec_t(Context) ContextVec;
 #define CONTEXT_INIT (Context) { \
   .regs = MSGPACK_SBUFFER_INIT, \
   .jumps = MSGPACK_SBUFFER_INIT, \
-  .buflist = MSGPACK_SBUFFER_INIT, \
+  .bufs = MSGPACK_SBUFFER_INIT, \
   .gvars = MSGPACK_SBUFFER_INIT, \
   .funcs = ARRAY_DICT_INIT, \
 }
@@ -31,7 +31,7 @@ typedef kvec_t(Context) ContextVec;
 typedef enum {
   kCtxRegs = 1,       ///< Registers
   kCtxJumps = 2,      ///< Jumplist
-  kCtxBuflist = 4,    ///< Buffer list
+  kCtxBufs = 4,       ///< Buffer list
   kCtxGVars = 8,      ///< Global variables
   kCtxSFuncs = 16,    ///< Script functions
   kCtxFuncs = 32,     ///< Functions
diff --git a/src/nvim/eval.c b/src/nvim/eval.c
index 00b9fcf646..1f753608d2 100644
--- a/src/nvim/eval.c
+++ b/src/nvim/eval.c
@@ -8002,8 +8002,8 @@ static void f_ctxpush(typval_T *argvars, typval_T *rettv, FunPtr fptr)
           types |= kCtxRegs;
         } else if (strequal((char *)tv_li->vval.v_string, "jumps")) {
           types |= kCtxJumps;
-        } else if (strequal((char *)tv_li->vval.v_string, "buflist")) {
-          types |= kCtxBuflist;
+        } else if (strequal((char *)tv_li->vval.v_string, "bufs")) {
+          types |= kCtxBufs;
         } else if (strequal((char *)tv_li->vval.v_string, "gvars")) {
           types |= kCtxGVars;
         } else if (strequal((char *)tv_li->vval.v_string, "sfuncs")) {
diff --git a/test/functional/api/vim_spec.lua b/test/functional/api/vim_spec.lua
index c34e7a0945..8b77dbcaa6 100644
--- a/test/functional/api/vim_spec.lua
+++ b/test/functional/api/vim_spec.lua
@@ -894,9 +894,17 @@ describe('API', function()
   end)
 
   describe('nvim_get_context', function()
-    it('returns context dictionary of current editor state', function()
-      local ctx_items = {'regs', 'jumps', 'buflist', 'gvars'}
-      eq({}, parse_context(nvim('get_context', ctx_items)))
+    it('validates args', function()
+      eq('unexpected key: blah',
+        pcall_err(nvim, 'get_context', {blah={}}))
+      eq('invalid value for key: types',
+        pcall_err(nvim, 'get_context', {types=42}))
+      eq('unexpected type: zub',
+        pcall_err(nvim, 'get_context', {types={'jumps', 'zub', 'zam',}}))
+    end)
+    it('returns map of current editor state', function()
+      local opts = {types={'regs', 'jumps', 'bufs', 'gvars'}}
+      eq({}, parse_context(nvim('get_context', {})))
 
       feed('i1<cr>2<cr>3<c-[>ddddddqahjklquuu')
       feed('gg')
@@ -921,26 +929,28 @@ describe('API', function()
           { k, v -> k != "l" || v != 1 })'), '!empty(v:val.f)')
         ]]):gsub('\n', '')),
 
-        ['buflist'] = eval([[
+        ['bufs'] = eval([[
         filter(map(getbufinfo(), '{ "f": v:val.name }'), '!empty(v:val.f)')
         ]]),
 
         ['gvars'] = {{'one', 1}, {'Two', 2}, {'THREE', 3}},
       }
 
-      eq(expected_ctx, parse_context(nvim('get_context', ctx_items)))
+      eq(expected_ctx, parse_context(nvim('get_context', opts)))
+      eq(expected_ctx, parse_context(nvim('get_context', {})))
+      eq(expected_ctx, parse_context(nvim('get_context', {types={}})))
     end)
   end)
 
   describe('nvim_load_context', function()
     it('sets current editor state to given context dictionary', function()
-      local ctx_items = {'regs', 'jumps', 'buflist', 'gvars'}
-      eq({}, parse_context(nvim('get_context', ctx_items)))
+      local opts = {types={'regs', 'jumps', 'bufs', 'gvars'}}
+      eq({}, parse_context(nvim('get_context', opts)))
 
       nvim('set_var', 'one', 1)
       nvim('set_var', 'Two', 2)
       nvim('set_var', 'THREE', 3)
-      local ctx = nvim('get_context', ctx_items)
+      local ctx = nvim('get_context', opts)
       nvim('set_var', 'one', 'a')
       nvim('set_var', 'Two', 'b')
       nvim('set_var', 'THREE', 'c')
diff --git a/test/functional/eval/ctx_functions_spec.lua b/test/functional/eval/ctx_functions_spec.lua
index 7dde5d3194..c81dad9645 100644
--- a/test/functional/eval/ctx_functions_spec.lua
+++ b/test/functional/eval/ctx_functions_spec.lua
@@ -82,21 +82,21 @@ describe('context functions', function()
       command('edit '..fname1)
       command('edit '..fname2)
       command('edit TEST')
-      local buflist = call('map', call('getbufinfo'), 'v:val.name')
+      local bufs = call('map', call('getbufinfo'), 'v:val.name')
       call('ctxpush')
-      call('ctxpush', {'buflist'})
+      call('ctxpush', {'bufs'})
 
       command('%bwipeout')
       eq({''}, call('map', call('getbufinfo'), 'v:val.name'))
 
       call('ctxpop')
-      eq({'', unpack(buflist)}, call('map', call('getbufinfo'), 'v:val.name'))
+      eq({'', unpack(bufs)}, call('map', call('getbufinfo'), 'v:val.name'))
 
       command('%bwipeout')
       eq({''}, call('map', call('getbufinfo'), 'v:val.name'))
 
       call('ctxpop')
-      eq({'', unpack(buflist)}, call('map', call('getbufinfo'), 'v:val.name'))
+      eq({'', unpack(bufs)}, call('map', call('getbufinfo'), 'v:val.name'))
     end)
 
     it('saves and restores global variables properly', function()
@@ -297,8 +297,8 @@ describe('context functions', function()
         ]]):gsub('\n', ''))
       }
 
-      local with_buflist = {
-        ['buflist'] = eval([[
+      local with_bufs = {
+        ['bufs'] = eval([[
         filter(map(getbufinfo(), '{ "f": v:val.name }'), '!empty(v:val.f)')
         ]])
       }
@@ -310,7 +310,7 @@ describe('context functions', function()
       local with_all = {
         ['regs'] = with_regs['regs'],
         ['jumps'] = with_jumps['jumps'],
-        ['buflist'] = with_buflist['buflist'],
+        ['bufs'] = with_bufs['bufs'],
         ['gvars'] = with_gvars['gvars'],
       }
 
@@ -323,16 +323,16 @@ describe('context functions', function()
       eq(with_gvars, parse_context(call('ctxget', 0)))
       eq(with_all, parse_context(call('ctxget', 1)))
 
-      call('ctxpush', {'buflist'})
-      eq(with_buflist, parse_context(call('ctxget')))
-      eq(with_buflist, parse_context(call('ctxget', 0)))
+      call('ctxpush', {'bufs'})
+      eq(with_bufs, parse_context(call('ctxget')))
+      eq(with_bufs, parse_context(call('ctxget', 0)))
       eq(with_gvars, parse_context(call('ctxget', 1)))
       eq(with_all, parse_context(call('ctxget', 2)))
 
       call('ctxpush', {'jumps'})
       eq(with_jumps, parse_context(call('ctxget')))
       eq(with_jumps, parse_context(call('ctxget', 0)))
-      eq(with_buflist, parse_context(call('ctxget', 1)))
+      eq(with_bufs, parse_context(call('ctxget', 1)))
       eq(with_gvars, parse_context(call('ctxget', 2)))
       eq(with_all, parse_context(call('ctxget', 3)))
 
@@ -340,20 +340,20 @@ describe('context functions', function()
       eq(with_regs, parse_context(call('ctxget')))
       eq(with_regs, parse_context(call('ctxget', 0)))
       eq(with_jumps, parse_context(call('ctxget', 1)))
-      eq(with_buflist, parse_context(call('ctxget', 2)))
+      eq(with_bufs, parse_context(call('ctxget', 2)))
       eq(with_gvars, parse_context(call('ctxget', 3)))
       eq(with_all, parse_context(call('ctxget', 4)))
 
       call('ctxpop')
       eq(with_jumps, parse_context(call('ctxget')))
       eq(with_jumps, parse_context(call('ctxget', 0)))
-      eq(with_buflist, parse_context(call('ctxget', 1)))
+      eq(with_bufs, parse_context(call('ctxget', 1)))
       eq(with_gvars, parse_context(call('ctxget', 2)))
       eq(with_all, parse_context(call('ctxget', 3)))
 
       call('ctxpop')
-      eq(with_buflist, parse_context(call('ctxget')))
-      eq(with_buflist, parse_context(call('ctxget', 0)))
+      eq(with_bufs, parse_context(call('ctxget')))
+      eq(with_bufs, parse_context(call('ctxget', 0)))
       eq(with_gvars, parse_context(call('ctxget', 1)))
       eq(with_all, parse_context(call('ctxget', 2)))
 
diff --git a/test/functional/helpers.lua b/test/functional/helpers.lua
index 2cf81ed4d0..b29161e34c 100644
--- a/test/functional/helpers.lua
+++ b/test/functional/helpers.lua
@@ -777,12 +777,12 @@ end
 
 function module.parse_context(ctx)
   local parsed = {}
-  for _, item in ipairs({'regs', 'jumps', 'buflist', 'gvars'}) do
+  for _, item in ipairs({'regs', 'jumps', 'bufs', 'gvars'}) do
     parsed[item] = filter(function(v)
       return type(v) == 'table'
     end, module.call('msgpackparse', ctx[item]))
   end
-  parsed['buflist'] = parsed['buflist'][1]
+  parsed['bufs'] = parsed['bufs'][1]
   return map(function(v)
     if #v == 0 then
       return nil