Merge #8375 'API: nvim_get_commands'

closes #7833
ref #8029

src/nvim/api/buffer.c

@@ -24,6 +24,7 @@
 #include "nvim/syntax.h"
 #include "nvim/window.h"
 #include "nvim/undo.h"
+#include "nvim/ex_docmd.h"
 
 #ifdef INCLUDE_GENERATED_DECLARATIONS
 # include "api/buffer.c.generated.h"
@@ -458,16 +459,15 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
   return buf->b_changedtick;
 }
 
-/// Gets a list of dictionaries describing buffer-local mappings.
+/// Gets a list of buffer-local |mapping| definitions.
-/// The "buffer" key in the returned dictionary reflects the buffer
-/// handle where the mapping is present.
 ///
 /// @param  mode       Mode short-name ("n", "i", "v", ...)
 /// @param  buffer     Buffer handle
 /// @param[out]  err   Error details, if any
-/// @returns Array of maparg()-like dictionaries describing mappings
+/// @returns Array of maparg()-like dictionaries describing mappings.
+///          The "buffer" key holds the associated buffer handle.
 ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
-    FUNC_API_SINCE(3)
+  FUNC_API_SINCE(3)
 {
   buf_T *buf = find_buffer_by_handle(buffer, err);
 
@@ -478,6 +478,46 @@ ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
   return keymap_array(mode, buf);
 }
 
+/// Gets a map of buffer-local |user-commands|.
+///
+/// @param  buffer  Buffer handle.
+/// @param  opts  Optional parameters. Currently not used.
+/// @param[out]  err   Error details, if any.
+///
+/// @returns Map of maps describing commands.
+Dictionary nvim_buf_get_commands(Buffer buffer, Dictionary opts, Error *err)
+  FUNC_API_SINCE(4)
+{
+  bool global = (buffer == -1);
+  bool builtin = false;
+
+  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 (Dictionary)ARRAY_DICT_INIT;
+    }
+    if (strequal("builtin", k.data)) {
+      builtin = v.data.boolean;
+    }
+  }
+
+  if (global) {
+    if (builtin) {
+      api_set_error(err, kErrorTypeValidation, "builtin=true not implemented");
+      return (Dictionary)ARRAY_DICT_INIT;
+    }
+    return commands_array(NULL);
+  }
+
+  buf_T *buf = find_buffer_by_handle(buffer, err);
+  if (builtin || !buf) {
+    return (Dictionary)ARRAY_DICT_INIT;
+  }
+  return commands_array(buf);
+}
+
 /// Sets a buffer-scoped (b:) variable
 ///
 /// @param buffer     Buffer handle

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) {
+    return (String){
-        .data = xmemdupz(str, len),
+      .data = xmemdupz(str, len),
-        .size = 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.
@@ -1149,7 +1149,7 @@ void api_set_error(Error *err, ErrorType errType, const char *format, ...)
 ///
 /// @param  mode  The abbreviation for the mode
 /// @param  buf  The buffer to get the mapping array. NULL for global
-/// @returns An array of maparg() like dictionaries describing mappings
+/// @returns Array of maparg()-like dictionaries describing mappings
 ArrayOf(Dictionary) keymap_array(String mode, buf_T *buf)
 {
   Array mappings = ARRAY_DICT_INIT;

src/nvim/api/vim.c

@@ -948,17 +948,32 @@ Dictionary nvim_get_mode(void)
   return rv;
 }
 
-/// Gets a list of dictionaries describing global (non-buffer) mappings.
+/// Gets a list of global (non-buffer-local) |mapping| definitions.
-/// The "buffer" key in the returned dictionary is always zero.
 ///
 /// @param  mode       Mode short-name ("n", "i", "v", ...)
-/// @returns Array of maparg()-like dictionaries describing mappings
+/// @returns Array of maparg()-like dictionaries describing mappings.
+///          The "buffer" key is always zero.
 ArrayOf(Dictionary) nvim_get_keymap(String mode)
-    FUNC_API_SINCE(3)
+  FUNC_API_SINCE(3)
 {
   return keymap_array(mode, NULL);
 }
 
+/// Gets a map of global (non-buffer-local) Ex commands.
+///
+/// Currently only |user-commands| are supported, not builtin Ex commands.
+///
+/// @param  opts  Optional parameters. Currently only supports
+///               {"builtin":false}
+/// @param[out]  err   Error details, if any.
+///
+/// @returns Map of maps describing commands.
+Dictionary nvim_get_commands(Dictionary opts, Error *err)
+  FUNC_API_SINCE(4)
+{
+  return nvim_buf_get_commands(-1, opts, err);
+}
+
 /// Returns a 2-tuple (Array), where item 0 is the current channel id and item
 /// 1 is the |api-metadata| map (Dictionary).
 ///

src/nvim/ex_docmd.c

@@ -73,6 +73,7 @@
 #include "nvim/shada.h"
 #include "nvim/lua/executor.h"
 #include "nvim/globals.h"
+#include "nvim/api/private/helpers.h"
 
 static int quitmore = 0;
 static int ex_pressedreturn = FALSE;
@@ -4862,51 +4863,56 @@ static struct {
  * List of names for completion for ":command" with the EXPAND_ flag.
  * Must be alphabetical for completion.
  */
-static struct {
+static const char *command_complete[] =
-  int expand;
-  char    *name;
-} command_complete[] =
 {
-  { EXPAND_AUGROUP, "augroup" },
+  [EXPAND_AUGROUP] = "augroup",
-  { EXPAND_BEHAVE, "behave" },
+  [EXPAND_BEHAVE] = "behave",
-  { EXPAND_BUFFERS, "buffer" },
+  [EXPAND_BUFFERS] = "buffer",
-  { EXPAND_CHECKHEALTH, "checkhealth" },
+  [EXPAND_CHECKHEALTH] = "checkhealth",
-  { EXPAND_COLORS, "color" },
+  [EXPAND_COLORS] = "color",
-  { EXPAND_COMMANDS, "command" },
+  [EXPAND_COMMANDS] = "command",
-  { EXPAND_COMPILER, "compiler" },
+  [EXPAND_COMPILER] = "compiler",
-  { EXPAND_CSCOPE, "cscope" },
+  [EXPAND_CSCOPE] = "cscope",
-  { EXPAND_USER_DEFINED, "custom" },
+  [EXPAND_USER_DEFINED] = "custom",
-  { EXPAND_USER_LIST, "customlist" },
+  [EXPAND_USER_LIST] = "customlist",
-  { EXPAND_DIRECTORIES, "dir" },
+  [EXPAND_DIRECTORIES] = "dir",
-  { EXPAND_ENV_VARS, "environment" },
+  [EXPAND_ENV_VARS] = "environment",
-  { EXPAND_EVENTS, "event" },
+  [EXPAND_EVENTS] = "event",
-  { EXPAND_EXPRESSION, "expression" },
+  [EXPAND_EXPRESSION] = "expression",
-  { EXPAND_FILES, "file" },
+  [EXPAND_FILES] = "file",
-  { EXPAND_FILES_IN_PATH, "file_in_path" },
+  [EXPAND_FILES_IN_PATH] = "file_in_path",
-  { EXPAND_FILETYPE, "filetype" },
+  [EXPAND_FILETYPE] = "filetype",
-  { EXPAND_FUNCTIONS, "function" },
+  [EXPAND_FUNCTIONS] = "function",
-  { EXPAND_HELP, "help" },
+  [EXPAND_HELP] = "help",
-  { EXPAND_HIGHLIGHT, "highlight" },
+  [EXPAND_HIGHLIGHT] = "highlight",
-  { EXPAND_HISTORY, "history" },
+  [EXPAND_HISTORY] = "history",
 #ifdef HAVE_WORKING_LIBINTL
-  { EXPAND_LOCALES, "locale" },
+  [EXPAND_LOCALES] = "locale",
 #endif
-  { EXPAND_MAPPINGS, "mapping" },
+  [EXPAND_MAPPINGS] = "mapping",
-  { EXPAND_MENUS, "menu" },
+  [EXPAND_MENUS] = "menu",
-  { EXPAND_MESSAGES, "messages" },
+  [EXPAND_MESSAGES] = "messages",
-  { EXPAND_OWNSYNTAX, "syntax" },
+  [EXPAND_OWNSYNTAX] = "syntax",
-  { EXPAND_SYNTIME, "syntime" },
+  [EXPAND_SYNTIME] = "syntime",
-  { EXPAND_SETTINGS, "option" },
+  [EXPAND_SETTINGS] = "option",
-  { EXPAND_PACKADD, "packadd" },
+  [EXPAND_PACKADD] = "packadd",
-  { EXPAND_SHELLCMD, "shellcmd" },
+  [EXPAND_SHELLCMD] = "shellcmd",
-  { EXPAND_SIGN, "sign" },
+  [EXPAND_SIGN] = "sign",
-  { EXPAND_TAGS, "tag" },
+  [EXPAND_TAGS] = "tag",
-  { EXPAND_TAGS_LISTFILES, "tag_listfiles" },
+  [EXPAND_TAGS_LISTFILES] = "tag_listfiles",
-  { EXPAND_USER, "user" },
+  [EXPAND_USER] = "user",
-  { EXPAND_USER_VARS, "var" },
+  [EXPAND_USER_VARS] = "var",
-  { 0, NULL }
 };
 
+static char *get_command_complete(int arg)
+{
+  if (arg >= (int)(ARRAY_SIZE(command_complete))) {
+    return NULL;
+  } else {
+    return (char *)command_complete[arg];
+  }
+}
+
 static void uc_list(char_u *name, size_t name_len)
 {
   int i, j;
@@ -5000,13 +5006,12 @@ static void uc_list(char_u *name, size_t name_len)
         IObuff[len++] = ' ';
       } while (len < 21);
 
-      /* Completion */
+      // Completion
-      for (j = 0; command_complete[j].expand != 0; ++j)
+      char *cmd_compl = get_command_complete(cmd->uc_compl);
-        if (command_complete[j].expand == cmd->uc_compl) {
+      if (cmd_compl != NULL) {
-          STRCPY(IObuff + len, command_complete[j].name);
+        STRCPY(IObuff + len, get_command_complete(cmd->uc_compl));
-          len += (int)STRLEN(IObuff + len);
+        len += (int)STRLEN(IObuff + len);
-          break;
+      }
-        }
 
       do {
         IObuff[len++] = ' ';
@@ -5797,7 +5802,15 @@ char_u *get_user_cmd_nargs(expand_T *xp, int idx)
  */
 char_u *get_user_cmd_complete(expand_T *xp, int idx)
 {
-  return (char_u *)command_complete[idx].name;
+  if (idx >= (int)ARRAY_SIZE(command_complete)) {
+    return NULL;
+  }
+  char *cmd_compl = get_command_complete(idx);
+  if (cmd_compl == NULL) {
+    return (char_u *)"";
+  } else {
+    return (char_u *)cmd_compl;
+  }
 }
 
 /*
@@ -5857,20 +5870,23 @@ int parse_compl_arg(const char_u *value, int vallen, int *complp,
     }
   }
 
-  for (i = 0; command_complete[i].expand != 0; ++i) {
+  for (i = 0; i < (int)ARRAY_SIZE(command_complete); i++) {
-    if ((int)STRLEN(command_complete[i].name) == valend
+    if (get_command_complete(i) == NULL) {
-        && STRNCMP(value, command_complete[i].name, valend) == 0) {
+      continue;
-      *complp = command_complete[i].expand;
+    }
-      if (command_complete[i].expand == EXPAND_BUFFERS)
+    if ((int)STRLEN(command_complete[i]) == valend
+        && STRNCMP(value, command_complete[i], valend) == 0) {
+      *complp = i;
+      if (i == EXPAND_BUFFERS) {
         *argt |= BUFNAME;
-      else if (command_complete[i].expand == EXPAND_DIRECTORIES
+      } else if (i == EXPAND_DIRECTORIES || i == EXPAND_FILES) {
-               || command_complete[i].expand == EXPAND_FILES)
         *argt |= XFILE;
+      }
       break;
     }
   }
 
-  if (command_complete[i].expand == 0) {
+  if (i == (int)ARRAY_SIZE(command_complete)) {
     EMSG2(_("E180: Invalid complete value: %s"), value);
     return FAIL;
   }
@@ -5894,9 +5910,13 @@ int parse_compl_arg(const char_u *value, int vallen, int *complp,
 
 int cmdcomplete_str_to_type(char_u *complete_str)
 {
-    for (int i = 0; command_complete[i].expand != 0; i++) {
+    for (int i = 0; i < (int)(ARRAY_SIZE(command_complete)); i++) {
-      if (STRCMP(complete_str, command_complete[i].name) == 0) {
+      char *cmd_compl = get_command_complete(i);
-        return command_complete[i].expand;
+      if (cmd_compl == NULL) {
+        continue;
+      }
+      if (STRCMP(complete_str, command_complete[i]) == 0) {
+        return i;
       }
     }
 
@@ -9948,3 +9968,82 @@ bool cmd_can_preview(char_u *cmd)
 
   return false;
 }
+
+/// Gets a map 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.
+///
+/// @return Map of maps describing commands
+Dictionary commands_array(buf_T *buf)
+{
+  Dictionary rv = ARRAY_DICT_INIT;
+  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;
+    ucmd_T *cmd = USER_CMD_GA(gap, i);
+
+    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));
+    PUT(d, "bang", BOOLEAN_OBJ(!!(cmd->uc_argt & BANG)));
+    PUT(d, "bar", BOOLEAN_OBJ(!!(cmd->uc_argt & TRLBAR)));
+    PUT(d, "register", BOOLEAN_OBJ(!!(cmd->uc_argt & REGSTR)));
+
+    switch (cmd->uc_argt & (EXTRA|NOSPC|NEEDARG)) {
+      case 0:                    arg[0] = '0'; break;
+      case(EXTRA):               arg[0] = '*'; break;
+      case(EXTRA|NOSPC):         arg[0] = '?'; break;
+      case(EXTRA|NEEDARG):       arg[0] = '+'; break;
+      case(EXTRA|NOSPC|NEEDARG): arg[0] = '1'; break;
+    }
+    PUT(d, "nargs", STRING_OBJ(cstr_to_string(arg)));
+
+    char *cmd_compl = get_command_complete(cmd->uc_compl);
+    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);
+
+    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) {
+        snprintf(str, sizeof(str), "%" PRId64, (int64_t)cmd->uc_def);
+        obj = STRING_OBJ(cstr_to_string(str));    // -range=N
+      } else {
+        obj = STRING_OBJ(cstr_to_string("."));    // -range
+      }
+    }
+    PUT(d, "range", obj);
+
+    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) {
+        obj = STRING_OBJ(cstr_to_string(addr_type_complete[j].name));
+        break;
+      }
+    }
+    PUT(d, "addr", obj);
+
+    PUT(rv, (char *)cmd->uc_name, DICTIONARY_OBJ(d));
+  }
+  return rv;
+}

test/functional/api/command_spec.lua

@@ -0,0 +1,80 @@
+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 cmd_dict  = { addr=NIL, bang=false, bar=false, complete=NIL, complete_arg=NIL, count=NIL, definition='echo "Hello World"', name='Hello', nargs='1', range=NIL, register=false, script_id=0, }
+  local cmd_dict2 = { addr=NIL, bang=false, bar=false, complete=NIL, complete_arg=NIL, count=NIL, definition='pwd',                name='Pwd',   nargs='?', range=NIL, register=false, script_id=0, }
+  before_each(clear)
+
+  it('gets empty list if no commands were defined', function()
+    eq({}, meths.get_commands({builtin=false}))
+  end)
+
+  it('validates input', function()
+    expect_err('builtin=true not implemented', 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({Hello=cmd_dict}, meths.get_commands({builtin=false}))
+    -- Define another command.
+    command('command -nargs=? Pwd pwd');
+    eq({Hello=cmd_dict, Pwd=cmd_dict2}, meths.get_commands({builtin=false}))
+    -- Delete a command.
+    command('delcommand Pwd')
+    eq({Hello=cmd_dict}, meths.get_commands({builtin=false}))
+  end)
+
+  it('gets buffer-local user-defined commands', function()
+    -- Define a buffer-local command.
+    command('command -buffer -nargs=1 Hello echo "Hello World"')
+    eq({Hello=cmd_dict}, curbufmeths.get_commands({builtin=false}))
+    -- Define another buffer-local command.
+    command('command -buffer -nargs=? Pwd pwd')
+    eq({Hello=cmd_dict, Pwd=cmd_dict2}, curbufmeths.get_commands({builtin=false}))
+    -- Delete a command.
+    command('delcommand Pwd')
+    eq({Hello=cmd_dict}, curbufmeths.get_commands({builtin=false}))
+
+    -- {builtin=true} always returns empty for buffer-local case.
+    eq({}, curbufmeths.get_commands({builtin=true}))
+  end)
+
+  it('gets various command attributes', function()
+    local cmd0 = { addr='arguments', bang=false, bar=false, complete='dir',    complete_arg=NIL,         count='10', definition='pwd <args>',                    name='TestCmd', nargs='0', range='10', register=false, script_id=0, }
+    local cmd1 = { addr=NIL,         bang=false, bar=false, complete='custom', complete_arg='ListUsers', count=NIL,  definition='!finger <args>',                name='Finger',  nargs='+', range=NIL,  register=false, script_id=1, }
+    local cmd2 = { addr=NIL,         bang=true,  bar=false, complete=NIL,      complete_arg=NIL,         count=NIL,  definition='call \128\253Q2_foo(<q-args>)', name='Cmd2',    nargs='*', range=NIL,  register=false, script_id=2, }
+    local cmd3 = { addr=NIL,         bang=false, bar=true,  complete=NIL,      complete_arg=NIL,         count=NIL,  definition='call \128\253Q3_ohyeah()',      name='Cmd3',    nargs='0', range=NIL,  register=false, script_id=3, }
+    local cmd4 = { addr=NIL,         bang=false, bar=false, complete=NIL,      complete_arg=NIL,         count=NIL,  definition='call \128\253Q4_just_great()',  name='Cmd4',    nargs='0', range=NIL,  register=true,  script_id=4, }
+    source([[
+      command -complete=custom,ListUsers -nargs=+ Finger !finger <args>
+    ]])
+    eq({Finger=cmd1}, meths.get_commands({builtin=false}))
+    command('command -complete=dir -addr=arguments -count=10 TestCmd pwd <args>')
+    eq({Finger=cmd1, TestCmd=cmd0}, meths.get_commands({builtin=false}))
+
+    source([[
+      command -bang -nargs=* Cmd2 call <SID>foo(<q-args>)
+    ]])
+    source([[
+      command -bar -nargs=0 Cmd3 call <SID>ohyeah()
+    ]])
+    source([[
+      command -register Cmd4 call <SID>just_great()
+    ]])
+    -- TODO(justinmk): Order is stable but undefined. Sort before return?
+    eq({Cmd2=cmd2, Cmd3=cmd3, Cmd4=cmd4, Finger=cmd1, TestCmd=cmd0}, meths.get_commands({builtin=false}))
+  end)
+end)

test/functional/api/keymap_spec.lua

@@ -11,7 +11,7 @@ local source = helpers.source
 
 local shallowcopy = global_helpers.shallowcopy
 
-describe('get_keymap', function()
+describe('nvim_get_keymap', function()
   before_each(clear)
 
   -- Basic mapping and table to be used to describe results