feat(api): nvim_exec2(), deprecate nvim_exec() #19032

Problem:
The signature of nvim_exec() is not extensible per ":help api-contract".

Solution:
Introduce nvim_exec2() and deprecate nvim_exec().

4 files changed, 47 insertions, 11 deletions

diff --git a/src/nvim/api/command.c b/src/nvim/api/command.c
index 1455f28050..26ee9205b2 100644
--- a/src/nvim/api/command.c
+++ b/src/nvim/api/command.c
@@ -307,7 +307,7 @@ end:
 ///
 /// On execution error: fails with VimL error, updates v:errmsg.
 ///
-/// @see |nvim_exec()|
+/// @see |nvim_exec2()|
 /// @see |nvim_command()|
 ///
 /// @param cmd       Command to execute. Must be a Dictionary that can contain the same values as
diff --git a/src/nvim/api/deprecated.c b/src/nvim/api/deprecated.c
index b1e2e6811e..6a12cfe2da 100644
--- a/src/nvim/api/deprecated.c
+++ b/src/nvim/api/deprecated.c
@@ -27,13 +27,26 @@
 # include "api/deprecated.c.generated.h"
 #endif
 
+/// @deprecated Use nvim_exec2() instead.
+/// @see nvim_exec2
+String nvim_exec(uint64_t channel_id, String src, Boolean output, Error *err)
+  FUNC_API_SINCE(7)
+  FUNC_API_DEPRECATED_SINCE(11)
+{
+  Dict(exec_opts) opts = { 0 };
+  opts.output = BOOLEAN_OBJ(output);
+  return exec_impl(channel_id, src, &opts, err);
+}
+
 /// @deprecated
-/// @see nvim_exec
+/// @see nvim_exec2
 String nvim_command_output(uint64_t channel_id, String command, Error *err)
   FUNC_API_SINCE(1)
   FUNC_API_DEPRECATED_SINCE(7)
 {
-  return nvim_exec(channel_id, command, true, err);
+  Dict(exec_opts) opts = { 0 };
+  opts.output = BOOLEAN_OBJ(true);
+  return exec_impl(channel_id, command, &opts, err);
 }
 
 /// @deprecated Use nvim_exec_lua() instead.
diff --git a/src/nvim/api/keysets.lua b/src/nvim/api/keysets.lua
index b2b327d73e..ce29001787 100644
--- a/src/nvim/api/keysets.lua
+++ b/src/nvim/api/keysets.lua
@@ -232,4 +232,7 @@ return {
   { 'echo_opts', {
     "verbose";
   }};
+  { 'exec_opts', {
+    "output";
+  }};
 }
diff --git a/src/nvim/api/vimscript.c b/src/nvim/api/vimscript.c
index 32dcbdec3f..2438a5cf1d 100644
--- a/src/nvim/api/vimscript.c
+++ b/src/nvim/api/vimscript.c
@@ -45,13 +45,33 @@
 /// @see |nvim_cmd()|
 ///
 /// @param src      Vimscript code
-/// @param output   Capture and return all (non-error, non-shell |:!|) output
+/// @param opts  Optional parameters.
+///           - output: (boolean, default false) Whether to capture and return
+///                     all (non-error, non-shell |:!|) output.
 /// @param[out] err Error details (Vim error), if any
-/// @return Output (non-error, non-shell |:!|) if `output` is true,
-///         else empty string.
-String nvim_exec(uint64_t channel_id, String src, Boolean output, Error *err)
-  FUNC_API_SINCE(7)
+/// @return Dictionary containing information about execution, with these keys:
+///       - output: (string|nil) Output if `opts.output` is true.
+Dictionary nvim_exec2(uint64_t channel_id, String src, Dict(exec_opts) *opts, Error *err)
+  FUNC_API_SINCE(11)
 {
+  Dictionary result = ARRAY_DICT_INIT;
+
+  String output = exec_impl(channel_id, src, opts, err);
+  if (ERROR_SET(err)) {
+    return result;
+  }
+
+  if (HAS_KEY(opts->output) && api_object_to_bool(opts->output, "opts.output", false, err)) {
+    PUT(result, "output", STRING_OBJ(output));
+  }
+
+  return result;
+}
+
+String exec_impl(uint64_t channel_id, String src, Dict(exec_opts) *opts, Error *err)
+{
+  Boolean output = api_object_to_bool(opts->output, "opts.output", false, err);
+
   const int save_msg_silent = msg_silent;
   garray_T *const save_capture_ga = capture_ga;
   const int save_msg_col = msg_col;
@@ -69,7 +89,7 @@ String nvim_exec(uint64_t channel_id, String src, Boolean output, Error *err)
 
   const sctx_T save_current_sctx = api_set_sctx(channel_id);
 
-  do_source_str(src.data, "nvim_exec()");
+  do_source_str(src.data, "nvim_exec2()");
   if (output) {
     capture_ga = save_capture_ga;
     msg_silent = save_msg_silent;
@@ -108,8 +128,8 @@ theend:
 ///
 /// On execution error: fails with VimL error, updates v:errmsg.
 ///
-/// Prefer using |nvim_cmd()| or |nvim_exec()| over this. To evaluate multiple lines of Vim script
-/// or an Ex command directly, use |nvim_exec()|. To construct an Ex command using a structured
+/// Prefer using |nvim_cmd()| or |nvim_exec2()| over this. To evaluate multiple lines of Vim script
+/// or an Ex command directly, use |nvim_exec2()|. To construct an Ex command using a structured
 /// format and then execute it, use |nvim_cmd()|. To modify an Ex command before evaluating it, use
 /// |nvim_parse_cmd()| in conjunction with |nvim_cmd()|.
 ///