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().

6 files changed, 24 insertions, 19 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 197edf2e81..ea57db22e0 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1549,11 +1549,11 @@ nvim_command({command})                                       *nvim_command()*
 
     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 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()|.
+    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()|.
 
     Parameters: ~
       • {command}  Ex command string
@@ -1570,7 +1570,7 @@ nvim_eval({expr})                                                *nvim_eval()*
     Return: ~
         Evaluation result or expanded object
 
-nvim_exec({src}, {output})                                       *nvim_exec()*
+nvim_exec2({src}, {*opts})                                      *nvim_exec2()*
     Executes Vimscript (multiline block of Ex commands), like anonymous
     |:source|.
 
@@ -1580,12 +1580,14 @@ nvim_exec({src}, {output})                                       *nvim_exec()*
     On execution error: fails with VimL error, updates v:errmsg.
 
     Parameters: ~
-      • {src}     Vimscript code
-      • {output}  Capture and return all (non-error, non-shell |:!|) output
+      • {src}   Vimscript code
+      • {opts}  Optional parameters.
+                • output: (boolean, default false) Whether to capture and
+                  return all (non-error, non-shell |:!|) output.
 
     Return: ~
-        Output (non-error, non-shell |:!|) if `output` is true, else empty
-        string.
+        Dictionary containing information about execution, with these keys:
+        • output: (string|nil) Output if `opts.output` is true.
 
     See also: ~
       • |execute()|
@@ -1738,7 +1740,7 @@ nvim_cmd({*cmd}, {*opts})                                         *nvim_cmd()*
         empty string.
 
     See also: ~
-      • |nvim_exec()|
+      • |nvim_exec2()|
       • |nvim_command()|
 
                                                   *nvim_create_user_command()*
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 84cc415a37..69cec8da53 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -15,10 +15,11 @@ Deprecated features
 API
 - *nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
 - *nvim_buf_set_virtual_text()*	Use |nvim_buf_set_extmark()| instead.
-- *nvim_command_output()*	Use |nvim_exec()| instead.
+- *nvim_command_output()*	Use |nvim_exec2()| instead.
 - *nvim_execute_lua()*		Use |nvim_exec_lua()| instead.
 - *nvim_get_hl_by_name()*	Use |nvim_get_hl()| instead.
 - *nvim_get_hl_by_id()*		Use |nvim_get_hl()| instead.
+- *nvim_exec()*			Use |nvim_exec2()| instead.
 
 COMMANDS
 - *:rv* *:rviminfo*		Deprecated alias to |:rshada| command.
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 018c6ce5a4..0bea2819c9 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1355,9 +1355,9 @@ cmd({command})                                                     *vim.cmd()*
     Parameters: ~
       • {command}  string|table Command(s) to execute. If a string, executes
                    multiple lines of Vim script at once. In this case, it is
-                   an alias to |nvim_exec()|, where `output` is set to false.
-                   Thus it works identical to |:source|. If a table, executes
-                   a single command. In this case, it is an alias to
+                   an alias to |nvim_exec2()|, where `opts.output` is set to
+                   false. Thus it works identical to |:source|. If a table,
+                   executes a single command. In this case, it is an alias to
                    |nvim_cmd()| where `opts` is empty.
 
     See also: ~
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index f3950de683..20af29430a 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -60,6 +60,8 @@ The following changes may require adaptations in user config or plugins.
 
 • Renamed vim.pretty_print to vim.print. |deprecated|
 
+• |nvim_exec()| is now deprecated in favor of |nvim_exec2()|.
+
 ==============================================================================
 NEW FEATURES                                                    *news-features*
 
diff --git a/runtime/lua/_vim9script.lua b/runtime/lua/_vim9script.lua
index 363d061451..76e427b748 100644
--- a/runtime/lua/_vim9script.lua
+++ b/runtime/lua/_vim9script.lua
@@ -162,7 +162,7 @@ local vim9 = (function()
           end
         end
 
-        vim.api.nvim_exec(table.concat(file, '\n'), false)
+        vim.api.nvim_exec2(table.concat(file, '\n'), { output = false })
       end,
     })
   end
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index fd6a5865ce..db7a6c1d17 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -322,8 +322,8 @@ end
 ---
 ---@param command string|table Command(s) to execute.
 ---                            If a string, executes multiple lines of Vim script at once. In this
----                            case, it is an alias to |nvim_exec()|, where `output` is set to
----                            false. Thus it works identical to |:source|.
+---                            case, it is an alias to |nvim_exec2()|, where `opts.output` is set
+---                            to false. Thus it works identical to |:source|.
 ---                            If a table, executes a single command. In this case, it is an alias
 ---                            to |nvim_cmd()| where `opts` is empty.
 ---@see |ex-cmd-index|
@@ -338,7 +338,7 @@ vim.cmd = setmetatable({}, {
     if type(command) == 'table' then
       return vim.api.nvim_cmd(command, {})
     else
-      return vim.api.nvim_exec(command, false)
+      return vim.api.nvim_exec2(command, { output = false }).output
     end
   end,
   __index = function(t, command)