feat(api): rename buffer to buf in retval #38900

In 3a4a66017b, 4d3a67cd62
we renamed "buffer" to "buf" in dict parameters.

This commit also renames such keys in dict return-values.

runtime/doc/api.txt

@@ -848,7 +848,8 @@ nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
         • "pty" (optional) Name of pseudoterminal. On a POSIX system this is a
           device path like "/dev/pts/1". If unknown, the key will still be
           present if a pty is used (e.g. for conpty on Windows).
-        • "buffer" (optional) Buffer connected to |terminal| instance.
+        • "buf" (optional) Buffer connected to |terminal| instance.
+        • "buffer" (optional) Deprecated alias for `buf`.
         • "client" (optional) Info about the peer (client on the other end of
           the channel), as set by |nvim_set_client_info()|.
         • "exitcode" (optional) Exit code of the |terminal| process.
@@ -1001,7 +1002,7 @@ nvim_get_keymap({mode})                                    *nvim_get_keymap()*
 
     Return: ~
         (`vim.api.keyset.get_keymap[]`) Array of |maparg()|-like dictionaries
-        describing mappings. The "buffer" key is always zero.
+        describing mappings. The "buf" key is always zero.
 
 nvim_get_mark({name}, {opts})                                *nvim_get_mark()*
     Returns a `(row, col, buffer, buffername)` tuple representing the position
@@ -2282,7 +2283,7 @@ nvim_get_autocmds({opts})                                *nvim_get_autocmds()*
     Return: ~
         (`vim.api.keyset.get_autocmds.ret[]`) Array of matching autocommands,
         where each item has:
-        • buffer (`integer?`): Buffer id (only for |autocmd-buffer-local|).
+        • buf (`integer?`): Buffer id (only for |autocmd-buffer-local|).
         • buflocal (`boolean?`): true if the autocommand is buffer-local
           |autocmd-buffer-local|.
         • callback: (`function|string?`): Event handler: a Lua function or
@@ -2530,7 +2531,7 @@ nvim_buf_get_keymap({buffer}, {mode})                  *nvim_buf_get_keymap()*
 
     Return: ~
         (`vim.api.keyset.get_keymap[]`) Array of |maparg()|-like dictionaries
-        describing mappings. The "buffer" key holds the associated buffer id.
+        describing mappings. The "buf" key holds the associated buffer id.
 
                                                         *nvim_buf_get_lines()*
 nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})

runtime/doc/deprecated.txt

@@ -17,8 +17,12 @@ DEPRECATED IN 0.13					*deprecated-0.13*
 
 API
 
-• "buffer" key in |nvim_create_autocmd()|, |nvim_get_autocmds()|,
+• The "buffer" key accepted and/or returned by these functions, was renamed to
-  |nvim_exec_autocmds()|, |nvim_clear_autocmds()|. Use "buf" instead.
+  "buf":
+  • |nvim_create_autocmd()|
+  • |nvim_get_autocmds()|
+  • |nvim_exec_autocmds()|
+  • |nvim_clear_autocmds()|
 
 ------------------------------------------------------------------------------
 DEPRECATED IN 0.12					*deprecated-0.12*

runtime/lua/vim/_meta/api.lua

@@ -459,7 +459,7 @@ function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end
 --- @param buffer integer Buffer id, or 0 for current buffer
 --- @param mode string Mode short-name ("n", "i", "v", ...)
 --- @return vim.api.keyset.get_keymap[] # Array of |maparg()|-like dictionaries describing mappings.
---- The "buffer" key holds the associated buffer id.
+--- The "buf" key holds the associated buffer id.
 function vim.api.nvim_buf_get_keymap(buffer, mode) end
 
 --- Gets a line-range from the buffer.
@@ -1295,7 +1295,7 @@ function vim.api.nvim_get_all_options_info() end
 --- - id: (`integer?`) Autocommand ID to match.
 --- - pattern: (`string|table?`) Pattern(s) to match `autocmd-pattern`. Not allowed with {buf}.
 --- @return vim.api.keyset.get_autocmds.ret[] # Array of matching autocommands, where each item has:
---- - buffer (`integer?`): Buffer id (only for |autocmd-buffer-local|).
+--- - buf (`integer?`): Buffer id (only for |autocmd-buffer-local|).
 --- - buflocal (`boolean?`): true if the autocommand is buffer-local |autocmd-buffer-local|.
 --- - callback: (`function|string?`): Event handler: a Lua function or Vimscript function name.
 --- - command: (`string`) Event handler: an Ex-command. Empty if a `callback` is set.
@@ -1328,7 +1328,8 @@ function vim.api.nvim_get_autocmds(opts) end
 --- - "pty"      (optional) Name of pseudoterminal. On a POSIX system this is a device path like
 ---              "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
 ---              for conpty on Windows).
---- - "buffer"   (optional) Buffer connected to |terminal| instance.
+--- - "buf"      (optional) Buffer connected to |terminal| instance.
+--- - "buffer"   (optional) Deprecated alias for `buf`.
 --- - "client"   (optional) Info about the peer (client on the other end of the channel), as set
 ---              by |nvim_set_client_info()|.
 --- - "exitcode" (optional) Exit code of the |terminal| process.
@@ -1449,7 +1450,7 @@ function vim.api.nvim_get_hl_ns(opts) end
 ---
 --- @param mode string Mode short-name ("n", "i", "v", ...)
 --- @return vim.api.keyset.get_keymap[] # Array of |maparg()|-like dictionaries describing mappings.
---- The "buffer" key is always zero.
+--- The "buf" key is always zero.
 function vim.api.nvim_get_keymap(mode) end
 
 --- Returns a `(row, col, buffer, buffername)` tuple representing the position

src/nvim/api/autocmd.c

@@ -73,7 +73,7 @@ static int64_t next_autocmd_id = 1;
 ///        - id: (`integer?`) Autocommand ID to match.
 ///        - pattern: (`string|table?`) Pattern(s) to match |autocmd-pattern|. Not allowed with {buf}.
 /// @return Array of matching autocommands, where each item has:
-///         - buffer (`integer?`): Buffer id (only for |autocmd-buffer-local|).
+///         - buf (`integer?`): Buffer id (only for |autocmd-buffer-local|).
 ///         - buflocal (`boolean?`): true if the autocommand is buffer-local |autocmd-buffer-local|.
 ///         - callback: (`function|string?`): Event handler: a Lua function or Vimscript function name.
 ///         - command: (`string`) Event handler: an Ex-command. Empty if a `callback` is set.
@@ -277,7 +277,7 @@ ArrayOf(DictAs(get_autocmds__ret)) nvim_get_autocmds(Dict(get_autocmds) *opts, A
         }
       }
 
-      Dict autocmd_info = arena_dict(arena, 11);
+      Dict autocmd_info = arena_dict(arena, 12);
 
       if (ap->group != AUGROUP_DEFAULT) {
         PUT_C(autocmd_info, "group", INTEGER_OBJ(ap->group));
@@ -319,6 +319,7 @@ ArrayOf(DictAs(get_autocmds__ret)) nvim_get_autocmds(Dict(get_autocmds) *opts, A
 
       if (ap->buflocal_nr) {
         PUT_C(autocmd_info, "buflocal", BOOLEAN_OBJ(true));
+        PUT_C(autocmd_info, "buf", INTEGER_OBJ(ap->buflocal_nr));
         PUT_C(autocmd_info, "buffer", INTEGER_OBJ(ap->buflocal_nr));
       } else {
         PUT_C(autocmd_info, "buflocal", BOOLEAN_OBJ(false));

src/nvim/api/buffer.c

@@ -855,7 +855,7 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
 /// @param  mode       Mode short-name ("n", "i", "v", ...)
 /// @param[out]  err   Error details, if any
 /// @returns Array of |maparg()|-like dictionaries describing mappings.
-///          The "buffer" key holds the associated buffer id.
+///          The "buf" key holds the associated buffer id.
 ArrayOf(DictAs(get_keymap)) nvim_buf_get_keymap(Buffer buffer, String mode, Arena *arena,
                                                 Error *err)
   FUNC_API_SINCE(3)

src/nvim/api/vim.c

@@ -1585,7 +1585,7 @@ DictAs(get_mode) nvim_get_mode(Arena *arena)
 ///
 /// @param  mode       Mode short-name ("n", "i", "v", ...)
 /// @returns Array of |maparg()|-like dictionaries describing mappings.
-///          The "buffer" key is always zero.
+///          The "buf" key is always zero.
 ArrayOf(DictAs(get_keymap)) nvim_get_keymap(String mode, Arena *arena)
   FUNC_API_SINCE(3)
 {
@@ -1781,7 +1781,8 @@ void nvim__chan_set_detach(uint64_t channel_id, Boolean detach, Error *err)
 ///    - "pty"      (optional) Name of pseudoterminal. On a POSIX system this is a device path like
 ///                 "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
 ///                 for conpty on Windows).
-///    - "buffer"   (optional) Buffer connected to |terminal| instance.
+///    - "buf"      (optional) Buffer connected to |terminal| instance.
+///    - "buffer"   (optional) Deprecated alias for `buf`.
 ///    - "client"   (optional) Info about the peer (client on the other end of the channel), as set
 ///                 by |nvim_set_client_info()|.
 ///    - "exitcode" (optional) Exit code of the |terminal| process.

src/nvim/channel.c

@@ -999,7 +999,7 @@ Dict channel_info(uint64_t id, Arena *arena)
     return (Dict)ARRAY_DICT_INIT;
   }
 
-  Dict info = arena_dict(arena, 8);
+  Dict info = arena_dict(arena, 9);
   PUT_C(info, "id", INTEGER_OBJ((Integer)chan->id));
 
   const char *stream_desc, *mode_desc;
@@ -1048,6 +1048,7 @@ Dict channel_info(uint64_t id, Arena *arena)
     PUT_C(info, "client", DICT_OBJ(chan->rpc.info));
   } else if (chan->term) {
     mode_desc = "terminal";
+    PUT_C(info, "buf", BUFFER_OBJ(terminal_buf(chan->term)));
     PUT_C(info, "buffer", BUFFER_OBJ(terminal_buf(chan->term)));
     PUT_C(info, "exitcode", INTEGER_OBJ(chan->exit_status));
   } else {

src/nvim/mapping.c

@@ -2086,7 +2086,7 @@ static Dict mapblock_fill_dict(const mapblock_T *const mp, const char *lhsrawalt
                                Arena *arena)
   FUNC_ATTR_NONNULL_ARG(1)
 {
-  Dict dict = arena_dict(arena, 19);
+  Dict dict = arena_dict(arena, 20);
   char *const lhs = str2special_arena(mp->m_keys, compatible, !compatible, arena);
   char *mapmode = arena_alloc(arena, 7, false);
   map_mode_to_chars(mp->m_mode, mapmode);
@@ -2127,6 +2127,9 @@ static Dict mapblock_fill_dict(const mapblock_T *const mp, const char *lhsrawalt
   PUT_C(dict, "scriptversion", INTEGER_OBJ(1));
   PUT_C(dict, "lnum", INTEGER_OBJ(mp->m_script_ctx.sc_lnum));
   PUT_C(dict, "buffer", INTEGER_OBJ(buffer_value));
+  if (!compatible) {
+    PUT_C(dict, "buf", INTEGER_OBJ(buffer_value));
+  }
   PUT_C(dict, "nowait", INTEGER_OBJ(mp->m_nowait ? 1 : 0));
   PUT_C(dict, "replace_keycodes", INTEGER_OBJ(mp->m_replace_keycodes ? 1 : 0));
   PUT_C(dict, "mode", CSTR_AS_OBJ(mapmode));

test/functional/api/autocmd_spec.lua

@@ -626,7 +626,8 @@ describe('autocmd api', function()
         local aus = api.nvim_get_autocmds { event = 'InsertEnter', buf = 0 }
         eq({
           {
-            buffer = 2,
+            buf = 2,
+            buffer = 2, -- deprecated
             buflocal = true,
             command = ':echo "2"',
             event = 'InsertEnter',
@@ -638,7 +639,8 @@ describe('autocmd api', function()
         aus = api.nvim_get_autocmds { event = 'InsertEnter', buf = 1 }
         eq({
           {
-            buffer = 1,
+            buf = 1,
+            buffer = 1, -- deprecated
             buflocal = true,
             command = ':echo "1"',
             event = 'InsertEnter',
@@ -650,7 +652,8 @@ describe('autocmd api', function()
         aus = api.nvim_get_autocmds { event = 'InsertEnter', buf = { 1, 2 } }
         eq({
           {
-            buffer = 1,
+            buf = 1,
+            buffer = 1, -- deprecated
             buflocal = true,
             command = ':echo "1"',
             event = 'InsertEnter',
@@ -658,7 +661,8 @@ describe('autocmd api', function()
             pattern = '<buffer=1>',
           },
           {
-            buffer = 2,
+            buf = 2,
+            buffer = 2, -- deprecated
             buflocal = true,
             command = ':echo "2"',
             event = 'InsertEnter',

test/functional/api/keymap_spec.lua

@@ -48,7 +48,8 @@ describe('nvim_get_keymap', function()
     replace_keycodes = 0,
     sid = 0,
     scriptversion = 1,
-    buffer = 0,
+    buf = 0,
+    buffer = 0, -- deprecated
     nowait = 0,
     mode = 'n',
     mode_bits = 0x01,
@@ -63,12 +64,12 @@ describe('nvim_get_keymap', function()
 
   it('returns list of all applicable mappings', function()
     command(foo_bar_string)
-    -- Only one mapping available
+    -- Only one mapping available. Should be the same as `foo_bar_map_table`, and maparg() result
-    -- Should be the same as the dictionary we supplied earlier
+    -- (plus "buf"), since this is a global map.
-    -- and the dictionary you would get from maparg
-    -- since this is a global map, and not script local
     eq({ foo_bar_map_table }, api.nvim_get_keymap('n'))
-    eq({ fn.maparg('foo', 'n', false, true) }, api.nvim_get_keymap('n'))
+    -- Add "buf" key to maparg() result.
+    local maparg_rv = vim.tbl_deep_extend('force', fn.maparg('foo', 'n', false, true), { buf = 0 })
+    eq({ maparg_rv }, api.nvim_get_keymap('n'))
 
     -- Add another mapping
     command('nnoremap foo_longer bar_longer')
@@ -107,7 +108,8 @@ describe('nvim_get_keymap', function()
     foolong_bar_map_table['rhs'] = 'bar_longer'
 
     local buffer_table = shallowcopy(foo_bar_map_table)
-    buffer_table['buffer'] = 1
+    buffer_table['buf'] = 1
+    buffer_table['buffer'] = 1 -- deprecated
 
     command('nnoremap <buffer> foo bar')
 
@@ -120,7 +122,8 @@ describe('nvim_get_keymap', function()
     command('nnoremap foo bar')
 
     local buffer_table = shallowcopy(foo_bar_map_table)
-    buffer_table['buffer'] = 1
+    buffer_table['buf'] = 1
+    buffer_table['buffer'] = 1 -- deprecated
 
     command('nnoremap <buffer> foo bar')
 
@@ -143,7 +146,8 @@ describe('nvim_get_keymap', function()
     command('nnoremap <buffer> foo bar')
     -- Final buffer will have buffer mappings
     local buffer_table = shallowcopy(foo_bar_map_table)
-    buffer_table['buffer'] = final_buffer
+    buffer_table['buf'] = final_buffer
+    buffer_table['buffer'] = final_buffer -- deprecated
     eq({ buffer_table }, api.nvim_buf_get_keymap(final_buffer, 'n'))
     eq({ buffer_table }, api.nvim_buf_get_keymap(0, 'n'))
 
@@ -302,7 +306,7 @@ describe('nvim_get_keymap', function()
     eq(':let g:maparg_test_var = 1<CR>', api.nvim_get_keymap('n')[1]['rhs'])
   end)
 
-  it('works correctly despite various &cpo settings', function()
+  it("works correctly despite 'cpoptions'", function()
     local cpo_table = {
       script = 0,
       silent = 0,
@@ -310,7 +314,8 @@ describe('nvim_get_keymap', function()
       replace_keycodes = 0,
       sid = 0,
       scriptversion = 1,
-      buffer = 0,
+      buf = 0,
+      buffer = 0, -- deprecated
       nowait = 0,
       abbr = 0,
       noremap = 1,
@@ -383,7 +388,8 @@ describe('nvim_get_keymap', function()
       replace_keycodes = 0,
       sid = 0,
       scriptversion = 1,
-      buffer = 0,
+      buf = 0,
+      buffer = 0, -- deprecated
       nowait = 0,
       noremap = 1,
       lnum = 0,
@@ -431,7 +437,8 @@ describe('nvim_get_keymap', function()
       replace_keycodes = 0,
       sid = sid_lua,
       scriptversion = 1,
-      buffer = 0,
+      buf = 0,
+      buffer = 0, -- deprecated
       nowait = 0,
       mode = 'n',
       mode_bits = 0x01,
@@ -453,7 +460,8 @@ describe('nvim_get_keymap', function()
       replace_keycodes = 0,
       sid = sid_api_client,
       scriptversion = 1,
-      buffer = 0,
+      buf = 0,
+      buffer = 0, -- deprecated
       nowait = 0,
       mode = 'n',
       mode_bits = 0x01,
@@ -470,7 +478,8 @@ describe('nvim_get_keymap', function()
 
     local mapargs_i = {
       abbr = 1,
-      buffer = 0,
+      buf = 0,
+      buffer = 0, -- deprecated
       expr = 0,
       replace_keycodes = 0,
       lhs = 'foo',
@@ -488,7 +497,8 @@ describe('nvim_get_keymap', function()
     }
     local mapargs_c = {
       abbr = 1,
-      buffer = 1,
+      buf = 1,
+      buffer = 1, -- deprecated
       expr = 0,
       replace_keycodes = 0,
       lhs = 'foo',
@@ -559,6 +569,7 @@ describe('nvim_set_keymap, nvim_del_keymap', function()
     to_return.replace_keycodes = not opts.replace_keycodes and 0 or 1
     to_return.sid = not opts.sid and sid_api_client or opts.sid
     to_return.scriptversion = 1
+    -- to_return.buf = not opts.buffer and 0 or opts.buffer
     to_return.buffer = not opts.buffer and 0 or opts.buffer
     to_return.lnum = not opts.lnum and 0 or opts.lnum
     to_return.desc = opts.desc

test/functional/api/vim_spec.lua

@@ -2863,7 +2863,8 @@ describe('API', function()
         id = id,
         argv = argv,
         mode = 'terminal',
-        buffer = buffer,
+        buf = buffer,
+        buffer = buffer, -- deprecated
         pty = '?',
         exitcode = -1,
       }
@@ -2883,7 +2884,8 @@ describe('API', function()
         neq(nil, string.match(info.pty, '^/dev/'))
       end
       eq({ info = info }, event)
-      info.buffer = 1
+      info.buf = 1
+      info.buffer = 1 -- deprecated
       eq({ [1] = testinfo, [2] = stderr, [3] = info }, api.nvim_list_chans())
       eq(info, api.nvim_get_chan_info(3))