feat(lua): allow vim.cmd to be indexed (#19238)

1 files changed, 59 insertions, 7 deletions

diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 442d7b07d8..094fb2f909 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -288,6 +288,9 @@ end
 
 --- Execute Vim script commands.
 ---
+--- Note that `vim.cmd` can be indexed with a command name to return a callable function to the
+--- command.
+---
 --- Example:
 --- <pre>
 ---   vim.cmd('echo 42')
@@ -297,7 +300,23 @@ end
 ---       autocmd FileType c setlocal cindent
 ---     augroup END
 ---   ]])
----   vim.cmd({ cmd = 'echo', args = { '"foo"' } })
+---
+---   -- Ex command :echo "foo"
+---   -- Note string literals need to be double quoted.
+---   vim.cmd('echo "foo"')
+---   vim.cmd { cmd = 'echo', args = { '"foo"' } }
+---   vim.cmd.echo({ args = { '"foo"' } })
+---   vim.cmd.echo('"foo"')
+---
+---   -- Ex command :write! myfile.txt
+---   vim.cmd('write! myfile.txt')
+---   vim.cmd { cmd = 'write', args = { "myfile.txt" }, bang = true }
+---   vim.cmd.write { args = { "myfile.txt" }, bang = true }
+---   vim.cmd.write {"myfile.txt", bang = true })
+---
+---   -- Ex command :colorscheme blue
+---   vim.cmd('colorscheme blue')
+---   vim.cmd.colorscheme('blue')
 --- </pre>
 ---
 ---@param command string|table Command(s) to execute.
@@ -307,14 +326,47 @@ end
 ---                            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|
-function vim.cmd(command)
-  if type(command) == 'table' then
-    return vim.api.nvim_cmd(command, {})
-  else
-    return vim.api.nvim_exec(command, false)
-  end
+function vim.cmd(command) -- luacheck: no unused
+  error(command) -- Stub for gen_vimdoc.py
 end
 
+local VIM_CMD_ARG_MAX = 20
+
+vim.cmd = setmetatable({}, {
+  __call = function(_, command)
+    if type(command) == 'table' then
+      return vim.api.nvim_cmd(command, {})
+    else
+      return vim.api.nvim_exec(command, false)
+    end
+  end,
+  __index = function(t, command)
+    t[command] = function(...)
+      local opts
+      if select('#', ...) == 1 and type(select(1, ...)) == 'table' then
+        opts = select(1, ...)
+
+        -- Move indexed positions in opts to opt.args
+        if opts[1] and not opts.args then
+          opts.args = {}
+          for i = 1, VIM_CMD_ARG_MAX do
+            if not opts[i] then
+              break
+            end
+            opts.args[i] = opts[i]
+            opts[i] = nil
+          end
+        end
+      else
+        opts = { args = { ... } }
+      end
+      opts.cmd = command
+      return vim.api.nvim_cmd(opts, {})
+    end
+    return t[command]
+  end,
+})
+
 -- These are the vim.env/v/g/o/bo/wo variable magic accessors.
 do
   local validate = vim.validate