refactor: correct comments and assertions about mapping rhs <Nop> (#18821)

Also avoid referring to mappings as "keymaps" in commands and docs.

						*map_empty_rhs* *map-empty-rhs*
You can create an empty {rhs} by typing nothing after a single CTRL-V (you
have to type CTRL-V two times).  Unfortunately, you cannot do this in a vimrc
file.

6 files changed, 22 insertions, 18 deletions

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index eebbc3f73a..6a87e482ef 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -6688,7 +6688,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 			global
 	When bigger than zero, Vim will give messages about what it is doing.
 	Currently, these messages are given:
-	>= 1	Lua assignments to options,keymaps etc.
+	>= 1	Lua assignments to options, mappings, etc.
 	>= 2	When a file is ":source"'ed and when the shada file is read or written..
 	>= 3	UI info, terminal capabilities
 	>= 4	Shell commands.
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index 6981ecc455..af4aaf01aa 100644
--- a/src/nvim/api/private/helpers.c
+++ b/src/nvim/api/private/helpers.c
@@ -678,11 +678,7 @@ void modify_keymap(uint64_t channel_id, Buffer buffer, bool is_unmap, String mod
     if (rhs.size == 0) {  // assume that the user wants RHS to be a <Nop>
       parsed_args.rhs_is_noop = true;
     } else {
-      // the given RHS was nonempty and not a <Nop>, but was parsed as if it
-      // were empty?
-      assert(false && "Failed to parse nonempty RHS!");
-      api_set_error(err, kErrorTypeValidation, "Parsing of nonempty RHS failed: %s", rhs.data);
-      goto fail_and_free;
+      abort();  // should never happen
     }
   } else if (is_unmap && (parsed_args.rhs_len || parsed_args.rhs_lua != LUA_NOREF)) {
     if (parsed_args.rhs_len) {
diff --git a/src/nvim/getchar.c b/src/nvim/getchar.c
index 788e1113e2..85ac52cafd 100644
--- a/src/nvim/getchar.c
+++ b/src/nvim/getchar.c
@@ -2839,8 +2839,8 @@ int fix_input_buffer(char_u *buf, int len)
 /// the final `lhs` exceeds `MAXMAPLEN`, `lhs_len` will be set equal to the
 /// original larger length and `lhs` will be truncated.
 ///
-/// If RHS is equal to "<Nop>", `rhs` will be the empty string, `rhs_len`
-/// will be zero, and `rhs_is_noop` will be set to true.
+/// If RHS should be <Nop>, `rhs` will be an empty string, `rhs_len` will be
+/// zero, and `rhs_is_noop` will be set to true.
 ///
 /// Any memory allocated by @ref replace_termcodes is freed before this function
 /// returns.
@@ -2898,8 +2898,9 @@ void set_maparg_lhs_rhs(const char *const orig_lhs, const size_t orig_lhs_len,
       replaced = replace_termcodes(orig_rhs, orig_rhs_len, &rhs_buf, REPTERM_DO_LT, NULL,
                                    cpo_flags);
       mapargs->rhs_len = STRLEN(replaced);
-      // XXX: even when orig_rhs is non-empty, replace_termcodes may produce an empty string.
-      mapargs->rhs_is_noop = orig_rhs[0] != NUL && mapargs->rhs_len == 0;
+      // XXX: replace_termcodes may produce an empty string even if orig_rhs is non-empty
+      // (e.g. a single ^V, see :h map-empty-rhs)
+      mapargs->rhs_is_noop = orig_rhs_len != 0 && mapargs->rhs_len == 0;
       mapargs->rhs = xcalloc(mapargs->rhs_len + 1, sizeof(char_u));
       STRLCPY(mapargs->rhs, replaced, mapargs->rhs_len + 1);
     }
diff --git a/src/nvim/getchar.h b/src/nvim/getchar.h
index 237f0632bd..ddd6d81aef 100644
--- a/src/nvim/getchar.h
+++ b/src/nvim/getchar.h
@@ -54,8 +54,8 @@ struct map_arguments {
 
   char_u *rhs;  /// The {rhs} of the mapping.
   size_t rhs_len;
-  LuaRef rhs_lua;  /// lua function as rhs
-  bool rhs_is_noop;  /// True when the {orig_rhs} is <nop>.
+  LuaRef rhs_lua;  /// lua function as {rhs}
+  bool rhs_is_noop;  /// True when the {rhs} should be <Nop>.
 
   char_u *orig_rhs;  /// The original text of the {rhs}.
   size_t orig_rhs_len;
diff --git a/src/nvim/normal.c b/src/nvim/normal.c
index 3b91044f41..bf0ea2aeec 100644
--- a/src/nvim/normal.c
+++ b/src/nvim/normal.c
@@ -3917,7 +3917,7 @@ static void nv_regreplay(cmdarg_T *cap)
   }
 }
 
-/// Handle a ":" command and <Cmd> or Lua keymaps.
+/// Handle a ":" command and <Cmd> or Lua mappings.
 static void nv_colon(cmdarg_T *cap)
 {
   bool cmd_result;
diff --git a/test/functional/api/keymap_spec.lua b/test/functional/api/keymap_spec.lua
index 4fb2d55a76..4bee10a006 100644
--- a/test/functional/api/keymap_spec.lua
+++ b/test/functional/api/keymap_spec.lua
@@ -321,7 +321,7 @@ describe('nvim_get_keymap', function()
     eq({space_table}, meths.get_keymap('n'))
   end)
 
-  it('can handle lua keymaps', function()
+  it('can handle lua mappings', function()
     eq(0, exec_lua [[
       GlobalCount = 0
       vim.api.nvim_set_keymap ('n', 'asdf', '', {callback = function() GlobalCount = GlobalCount + 1 end })
@@ -606,6 +606,13 @@ describe('nvim_set_keymap, nvim_del_keymap', function()
     eq({''}, curbufmeths.get_lines(0, -1, 0))
     eq(generate_mapargs('i', 'lhs', '<NOP>', {}),
        get_mapargs('i', 'lhs'))
+
+    -- a single ^V in RHS is also <Nop> (see :h map-empty-rhs)
+    meths.set_keymap('i', 'lhs', '\022', {})
+    command('normal ilhs')
+    eq({''}, curbufmeths.get_lines(0, -1, 0))
+    eq(generate_mapargs('i', 'lhs', '\022', {}),
+       get_mapargs('i', 'lhs'))
   end)
 
   it('treats an empty RHS in a mapping like a <Nop>', function()
@@ -785,7 +792,7 @@ describe('nvim_set_keymap, nvim_del_keymap', function()
 
   end)
 
-  it (':map command shows lua keymap correctly', function()
+  it (':map command shows lua mapping correctly', function()
     exec_lua [[
       vim.api.nvim_set_keymap ('n', 'asdf', '', {callback = function() print('jkl;') end })
     ]]
@@ -793,7 +800,7 @@ describe('nvim_set_keymap, nvim_del_keymap', function()
                   "^\nn  asdf          <Lua function %d+>"))
   end)
 
-  it ('mapcheck() returns lua keymap correctly', function()
+  it ('mapcheck() returns lua mapping correctly', function()
     exec_lua [[
       vim.api.nvim_set_keymap ('n', 'asdf', '', {callback = function() print('jkl;') end })
     ]]
@@ -801,7 +808,7 @@ describe('nvim_set_keymap, nvim_del_keymap', function()
                   "^<Lua function %d+>"))
   end)
 
-  it ('maparg() returns lua keymap correctly', function()
+  it ('maparg() returns lua mapping correctly', function()
     exec_lua [[
       vim.api.nvim_set_keymap ('n', 'asdf', '', {callback = function() print('jkl;') end })
     ]]
@@ -895,7 +902,7 @@ describe('nvim_set_keymap, nvim_del_keymap', function()
     eq('\nNo mapping found', helpers.exec_capture('nmap <C-I>'))
   end)
 
-  it('can set descriptions on keymaps', function()
+  it('can set descriptions on mappings', function()
     meths.set_keymap('n', 'lhs', 'rhs', {desc="map description"})
     eq(generate_mapargs('n', 'lhs', 'rhs', {desc="map description"}), get_mapargs('n', 'lhs'))
     eq("\nn  lhs           rhs\n                 map description",