API: nvim_set_keymap, nvim_del_keymap #9924

closes #9136

- Treat empty {rhs} like <Nop>

- getchar.c: Pull "repl. MapArg termcodes" into func
  The "preprocessing code" surrounding the replace_termcodes calls needs
  to invoke replace_termcodes, and also check if RHS is equal to "<Nop>".
  To reduce code duplication, factor this out into a helper function.

  Also add an rhs_is_noop flag to MapArguments; buf_do_map_explicit
  expects an empty {rhs} string for "<Nop>", but also needs to distinguish
  that from something like ":map lhs<cr>" where no {rhs} was provided.

- getchar.c: Use allocated buffer for rhs in MapArgs
  Since the MAXMAPLEN limit does not apply to the RHS of a mapping (or
  else an RHS that calls a really long autoload function from a plugin
  would be incorrectly rejected as being too long), use an allocated
  buffer for RHS rather than a static buffer of length MAXMAPLEN + 1.

- Mappings LHS and RHS can contain literal space characters, newlines, etc.

- getchar.c: replace_termcodes in str_to_mapargs
  It makes sense to do this; str_to_mapargs is, intuitively, supposed to
  take a "raw" command string and parse it into a totally "do_map-ready"
  struct.

- api/vim.c: Update lhs, rhs len after replace_termcodes
  Fixes a bug in which replace_termcodes changes the length of lhs or rhs,
  but the later search through the mappings/abbreviations hashtables
  still uses the old length value. This would cause the search to fail
  erroneously and throw 'E31: No such mapping' errors or 'E24: No such
  abbreviation' errors.

- getchar: Create new map_arguments struct
  So that a string of map arguments can be parsed into a more useful, more
  portable data structure.

- getchar.c: Add buf_do_map function
  Exactly the same as the old do_map, but replace the hardcoded references
  to the global `buf_T* curbuf` with a function parameter so that we can
  invoke it from nvim_buf_set_keymap.

- Remove gettext calls in do_map error handling

src/nvim/api/vim.c

@@ -1262,6 +1262,53 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
   return keymap_array(mode, NULL);
 }
 
+/// Sets a global |mapping| for the given mode.
+///
+/// To set a buffer-local mapping, use |nvim_buf_set_keymap|.
+///
+/// Unlike ordinary Ex mode |:map| commands, special characters like literal
+/// spaces and newlines are treated as an actual part of the {lhs} or {rhs}.
+/// An empty {rhs} is treated like a |<Nop>|. |keycodes| are still replaced as
+/// usual.
+///
+/// `call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})`
+///
+/// Is equivalent to,
+///
+/// `nmap <nowait> <Space><NL> <Nop>`
+///
+/// @param  mode  Mode short-name (the first character of an map command,
+///               e.g. "n", "i", "v", "x", etc.) OR the string "!" (for
+///               |:map!|). |:map| can be represented with a single space " ",
+///               an empty string, or "m".
+/// @param  lhs   Left-hand-side |{lhs}| of the mapping.
+/// @param  rhs   Right-hand-side |{rhs}| of the mapping.
+/// @param  opts  |dict| of optional parameters. Accepts all |:map-arguments|
+///               as keys excluding |<buffer>| but also including |noremap|.
+///               Values should all be Booleans. Unrecognized keys will result
+///               in an error.
+/// @param[out]   err   Error details, if any.
+void nvim_set_keymap(String mode, String lhs, String rhs,
+                     Dictionary opts, Error *err)
+  FUNC_API_SINCE(6)
+{
+  modify_keymap(-1, false, mode, lhs, rhs, opts, err);
+}
+
+/// Unmap a global |mapping| for the given mode.
+///
+/// To unmap a buffer-local mapping, use |nvim_buf_del_keymap|.
+///
+/// Arguments are handled like |nvim_set_keymap|. Like with ordinary |:unmap|
+/// commands (and `nvim_set_keymap`), the given {lhs} is interpreted literally:
+/// for instance, trailing whitespace is treated as part of the {lhs}.
+/// |keycodes| are still replaced as usual.
+void nvim_del_keymap(String mode, String lhs, Error *err)
+  FUNC_API_SINCE(6)
+{
+  nvim_buf_del_keymap(-1, mode, lhs, err);
+}
+
 /// Gets a map of global (non-buffer-local) Ex commands.
 ///
 /// Currently only |user-commands| are supported, not builtin Ex commands.