fix(api)!: nvim_parse_cmd omit "count" "range" "reg" if not supported

runtime/doc/api.txt

@@ -1805,15 +1805,15 @@ nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
     Return: ~
         Dictionary containing command information, with these keys:
         • cmd: (string) Command name.
-        • range: (array) Command <range>. Can have 0-2 elements depending on
+        • range: (array) (optional) Command range (|<line1>| |<line2>|).
-          how many items the range contains. Has no elements if command
+          Omitted if command doesn't accept a range. Otherwise, has no
-          doesn't accept a range or if no range was specified, one element if
+          elements if no range was specified, one element if only a single
-          only a single range item was specified and two elements if both
+          range item was specified, or two elements if both range items were
-          range items were specified.
+          specified.
-        • count: (number) Any |<count>| that was supplied to the command. -1
+        • count: (number) (optional) Command |<count>|. Omitted if command
-          if command cannot take a count.
+          cannot take a count.
-        • reg: (string) The optional command |<register>|, if specified. Empty
+        • reg: (string) (optional) Command |<register>|. Omitted if command
-          string if not specified or if command cannot take a register.
+          cannot take a register.
         • bang: (boolean) Whether command contains a |<bang>| (!) modifier.
         • args: (array) Command arguments.
         • addr: (string) Value of |:command-addr|. Uses short name.

src/nvim/api/command.c

@@ -31,14 +31,15 @@
 /// @param[out] err  Error details, if any.
 /// @return Dictionary containing command information, with these keys:
 ///         - cmd: (string) Command name.
-///         - range: (array) Command <range>. Can have 0-2 elements depending on how many items the
+///         - range: (array) (optional) Command range (|<line1>| |<line2>|).
-///                          range contains. Has no elements if command doesn't accept a range or if
+///                          Omitted if command doesn't accept a range.
-///                          no range was specified, one element if only a single range item was
+///                          Otherwise, has no elements if no range was specified, one element if
-///                          specified and two elements if both range items were specified.
+///                          only a single range item was specified, or two elements if both range
-///         - count: (number) Any |<count>| that was supplied to the command. -1 if command cannot
+///                          items were specified.
-///                           take a count.
+///         - count: (number) (optional) Command |<count>|.
-///         - reg: (string) The optional command |<register>|, if specified. Empty string if not
+///                           Omitted if command cannot take a count.
-///                         specified or if command cannot take a register.
+///         - reg: (string) (optional) Command |<register>|.
+///                         Omitted if command cannot take a register.
 ///         - bang: (boolean) Whether command contains a |<bang>| (!) modifier.
 ///         - args: (array) Command arguments.
 ///         - addr: (string) Value of |:command-addr|. Uses short name.
@@ -142,15 +143,15 @@ Dictionary nvim_parse_cmd(String str, Dictionary opts, Error *err)
     PUT(result, "cmd", CSTR_TO_OBJ((char *)get_command_name(NULL, ea.cmdidx)));
   }
 
-  if ((ea.argt & EX_RANGE) && ea.addr_count > 0) {
+  if (ea.argt & EX_RANGE) {
     Array range = ARRAY_DICT_INIT;
+    if (ea.addr_count > 0) {
       if (ea.addr_count > 1) {
         ADD(range, INTEGER_OBJ(ea.line1));
       }
       ADD(range, INTEGER_OBJ(ea.line2));
+    }
     PUT(result, "range", ARRAY_OBJ(range));
-  } else {
-    PUT(result, "range", ARRAY_OBJ(ARRAY_DICT_INIT));
   }
 
   if (ea.argt & EX_COUNT) {
@@ -161,12 +162,12 @@ Dictionary nvim_parse_cmd(String str, Dictionary opts, Error *err)
     } else {
       PUT(result, "count", INTEGER_OBJ(0));
     }
-  } else {
-    PUT(result, "count", INTEGER_OBJ(-1));
   }
 
+  if (ea.argt & EX_REGSTR) {
     char reg[2] = { (char)ea.regname, NUL };
     PUT(result, "reg", CSTR_TO_OBJ(reg));
+  }
 
   PUT(result, "bang", BOOLEAN_OBJ(ea.forceit));
   PUT(result, "args", ARRAY_OBJ(args));

test/functional/api/vim_spec.lua

@@ -3177,9 +3177,6 @@ describe('API', function()
         cmd = 'echo',
         args = { 'foo' },
         bang = false,
-        range = {},
-        count = -1,
-        reg = '',
         addr = 'none',
         magic = {
             file = false,
@@ -3220,8 +3217,6 @@ describe('API', function()
         args = { '/math.random/math.max/' },
         bang = false,
         range = { 4, 6 },
-        count = -1,
-        reg = '',
         addr = 'line',
         magic = {
             file = false,
@@ -3263,7 +3258,6 @@ describe('API', function()
         bang = false,
         range = { 1 },
         count = 1,
-        reg = '',
         addr = 'buf',
         magic = {
             file = false,
@@ -3304,7 +3298,6 @@ describe('API', function()
         args = {},
         bang = false,
         range = {},
-        count = -1,
         reg = '+',
         addr = 'line',
         magic = {
@@ -3339,6 +3332,45 @@ describe('API', function()
           vertical = false,
         }
       }, meths.parse_cmd('put +', {}))
+      eq({
+        cmd = 'put',
+        args = {},
+        bang = false,
+        range = {},
+        reg = '',
+        addr = 'line',
+        magic = {
+            file = false,
+            bar = true
+        },
+        nargs = '0',
+        nextcmd = '',
+        mods = {
+          browse = false,
+          confirm = false,
+          emsg_silent = false,
+          filter = {
+              pattern = "",
+              force = false
+          },
+          hide = false,
+          horizontal = false,
+          keepalt = false,
+          keepjumps = false,
+          keepmarks = false,
+          keeppatterns = false,
+          lockmarks = false,
+          noautocmd = false,
+          noswapfile = false,
+          sandbox = false,
+          silent = false,
+          split = "",
+          tab = -1,
+          unsilent = false,
+          verbose = -1,
+          vertical = false,
+        }
+      }, meths.parse_cmd('put', {}))
     end)
     it('works with range, count and register', function()
       eq({
@@ -3388,8 +3420,6 @@ describe('API', function()
         args = {},
         bang = true,
         range = {},
-        count = -1,
-        reg = '',
         addr = 'line',
         magic = {
             file = true,
@@ -3430,8 +3460,6 @@ describe('API', function()
         args = { 'foo.txt' },
         bang = false,
         range = {},
-        count = -1,
-        reg = '',
         addr = '?',
         magic = {
             file = true,
@@ -3470,8 +3498,6 @@ describe('API', function()
         args = { 'foo.txt' },
         bang = false,
         range = {},
-        count = -1,
-        reg = '',
         addr = '?',
         magic = {
             file = true,
@@ -3513,8 +3539,6 @@ describe('API', function()
         args = { 'test', 'it' },
         bang = true,
         range = { 4, 6 },
-        count = -1,
-        reg = '',
         addr = 'line',
         magic = {
             file = false,
@@ -3555,8 +3579,6 @@ describe('API', function()
         args = { 'a.txt' },
         bang = false,
         range = {},
-        count = -1,
-        reg = '',
         addr = 'arg',
         magic = {
             file = true,
@@ -3597,9 +3619,6 @@ describe('API', function()
         cmd = 'MyCommand',
         args = { 'test it' },
         bang = false,
-        range = {},
-        count = -1,
-        reg = '',
         addr = 'none',
         magic = {
             file = false,
@@ -3691,8 +3710,6 @@ describe('API', function()
         args = {'x'},
         bang = true,
         range = {3, 4},
-        count = -1,
-        reg = '',
         addr = 'line',
         magic = {
           file = false,
@@ -3730,6 +3747,11 @@ describe('API', function()
       eq('', funcs.getreg('/'))
       eq('', funcs.histget('search'))
     end)
+    it('result can be used directly by nvim_cmd #20051', function()
+      eq("foo", meths.cmd(meths.parse_cmd('echo "foo"', {}), { output = true }))
+      meths.cmd(meths.parse_cmd("set cursorline", {}), {})
+      eq(true, meths.get_option_value("cursorline", {}))
+    end)
   end)
   describe('nvim_cmd', function()
     it('works', function ()