API: nvim_get_commands(): always return keys

- Always return all keys, with at least NIL value.
- Require `opts` param to be {"builtin":false}
- Validate `opts` param

5 files changed, 128 insertions, 94 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index c4508a0c81..878c8aad87 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -479,12 +479,11 @@ ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
   return keymap_array(mode, buf);
 }
 
-/// Gets a list of dictionaries describing buffer-local commands.
-/// The "buffer" key in the returned dictionary reflects the buffer
-/// handle where the command is present.
+/// Gets a list of maps describing buffer-local |user-commands|.
 ///
-/// @param  buffer     Buffer handle.
-/// @param  opts       Optional parameters, currently always 
+/// @param  buffer  Buffer handle.
+/// @param  opts  Optional parameters. Currently only supports
+///               {"builtin":false}
 /// @param[out]  err   Error details, if any.
 ///
 /// @returns Array of dictionaries describing commands.
@@ -492,6 +491,25 @@ ArrayOf(Dictionary) nvim_buf_get_commands(Buffer buffer, Dictionary opts,
                                           Error *err)
     FUNC_API_SINCE(4)
 {
+  for (size_t i = 0; i < opts.size; i++) {
+    String k = opts.items[i].key;
+    Object v = opts.items[i].value;
+    if (!strequal("builtin", k.data)) {
+      api_set_error(err, kErrorTypeValidation, "unexpected key: %s",
+                    k.data);
+      return (Array)ARRAY_DICT_INIT;
+    }
+    if (v.type != kObjectTypeBoolean || v.data.boolean != false) {
+      api_set_error(err, kErrorTypeValidation,
+                    "builtin commands not supported yet");
+      return (Array)ARRAY_DICT_INIT;
+    }
+  }
+
+  if (buffer == -1) {
+    return commands_array(NULL);
+  }
+
   buf_T *buf = find_buffer_by_handle(buffer, err);
   if (!buf) {
     return (Array)ARRAY_DICT_INIT;
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index 03f1a882d3..17ee3ed711 100644
--- a/src/nvim/api/private/helpers.c
+++ b/src/nvim/api/private/helpers.c
@@ -685,7 +685,7 @@ tabpage_T *find_tab_by_handle(Tabpage tabpage, Error *err)
 String cchar_to_string(char c)
 {
   char buf[] = { c, NUL };
-  return (String) {
+  return (String){
     .data = xmemdupz(buf, 1),
     .size = (c != NUL) ? 1 : 0
   };
@@ -701,13 +701,13 @@ String cchar_to_string(char c)
 String cstr_to_string(const char *str)
 {
     if (str == NULL) {
-      return (String) STRING_INIT;
+      return (String)STRING_INIT;
     }
 
     size_t len = strlen(str);
-    return (String) {
-        .data = xmemdupz(str, len),
-        .size = len
+    return (String){
+      .data = xmemdupz(str, len),
+      .size = len,
     };
 }
 
@@ -722,7 +722,7 @@ String cstr_to_string(const char *str)
 String cbuf_to_string(const char *buf, size_t size)
   FUNC_ATTR_NONNULL_ALL
 {
-  return (String) {
+  return (String){
     .data = xmemdupz(buf, size),
     .size = size
   };
@@ -737,9 +737,9 @@ String cbuf_to_string(const char *buf, size_t size)
 String cstr_as_string(char *str) FUNC_ATTR_PURE
 {
   if (str == NULL) {
-    return (String) STRING_INIT;
+    return (String)STRING_INIT;
   }
-  return (String) { .data = str, .size = strlen(str) };
+  return (String){ .data = str, .size = strlen(str) };
 }
 
 /// Converts from type Object to a VimL value.
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 38e64fd6ed..065b8d1ce2 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -959,17 +959,17 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
   return keymap_array(mode, NULL);
 }
 
-/// Gets a list of dictionaries describing global(non-buffer) commands.
+/// Gets a list of maps describing global |user-commands|.
 ///
-/// @param  opts       Holds the API Metadata describing what type of commands
-///                    are needed.
+/// @param  opts  Optional parameters. Currently only supports
+///               {"builtin":false}
 /// @param[out]  err   Error details, if any.
 ///
 /// @returns Array of dictionaries describing commands.
 ArrayOf(Dictionary) nvim_get_commands(Dictionary opts, Error *err)
     FUNC_API_SINCE(4)
 {
-  return commands_array(NULL);
+  return nvim_buf_get_commands(-1, opts, err);
 }
 
 /// Returns a 2-tuple (Array), where item 0 is the current channel id and item
diff --git a/src/nvim/ex_docmd.c b/src/nvim/ex_docmd.c
index 4cdb0d2cf1..121b913bb7 100644
--- a/src/nvim/ex_docmd.c
+++ b/src/nvim/ex_docmd.c
@@ -9972,28 +9972,26 @@ bool cmd_can_preview(char_u *cmd)
 /// Gets a list of maps describing user-commands defined for buffer `buf`
 /// or defined globally if `buf` is NULL.
 ///
-/// @param buf  Buffer to inspect, or NULL to get global commands.
+/// @param buf  Buffer to inspect, or NULL to get global user-commands.
 ///
 /// @return Array of dictionaries describing commands
 ArrayOf(Dictionary) commands_array(buf_T *buf)
 {
   Array rv = ARRAY_DICT_INIT;
-  garray_T *gap;
-  if (buf == NULL) {
-    gap = &ucmds;
-  } else {
-    gap = &buf->b_ucmds;
-  }
+  Object obj = NIL;
+  char str[10];
+  garray_T *gap = (buf == NULL) ? &ucmds : &buf->b_ucmds;
+
   for (int i = 0; i < gap->ga_len; i++) {
     char arg[2] = { 0, 0 };
     Dictionary d = ARRAY_DICT_INIT;
-    char Range[10] = "";
     ucmd_T *cmd = USER_CMD_GA(gap, i);
 
-    // Name
     PUT(d, "name", STRING_OBJ(cstr_to_string((char *)cmd->uc_name)));
+    PUT(d, "definition", STRING_OBJ(cstr_to_string((char *)cmd->uc_rep)));
+    PUT(d, "script_id", INTEGER_OBJ(cmd->uc_scriptID));
 
-    // Argument
+    // "nargs" key
     switch (cmd->uc_argt & (EXTRA|NOSPC|NEEDARG)) {
     case 0:                    arg[0] = '0'; break;
     case(EXTRA):               arg[0] = '*'; break;
@@ -10001,52 +9999,47 @@ ArrayOf(Dictionary) commands_array(buf_T *buf)
     case(EXTRA|NEEDARG):       arg[0] = '+'; break;
     case(EXTRA|NOSPC|NEEDARG): arg[0] = '1'; break;
     }
-    PUT(d, "nargs", STRING_OBJ(cstr_to_string((char *)arg)));
-
-    // Definition
-    PUT(d, "definition", STRING_OBJ(cstr_to_string((char *)cmd->uc_rep)));
+    PUT(d, "nargs", STRING_OBJ(cstr_to_string(arg)));
 
-    // Complete
     char *cmd_compl = get_command_complete(cmd->uc_compl);
-    if (cmd_compl != NULL) {
-      PUT(d, "complete", STRING_OBJ(cstr_to_string(cmd_compl)));
-    }
-
-    // Complete Arg
-    if (cmd->uc_compl_arg != NULL) {
-      PUT(d, "complete_arg",
-          STRING_OBJ(cstr_to_string((char *)cmd->uc_compl_arg)));
+    PUT(d, "complete", (cmd_compl == NULL
+                        ? NIL : STRING_OBJ(cstr_to_string(cmd_compl))));
+    PUT(d, "complete_arg", cmd->uc_compl_arg == NULL
+        ? NIL : STRING_OBJ(cstr_to_string((char *)cmd->uc_compl_arg)));
+
+    obj = NIL;
+    if (cmd->uc_argt & COUNT) {
+      if (cmd->uc_def >= 0) {
+        snprintf(str, sizeof(str), "%" PRId64, (int64_t)cmd->uc_def);
+        obj = STRING_OBJ(cstr_to_string(str));    // -count=N
+      } else {
+        obj = STRING_OBJ(cstr_to_string("0"));    // -count
+      }
     }
+    PUT(d, "count", obj);
 
-    // Range
-    if (cmd->uc_argt & (RANGE|COUNT)) {
-      if (cmd->uc_argt & COUNT) {
-        // -count=N
-        snprintf((char *)Range, sizeof(Range), "%" PRId64 "c",
-                 (int64_t)cmd->uc_def);
-      } else if (cmd->uc_argt & DFLALL) {
-        Range[0] = '%';
+    obj = NIL;
+    if (cmd->uc_argt & RANGE) {
+      if (cmd->uc_argt & DFLALL) {
+        obj = STRING_OBJ(cstr_to_string("%"));    // -range=%
       } else if (cmd->uc_def >= 0) {
-        // -range=N
-        snprintf((char *)Range, sizeof(Range), "%" PRId64 "",
-                 (int64_t)cmd->uc_def);
+        snprintf(str, sizeof(str), "%" PRId64, (int64_t)cmd->uc_def);
+        obj = STRING_OBJ(cstr_to_string(str));    // -range=N
       } else {
-        Range[0] = '.';
+        obj = STRING_OBJ(cstr_to_string("."));    // -range
       }
-      PUT(d, "range", STRING_OBJ(cstr_to_string((char *)Range)));
     }
+    PUT(d, "range", obj);
 
-    // Address
+    obj = NIL;
     for (int j = 0; addr_type_complete[j].expand != -1; j++) {
       if (addr_type_complete[j].expand != ADDR_LINES
           && addr_type_complete[j].expand == cmd->uc_addr_type) {
-        PUT(d, "addr", STRING_OBJ(cstr_to_string(addr_type_complete[j].name)));
+        obj = STRING_OBJ(cstr_to_string(addr_type_complete[j].name));
         break;
       }
     }
-
-    // ScriptID
-    PUT(d, "script_id", INTEGER_OBJ(cmd->uc_scriptID));
+    PUT(d, "addr", obj);
 
     ADD(rv, DICTIONARY_OBJ(d));
   }
diff --git a/test/functional/api/command_spec.lua b/test/functional/api/command_spec.lua
index db03edf6d2..d24cdc0493 100644
--- a/test/functional/api/command_spec.lua
+++ b/test/functional/api/command_spec.lua
@@ -1,74 +1,97 @@
 local helpers = require('test.functional.helpers')(after_each)
 
+local NIL = helpers.NIL
 local clear = helpers.clear
 local command = helpers.command
 local curbufmeths = helpers.curbufmeths
 local eq = helpers.eq
+local expect_err = helpers.expect_err
 local meths = helpers.meths
+local source = helpers.source
 
 describe('nvim_get_commands', function()
-  local dummy_dict = {dummy=''}
-  local cmd_string = 'command Hello echo "Hello World"'
-  local cmd_string2 = 'command Pwd pwd'
   local cmd_dict = {
+    addr=NIL,
+    complete=NIL,
+    complete_arg=NIL,
+    count=NIL,
+    definition='echo "Hello World"',
     name='Hello',
-    nargs='0',
+    nargs='1',
+    range=NIL,
     script_id=0,
-    definition='echo "Hello World"',
   }
   local cmd_dict2 = {
+    addr=NIL,
+    complete=NIL,
+    complete_arg=NIL,
+    count=NIL,
+    definition='pwd',
     name='Pwd',
-    nargs='0',
+    nargs='?',
+    range=NIL,
     script_id=0,
-    definition='pwd',
   }
   before_each(clear)
   it('gets empty list if no commands were defined', function()
-    eq({}, meths.get_commands(dummy_dict))
+    eq({}, meths.get_commands({builtin=false}))
   end)
-  it('gets user-def commands', function()
-    -- Insert a command
-    command(cmd_string)
-    eq({cmd_dict}, meths.get_commands(dummy_dict))
-    -- Insert a another command
-    command(cmd_string2);
-    eq({cmd_dict, cmd_dict2}, meths.get_commands(dummy_dict))
-    -- Delete a command
+  it('validates input', function()
+    expect_err('builtin commands not supported yet', meths.get_commands,
+               {builtin=true})
+    expect_err('unexpected key: foo', meths.get_commands,
+               {foo='blah'})
+  end)
+  it('gets global user-defined commands', function()
+    -- Define a command.
+    command('command -nargs=1 Hello echo "Hello World"')
+    eq({cmd_dict}, meths.get_commands({builtin=false}))
+    -- Define another command.
+    command('command -nargs=? Pwd pwd');
+    eq({cmd_dict, cmd_dict2}, meths.get_commands({builtin=false}))
+    -- Delete a command.
     command('delcommand Pwd')
-    eq({cmd_dict}, meths.get_commands(dummy_dict))
+    eq({cmd_dict}, meths.get_commands({builtin=false}))
   end)
-  it('considers different buffers', function()
-    -- Insert a command
-    command('command -buffer Hello echo "Hello World"')
-    eq({cmd_dict}, curbufmeths.get_commands(dummy_dict))
-    -- Insert a another command
-    command('command -buffer Pwd pwd')
-    eq({cmd_dict, cmd_dict2}, curbufmeths.get_commands(dummy_dict))
-    -- Delete a command
+  it('gets buffer-local user-defined commands', function()
+    -- Define a buffer-local command.
+    command('command -buffer -nargs=1 Hello echo "Hello World"')
+    eq({cmd_dict}, curbufmeths.get_commands({builtin=false}))
+    -- Define another buffer-local command.
+    command('command -buffer -nargs=? Pwd pwd')
+    eq({cmd_dict, cmd_dict2}, curbufmeths.get_commands({builtin=false}))
+    -- Delete a command.
     command('delcommand Pwd')
-    eq({cmd_dict}, curbufmeths.get_commands(dummy_dict))
+    eq({cmd_dict}, curbufmeths.get_commands({builtin=false}))
   end)
   it('gets different attributes of different commands', function()
     local cmd1 = {
+      addr=NIL,
       complete='custom',
-      nargs='1',
-      name='Finger',
-      script_id=0,
       complete_arg='ListUsers',
+      count=NIL,
       definition='!finger <args>',
+      name='Finger',
+      nargs='+',
+      range=NIL,
+      script_id=1,
     }
     local cmd2 = {
+      addr='arguments',
       complete='dir',
-      nargs='0',
+      complete_arg=NIL,
+      count='10',
+      definition='pwd <args>',
       name='TestCmd',
-      range='10c',
-      addr='arguments',
+      nargs='0',
+      range='10',
       script_id=0,
-      definition='pwd <args>',
     }
-    command('command -complete=custom,ListUsers -nargs=1 Finger !finger <args>')
-    eq({cmd1}, meths.get_commands(dummy_dict))
+    source([[
+      command -complete=custom,ListUsers -nargs=+ Finger !finger <args>
+    ]])
+    eq({cmd1}, meths.get_commands({builtin=false}))
     command('command -complete=dir -addr=arguments -count=10 TestCmd pwd <args>')
-    eq({cmd1, cmd2}, meths.get_commands(dummy_dict))
+    eq({cmd1, cmd2}, meths.get_commands({builtin=false}))
   end)
 end)