Merge #8375 'API: nvim_get_commands'

closes #7833
ref #8029

3 files changed, 73 insertions, 18 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 023f434f9d..fa4ad27e60 100644
--- a/src/nvim/api/buffer.c
+++ b/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.
-/// The "buffer" key in the returned dictionary reflects the buffer
-/// handle where the mapping is present.
+/// Gets a list of buffer-local |mapping| definitions.
 ///
 /// @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
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index b922036893..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.
@@ -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;
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index df4912a51e..7a951d4e67 100644
--- a/src/nvim/api/vim.c
+++ b/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.
-/// The "buffer" key in the returned dictionary is always zero.
+/// Gets a list of global (non-buffer-local) |mapping| definitions.
 ///
 /// @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).
 ///