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

1 files changed, 54 insertions, 0 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 7c87ca7887..46e1c12090 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -807,6 +807,47 @@ nvim_get_keymap({mode})                                    *nvim_get_keymap()*
                     Array of maparg()-like dictionaries describing mappings.
                     The "buffer" key is always zero.
 
+nvim_set_keymap({mode}, {lhs}, {rhs}, {opts})              *nvim_set_keymap()*
+                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>`
+
+                Parameters: ~
+                    {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".
+                    {lhs}   Left-hand-side |{lhs}| of the mapping.
+                    {rhs}   Right-hand-side |{rhs}| of the mapping.
+                    {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.
+
+nvim_del_keymap({mode}, {lhs})                             *nvim_del_keymap()*
+                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.
+
 nvim_get_commands({opts})                                *nvim_get_commands()*
                 Gets a map of global (non-buffer-local) Ex commands.
 
@@ -1296,6 +1337,19 @@ nvim_buf_get_keymap({buffer}, {mode})                  *nvim_buf_get_keymap()*
                     Array of maparg()-like dictionaries describing mappings.
                     The "buffer" key holds the associated buffer handle.
 
+                                                       *nvim_buf_set_keymap()*
+nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts})
+                Like |nvim_set_keymap|, but for a specific buffer.
+
+                Parameters: ~
+                    {buffer}  Buffer handle, or 0 for the current buffer.
+
+nvim_buf_del_keymap({buffer}, {mode}, {lhs})           *nvim_buf_del_keymap()*
+                Like |nvim_del_keymap|, but for a specific buffer.
+
+                Parameters: ~
+                    {buffer}  Buffer handle, or 0 for the current buffer.
+
 nvim_buf_get_commands({buffer}, {opts})              *nvim_buf_get_commands()*
                 Gets a map of buffer-local |user-commands|.