test: improve mapping tests and docs (#19619)

runtime/doc/api.txt

@@ -974,7 +974,7 @@ nvim_get_keymap({mode})                                    *nvim_get_keymap()*
                     {mode}  Mode short-name ("n", "i", "v", ...)
 
                 Return: ~
-                    Array of maparg()-like dictionaries describing mappings.
+                    Array of |maparg()|-like dictionaries describing mappings.
                     The "buffer" key is always zero.
 
 nvim_get_mark({name}, {opts})                                *nvim_get_mark()*
@@ -1508,9 +1508,12 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
                             used to give a description to the mapping. When
                             called from Lua, also accepts a "callback" key
                             that takes a Lua function to call when the mapping
-                            is executed. "replace_keycodes" can be used with
+                            is executed. When "expr" is true,
-                            "expr" to replace keycodes, see
+                            "replace_keycodes" (boolean) can be used to
-                            |nvim_replace_termcodes()|.
+                            replace keycodes in the resulting string (see
+                            |nvim_replace_termcodes()|), and a Lua callback
+                            returning `nil` is equivalent to returning an
+                            empty string.
 
 nvim_set_var({name}, {value})                                 *nvim_set_var()*
                 Sets a global (g:) variable.
@@ -2299,7 +2302,7 @@ nvim_buf_get_keymap({buffer}, {mode})                  *nvim_buf_get_keymap()*
                     {buffer}  Buffer handle, or 0 for current buffer
 
                 Return: ~
-                    Array of maparg()-like dictionaries describing mappings.
+                    Array of |maparg()|-like dictionaries describing mappings.
                     The "buffer" key holds the associated buffer handle.
 
                                                         *nvim_buf_get_lines()*

runtime/doc/lua.txt

@@ -2218,9 +2218,7 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
                             create mapping on multiple modes.
                     {lhs}   (string) Left-hand side |{lhs}| of the mapping.
                     {rhs}   string|function Right-hand side |{rhs}| of the
-                            mapping. Can also be a Lua function. If a Lua
+                            mapping. Can also be a Lua function.
-                            function and `opts.expr == true`, returning `nil`
-                            is equivalent to an empty string.
                     {opts}  (table) A table of |:map-arguments| such as
                             "silent". In addition to the options listed in
                             |nvim_set_keymap()|, this table also accepts the

runtime/lua/vim/keymap.lua

@@ -31,12 +31,10 @@ local keymap = {}
 ---    vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
 --- </pre>
 ---
----@param mode string|table   Same mode short names as |nvim_set_keymap()|.
+---@param mode string|table    Same mode short names as |nvim_set_keymap()|.
 ---                            Can also be list of modes to create mapping on multiple modes.
----@param lhs string          Left-hand side |{lhs}| of the mapping.
+---@param lhs string           Left-hand side |{lhs}| of the mapping.
 ---@param rhs string|function  Right-hand side |{rhs}| of the mapping. Can also be a Lua function.
----                            If a Lua function and `opts.expr == true`, returning `nil` is
----                            equivalent to an empty string.
 --
 ---@param opts table A table of |:map-arguments| such as "silent". In addition to the options
 ---                  listed in |nvim_set_keymap()|, this table also accepts the following keys:

src/nvim/api/buffer.c

@@ -932,7 +932,7 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
 /// @param  mode       Mode short-name ("n", "i", "v", ...)
 /// @param  buffer     Buffer handle, or 0 for current buffer
 /// @param[out]  err   Error details, if any
-/// @returns Array of maparg()-like dictionaries describing mappings.
+/// @returns Array of |maparg()|-like dictionaries describing mappings.
 ///          The "buffer" key holds the associated buffer handle.
 ArrayOf(Dictionary) nvim_buf_get_keymap(uint64_t channel_id, Buffer buffer, String mode, Error *err)
   FUNC_API_SINCE(3)

src/nvim/api/vim.c

@@ -1411,7 +1411,7 @@ Dictionary nvim_get_mode(void)
 /// Gets a list of global (non-buffer-local) |mapping| definitions.
 ///
 /// @param  mode       Mode short-name ("n", "i", "v", ...)
-/// @returns Array of maparg()-like dictionaries describing mappings.
+/// @returns Array of |maparg()|-like dictionaries describing mappings.
 ///          The "buffer" key is always zero.
 ArrayOf(Dictionary) nvim_get_keymap(uint64_t channel_id, String mode)
   FUNC_API_SINCE(3)
@@ -1423,8 +1423,8 @@ ArrayOf(Dictionary) nvim_get_keymap(uint64_t channel_id, String mode)
 ///
 /// To set a buffer-local mapping, use |nvim_buf_set_keymap()|.
 ///
-/// Unlike |:map|, leading/trailing whitespace is accepted as part of the {lhs}
+/// Unlike |:map|, leading/trailing whitespace is accepted as part of the {lhs} or {rhs}.
-/// or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
+/// Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
 ///
 /// Example:
 /// <pre>
@@ -1441,14 +1441,15 @@ ArrayOf(Dictionary) nvim_get_keymap(uint64_t channel_id, String mode)
 ///               or "!" for |:map!|, or empty string for |:map|.
 /// @param  lhs   Left-hand-side |{lhs}| of the mapping.
 /// @param  rhs   Right-hand-side |{rhs}| of the mapping.
-/// @param  opts  Optional parameters map: keys are |:map-arguments|, values
+/// @param  opts  Optional parameters map: keys are |:map-arguments|, values are booleans (default
-///               are booleans (default false). Accepts all |:map-arguments| as
+///               false). Accepts all |:map-arguments| as keys excluding |<buffer>| but including
-///               keys excluding |<buffer>| but including |noremap| and "desc".
+///               |noremap| and "desc". Unknown key is an error.
-///               Unknown key is an error. "desc" can be used to give a
+///               "desc" can be used to give a description to the mapping.
-///               description to the mapping. When called from Lua, also accepts a
+///               When called from Lua, also accepts a "callback" key that takes a Lua function to
-///               "callback" key that takes a Lua function to call when the
+///               call when the mapping is executed.
-///               mapping is executed. "replace_keycodes" can be used with "expr"
+///               When "expr" is true, "replace_keycodes" (boolean) can be used to replace keycodes
-///               to replace keycodes, see |nvim_replace_termcodes()|.
+///               in the resulting string (see |nvim_replace_termcodes()|), and a Lua callback
+///               returning `nil` is equivalent to returning an empty string.
 /// @param[out]   err   Error details, if any.
 void nvim_set_keymap(uint64_t channel_id, String mode, String lhs, String rhs, Dict(keymap) *opts,
                      Error *err)

src/nvim/mapping.c

@@ -1537,9 +1537,6 @@ char_u *eval_map_expr(mapblock_T *mp, int c)
 {
   char_u *p = NULL;
   char_u *expr = NULL;
-  pos_T save_cursor;
-  int save_msg_col;
-  int save_msg_row;
 
   // Remove escaping of K_SPECIAL, because "str" is in a format to be used as
   // typeahead.
@@ -1553,9 +1550,9 @@ char_u *eval_map_expr(mapblock_T *mp, int c)
   textlock++;
   ex_normal_lock++;
   set_vim_var_char(c);    // set v:char to the typed character
-  save_cursor = curwin->w_cursor;
+  const pos_T save_cursor = curwin->w_cursor;
-  save_msg_col = msg_col;
+  const int save_msg_col = msg_col;
-  save_msg_row = msg_row;
+  const int save_msg_row = msg_row;
   if (mp->m_luaref != LUA_NOREF) {
     Error err = ERROR_INIT;
     Array args = ARRAY_DICT_INIT;

test/functional/api/keymap_spec.lua

@@ -523,6 +523,11 @@ describe('nvim_set_keymap, nvim_del_keymap', function()
       pcall_err(meths.set_keymap, 'n', 'lhs', 'rhs', {buffer = true}))
   end)
 
+  it('error when "replace_keycodes" is used without "expr"', function()
+    eq('"replace_keycodes" requires "expr"',
+      pcall_err(meths.set_keymap, 'n', 'lhs', 'rhs', {replace_keycodes = true}))
+  end)
+
   local optnames = {'nowait', 'silent', 'script', 'expr', 'unique'}
   for _, opt in ipairs(optnames) do
     -- note: need '%' to escape hyphens, which have special meaning in lua
@@ -842,14 +847,14 @@ describe('nvim_set_keymap, nvim_del_keymap', function()
     eq(generate_mapargs('n', 'asdf', nil, {sid=sid_lua}), mapargs)
   end)
 
-  it('can make lua expr mappings', function()
+  it('can make lua expr mappings replacing keycodes', function()
     exec_lua [[
-      vim.api.nvim_set_keymap ('n', 'aa', '', {callback = function() return ':lua SomeValue = 99<cr>' end, expr = true, replace_keycodes = true })
+      vim.api.nvim_set_keymap ('n', 'aa', '', {callback = function() return '<Insert>π<C-V><M-π>foo<lt><Esc>' end, expr = true, replace_keycodes = true })
     ]]
 
     feed('aa')
 
-    eq(99, exec_lua[[return SomeValue]])
+    eq({'π<M-π>foo<'}, meths.buf_get_lines(0, 0, -1, false))
   end)
 
   it('can make lua expr mappings without replacing keycodes', function()
@@ -862,6 +867,16 @@ describe('nvim_set_keymap, nvim_del_keymap', function()
     eq({'<space>'}, meths.buf_get_lines(0, 0, -1, false))
   end)
 
+  it('lua expr mapping returning nil is equivalent to returnig an empty string', function()
+    exec_lua [[
+      vim.api.nvim_set_keymap ('i', 'aa', '', {callback = function() return nil end, expr = true })
+    ]]
+
+    feed('iaa<esc>')
+
+    eq({''}, meths.buf_get_lines(0, 0, -1, false))
+  end)
+
   it('does not reset pum in lua mapping', function()
     eq(0, exec_lua [[
       VisibleCount = 0
@@ -1050,14 +1065,14 @@ describe('nvim_buf_set_keymap, nvim_buf_del_keymap', function()
     eq(1, exec_lua[[return GlobalCount]])
   end)
 
-  it('can make lua expr mappings', function()
+  it('can make lua expr mappings replacing keycodes', function()
     exec_lua [[
-      vim.api.nvim_buf_set_keymap (0, 'n', 'aa', '', {callback = function() return ':lua SomeValue = 99<cr>' end, expr = true, replace_keycodes = true })
+      vim.api.nvim_buf_set_keymap (0, 'n', 'aa', '', {callback = function() return '<Insert>π<C-V><M-π>foo<lt><Esc>' end, expr = true, replace_keycodes = true })
     ]]
 
     feed('aa')
 
-    eq(99, exec_lua[[return SomeValue ]])
+    eq({'π<M-π>foo<'}, meths.buf_get_lines(0, 0, -1, false))
   end)
 
   it('can make lua expr mappings without replacing keycodes', function()

test/functional/lua/vim_spec.lua

@@ -2792,12 +2792,12 @@ describe('vim.keymap', function()
 
   it('can make an expr mapping', function()
     exec_lua [[
-      vim.keymap.set('n', 'aa', function() return ':lua SomeValue = 99<cr>' end, {expr = true})
+      vim.keymap.set('n', 'aa', function() return '<Insert>π<C-V><M-π>foo<lt><Esc>' end, {expr = true})
     ]]
 
     feed('aa')
 
-    eq(99, exec_lua[[return SomeValue]])
+    eq({'π<M-π>foo<'}, meths.buf_get_lines(0, 0, -1, false))
   end)
 
   it('can overwrite a mapping', function()