feat: add preview functionality to user commands

Adds a Lua-only `preview` flag to user commands which allows the command to be incrementally previewed like `:substitute` when 'inccommand' is set.

4 files changed, 13 insertions, 2 deletions

diff --git a/src/nvim/api/keysets.lua b/src/nvim/api/keysets.lua
index d4882abffe..881a83e606 100644
--- a/src/nvim/api/keysets.lua
+++ b/src/nvim/api/keysets.lua
@@ -53,6 +53,7 @@ return {
     "force";
     "keepscript";
     "nargs";
+    "preview";
     "range";
     "register";
   };
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index 3cccbc3cdf..6981ecc455 100644
--- a/src/nvim/api/private/helpers.c
+++ b/src/nvim/api/private/helpers.c
@@ -1438,6 +1438,7 @@ void create_user_command(String name, Object command, Dict(user_command) *opts,
   char *rep = NULL;
   LuaRef luaref = LUA_NOREF;
   LuaRef compl_luaref = LUA_NOREF;
+  LuaRef preview_luaref = LUA_NOREF;
 
   if (!uc_validate_name(name.data)) {
     api_set_error(err, kErrorTypeValidation, "Invalid command name");
@@ -1592,6 +1593,14 @@ void create_user_command(String name, Object command, Dict(user_command) *opts,
     goto err;
   }
 
+  if (opts->preview.type == kObjectTypeLuaRef) {
+    argt |= EX_PREVIEW;
+    preview_luaref = api_new_luaref(opts->preview.data.luaref);
+  } else if (HAS_KEY(opts->preview)) {
+    api_set_error(err, kErrorTypeValidation, "Invalid value for 'preview'");
+    goto err;
+  }
+
   switch (command.type) {
   case kObjectTypeLuaRef:
     luaref = api_new_luaref(command.data.luaref);
@@ -1611,7 +1620,7 @@ void create_user_command(String name, Object command, Dict(user_command) *opts,
   }
 
   if (uc_add_command(name.data, name.size, rep, argt, def, flags, compl, compl_arg, compl_luaref,
-                     addr_type_arg, luaref, force) != OK) {
+                     preview_luaref, addr_type_arg, luaref, force) != OK) {
     api_set_error(err, kErrorTypeException, "Failed to create user command");
     // Do not goto err, since uc_add_command now owns luaref, compl_luaref, and compl_arg
   }
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 5c3c16d6b0..8555d1bb71 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -2511,6 +2511,7 @@ Dictionary nvim_eval_statusline(String str, Dict(eval_statusline) *opts, Error *
 ///                 - desc: (string) Used for listing the command when a Lua function is used for
 ///                                  {command}.
 ///                 - force: (boolean, default true) Override any previous definition.
+///                 - preview: (function) Preview callback for 'inccommand' |:command-preview|
 /// @param[out] err Error details, if any.
 void nvim_create_user_command(String name, Object command, Dict(user_command) *opts, Error *err)
   FUNC_API_SINCE(9)
diff --git a/src/nvim/api/vimscript.c b/src/nvim/api/vimscript.c
index e71f1a11ec..99ab247c2a 100644
--- a/src/nvim/api/vimscript.c
+++ b/src/nvim/api/vimscript.c
@@ -1311,7 +1311,7 @@ String nvim_cmd(uint64_t channel_id, Dict(cmd) *cmd, Dict(cmd_opts) *opts, Error
     }
 
     WITH_SCRIPT_CONTEXT(channel_id, {
-      execute_cmd(&ea, &cmdinfo);
+      execute_cmd(&ea, &cmdinfo, false);
     });
 
     if (output) {