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

3 files changed, 86 insertions, 8 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index aeb1699908..0e58d1b1fe 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1291,6 +1291,9 @@ Lua module: vim                                                      *lua-vim*
 cmd({command})                                                     *vim.cmd()*
                 Execute Vim script commands.
 
+                Note that `vim.cmd` can be indexed with a command name to
+                return a callable function to the command.
+
                 Example: >
 
                    vim.cmd('echo 42')
@@ -1300,7 +1303,23 @@ cmd({command})                                                     *vim.cmd()*
                        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')
 <
 
                 Parameters: ~
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
diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua
index e2347c3c11..57bb2f9765 100644
--- a/test/functional/lua/vim_spec.lua
+++ b/test/functional/lua/vim_spec.lua
@@ -2148,6 +2148,13 @@ describe('lua stdlib', function()
     ]]
     eq('2', funcs.luaeval "BUF")
     eq(2, funcs.luaeval "#vim.api.nvim_list_bufs()")
+
+    -- vim.cmd can be indexed with a command name
+    exec_lua [[
+      vim.cmd.let 'g:var = 2'
+    ]]
+
+    eq(2, funcs.luaeval "vim.g.var")
   end)
 
   it('vim.regex', function()