API/nvim_set_keymap: minor cleanup

ref #9924

.gitignore

@@ -1,5 +1,6 @@
 # Tools
 .ropeproject/
+compile_commands.json
 # Visual Studio
 /.vs/
 
@@ -54,4 +55,3 @@ local.mk
 /runtime/doc/*.html
 /runtime/doc/tags.ref
 /runtime/doc/errors.log
-compile_commands.json

runtime/doc/api.txt

@@ -810,43 +810,38 @@ nvim_get_keymap({mode})                                    *nvim_get_keymap()*
 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|.
+                To set a buffer-local mapping, use |nvim_buf_set_keymap()|.
 
-                Unlike ordinary Ex mode |:map| commands, special characters
+                Unlike |:map|, leading/trailing whitespace is accepted as part
-                like literal spaces and newlines are treated as an actual part
+                of the {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are
-                of the {lhs} or {rhs}. An empty {rhs} is treated like a
+                replaced as usual.
-                |<Nop>|. |keycodes| are still replaced as usual.
 
-                `call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})`
+                Example: >
+                    call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
+<
 
-                Is equivalent to,
+                is equivalent to: >
-
+                    nmap <nowait> <Space><NL> <Nop>
-                `nmap <nowait> <Space><NL> <Nop>`
+<
 
                 Parameters: ~
-                    {mode}  Mode short-name (the first character of an map
+                    {mode}  Mode short-name (map command prefix: "n", "i",
-                            command, e.g. "n", "i", "v", "x", etc.) OR the
+                            "v", "x", …) or "!" for |:map!|, or empty string
-                            string "!" (for |:map!|). |:map| can be
+                            for |:map|.
-                            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
+                    {opts}  Optional parameters map. Accepts all
                             |:map-arguments| as keys excluding |<buffer>| but
-                            also including |noremap|. Values should all be
+                            including |noremap|. Values are Booleans. Unknown
-                            Booleans. Unrecognized keys will result in an
+                            key is an error.
-                            error.
 
 nvim_del_keymap({mode}, {lhs})                             *nvim_del_keymap()*
-                Unmap a global |mapping| for the given mode.
+                Unmaps a global |mapping| for the given mode.
 
-                To unmap a buffer-local mapping, use |nvim_buf_del_keymap|.
+                To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|.
 
-                Arguments are handled like |nvim_set_keymap|. Like with
+                See also: ~
-                ordinary |:unmap| commands (and `nvim_set_keymap` ), the given
+                    |nvim_set_keymap()|
-                {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.
@@ -1339,16 +1334,22 @@ nvim_buf_get_keymap({buffer}, {mode})                  *nvim_buf_get_keymap()*
 
                                                        *nvim_buf_set_keymap()*
 nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts})
-                Like |nvim_set_keymap|, but for a specific buffer.
+                Sets a buffer-local |mapping| for the given mode.
 
                 Parameters: ~
-                    {buffer}  Buffer handle, or 0 for the current buffer.
+                    {buffer}  Buffer handle, or 0 for current buffer
+
+                See also: ~
+                    |nvim_set_keymap()|
 
 nvim_buf_del_keymap({buffer}, {mode}, {lhs})           *nvim_buf_del_keymap()*
-                Like |nvim_del_keymap|, but for a specific buffer.
+                Unmaps a buffer-local |mapping| for the given mode.
 
                 Parameters: ~
-                    {buffer}  Buffer handle, or 0 for the current buffer.
+                    {buffer}  Buffer handle, or 0 for current buffer
+
+                See also: ~
+                    |nvim_del_keymap()|
 
 nvim_buf_get_commands({buffer}, {opts})              *nvim_buf_get_commands()*
                 Gets a map of buffer-local |user-commands|.

src/nvim/api/buffer.c

@@ -577,9 +577,11 @@ ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
   return keymap_array(mode, buf);
 }
 
-/// Like |nvim_set_keymap|, but for a specific buffer.
+/// Sets a buffer-local |mapping| for the given mode.
 ///
-/// @param  buffer  Buffer handle, or 0 for the current buffer.
+/// @see |nvim_set_keymap()|
+///
+/// @param  buffer  Buffer handle, or 0 for current buffer
 void nvim_buf_set_keymap(Buffer buffer, String mode, String lhs, String rhs,
                          Dictionary opts, Error *err)
   FUNC_API_SINCE(6)
@@ -587,9 +589,11 @@ void nvim_buf_set_keymap(Buffer buffer, String mode, String lhs, String rhs,
   modify_keymap(buffer, false, mode, lhs, rhs, opts, err);
 }
 
-/// Like |nvim_del_keymap|, but for a specific buffer.
+/// Unmaps a buffer-local |mapping| for the given mode.
 ///
-/// @param  buffer  Buffer handle, or 0 for the current buffer.
+/// @see |nvim_del_keymap()|
+///
+/// @param  buffer  Buffer handle, or 0 for current buffer
 void nvim_buf_del_keymap(Buffer buffer, String mode, String lhs, Error *err)
   FUNC_API_SINCE(6)
 {

src/nvim/api/private/helpers.c

@@ -770,7 +770,7 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
   MapArguments parsed_args;
   memset(&parsed_args, 0, sizeof(parsed_args));
   if (parse_keymap_opts(opts, &parsed_args, err)) {
-    goto FAIL_AND_FREE;
+    goto fail_and_free;
   }
   parsed_args.buffer = !global;
 
@@ -782,14 +782,14 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
     err_msg = "LHS exceeds maximum map length: %s";
     err_arg = lhs.data;
     err_type = kErrorTypeValidation;
-    goto FAIL_WITH_MESSAGE;
+    goto fail_with_message;
   }
 
   if (mode.size > 1) {
     err_msg = "Shortname is too long: %s";
     err_arg = mode.data;
     err_type = kErrorTypeValidation;
-    goto FAIL_WITH_MESSAGE;
+    goto fail_with_message;
   }
   int mode_val;  // integer value of the mapping mode, to be passed to do_map()
   char_u *p = (char_u *)((mode.size) ? mode.data : "m");
@@ -804,7 +804,7 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
         err_msg = "Invalid mode shortname: %s";
         err_arg = (char *)p;
         err_type = kErrorTypeValidation;
-        goto FAIL_WITH_MESSAGE;
+        goto fail_with_message;
       }
     }
   }
@@ -813,7 +813,7 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
     err_msg = "Invalid (empty) LHS";
     err_arg = "";
     err_type = kErrorTypeValidation;
-    goto FAIL_WITH_MESSAGE;
+    goto fail_with_message;
   }
 
   bool is_noremap = parsed_args.noremap;
@@ -829,16 +829,16 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
       err_msg = "Parsing of nonempty RHS failed: %s";
       err_arg = rhs.data;
       err_type = kErrorTypeException;
-      goto FAIL_WITH_MESSAGE;
+      goto fail_with_message;
     }
   } else if (is_unmap && parsed_args.rhs_len) {
     err_msg = "Gave nonempty RHS in unmap command: %s";
     err_arg = (char *)parsed_args.rhs;
     err_type = kErrorTypeValidation;
-    goto FAIL_WITH_MESSAGE;
+    goto fail_with_message;
   }
 
-  // buf_do_map_explicit reads noremap/unmap as its own argument
+  // buf_do_map() reads noremap/unmap as its own argument.
   int maptype_val = 0;
   if (is_unmap) {
     maptype_val = 1;
@@ -846,23 +846,22 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
     maptype_val = 2;
   }
 
-  switch (buf_do_map_explicit(maptype_val, &parsed_args, mode_val,
+  switch (buf_do_map(maptype_val, &parsed_args, mode_val, 0, target_buf)) {
-                              0, target_buf)) {
     case 0:
       break;
     case 1:
       api_set_error(err, kErrorTypeException, (char *)e_invarg, 0);
-      goto FAIL_AND_FREE;
+      goto fail_and_free;
     case 2:
       api_set_error(err, kErrorTypeException, (char *)e_nomap, 0);
-      goto FAIL_AND_FREE;
+      goto fail_and_free;
     case 5:
       api_set_error(err, kErrorTypeException,
                     "E227: mapping already exists for %s", parsed_args.lhs);
-      goto FAIL_AND_FREE;
+      goto fail_and_free;
     default:
       assert(false && "Unrecognized return code!");
-      goto FAIL_AND_FREE;
+      goto fail_and_free;
   }  // switch
 
   xfree(lhs_buf);
@@ -872,10 +871,10 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
 
   return;
 
-FAIL_WITH_MESSAGE:
+fail_with_message:
   api_set_error(err, err_type, err_msg, err_arg);
 
-FAIL_AND_FREE:
+fail_and_free:
   xfree(lhs_buf);
   xfree(rhs_buf);
   xfree(parsed_args.rhs);
@@ -913,7 +912,7 @@ Integer parse_keymap_opts(Dictionary opts, MapArguments *out, Error *err)
       err_msg = "Gave non-boolean value for an opt: %s";
       err_arg = optname;
       err_type = kErrorTypeValidation;
-      goto FAIL_WITH_MESSAGE;
+      goto fail_with_message;
     }
 
     bool was_valid_opt = false;
@@ -961,13 +960,13 @@ Integer parse_keymap_opts(Dictionary opts, MapArguments *out, Error *err)
       err_msg = "Invalid key: %s";
       err_arg = optname;
       err_type = kErrorTypeValidation;
-      goto FAIL_WITH_MESSAGE;
+      goto fail_with_message;
     }
   }  // for
 
   return 0;
 
-FAIL_WITH_MESSAGE:
+fail_with_message:
   api_set_error(err, err_type, err_msg, err_arg);
   return 1;
 }

src/nvim/api/vim.c

@@ -1264,29 +1264,28 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
 
 /// Sets a global |mapping| for the given mode.
 ///
-/// To set a buffer-local mapping, use |nvim_buf_set_keymap|.
+/// To set a buffer-local mapping, use |nvim_buf_set_keymap()|.
 ///
-/// Unlike ordinary Ex mode |:map| commands, special characters like literal
+/// Unlike |:map|, leading/trailing whitespace is accepted as part of the {lhs}
-/// spaces and newlines are treated as an actual part of the {lhs} or {rhs}.
+/// or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
-/// An empty {rhs} is treated like a |<Nop>|. |keycodes| are still replaced as
-/// usual.
 ///
-/// `call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})`
+/// Example:
+/// <pre>
+///     call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
+/// </pre>
 ///
-/// Is equivalent to,
+/// is equivalent to:
+/// <pre>
+///     nmap <nowait> <Space><NL> <Nop>
+/// </pre>
 ///
-/// `nmap <nowait> <Space><NL> <Nop>`
+/// @param  mode  Mode short-name (map command prefix: "n", "i", "v", "x", …)
-///
+///               or "!" for |:map!|, or empty string for |:map|.
-/// @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|
+/// @param  opts  Optional parameters map. Accepts all |:map-arguments|
-///               as keys excluding |<buffer>| but also including |noremap|.
+///               as keys excluding |<buffer>| but including |noremap|.
-///               Values should all be Booleans. Unrecognized keys will result
+///               Values are Booleans. Unknown key is an error.
-///               in an error.
 /// @param[out]   err   Error details, if any.
 void nvim_set_keymap(String mode, String lhs, String rhs,
                      Dictionary opts, Error *err)
@@ -1295,14 +1294,11 @@ void nvim_set_keymap(String mode, String lhs, String rhs,
   modify_keymap(-1, false, mode, lhs, rhs, opts, err);
 }
 
-/// Unmap a global |mapping| for the given mode.
+/// Unmaps a global |mapping| for the given mode.
 ///
-/// To unmap a buffer-local mapping, use |nvim_buf_del_keymap|.
+/// To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|.
 ///
-/// Arguments are handled like |nvim_set_keymap|. Like with ordinary |:unmap|
+/// @see |nvim_set_keymap()|
-/// 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)
 {

src/nvim/getchar.c

@@ -2683,15 +2683,18 @@ int str_to_mapargs(const char_u *strargs, bool is_unmap, MapArguments *mapargs)
   return 0;
 }
 
-/// Actually set/unset a mapping or abbreviation.
+/// Sets or removes a mapping or abbreviation in buffer `buf`.
 ///
-/// Parameters are like @ref buf_do_map unless otherwise noted.
+/// @param maptype    @see do_map
 /// @param args  Fully parsed and "preprocessed" arguments for the
 ///              (un)map/abbrev command. Termcodes should have already been
 ///              replaced; whitespace, `<` and `>` signs, etc. in {lhs} and
 ///              {rhs} are assumed to be literal components of the mapping.
-int buf_do_map_explicit(int maptype, MapArguments *args, int mode,
+/// @param mode       @see do_map
-                        bool is_abbrev, buf_T *buf)
+/// @param is_abbrev  @see do_map
+/// @param buf        Target Buffer
+int buf_do_map(int maptype, MapArguments *args, int mode, bool is_abbrev,
+               buf_T *buf)
 {
   mapblock_T  *mp, **mpp;
   char_u      *p;
@@ -3030,31 +3033,6 @@ theend:
   return retval;
 }
 
-/// Like @ref do_map, but you can specify the target buffer.
-int buf_do_map(int maptype, char_u *arg, int mode, bool is_abbrev, buf_T *buf)
-{
-  MapArguments parsed_args;
-  int result = str_to_mapargs(arg, maptype == 1, &parsed_args);
-  switch (result) {
-    case 0:
-      break;
-    case 1:
-      result = 1;  // invalid arguments
-      goto FREE_AND_RETURN;
-    default:
-      assert(false && "Unknown return code from str_to_mapargs!");
-      result = -1;
-      goto FREE_AND_RETURN;
-  }  // switch
-
-  result = buf_do_map_explicit(maptype, &parsed_args, mode, is_abbrev, buf);
-
-FREE_AND_RETURN:
-  xfree(parsed_args.rhs);
-  xfree(parsed_args.orig_rhs);
-  return result;
-}
-
 
 /// Set or remove a mapping or an abbreviation in the current buffer, OR
 /// display (matching) mappings/abbreviations.
@@ -3104,7 +3082,26 @@ FREE_AND_RETURN:
 ///
 int do_map(int maptype, char_u *arg, int mode, bool is_abbrev)
 {
-  return buf_do_map(maptype, arg, mode, is_abbrev, curbuf);
+  MapArguments parsed_args;
+  int result = str_to_mapargs(arg, maptype == 1, &parsed_args);
+  switch (result) {
+    case 0:
+      break;
+    case 1:
+      result = 1;  // invalid arguments
+      goto free_and_return;
+    default:
+      assert(false && "Unknown return code from str_to_mapargs!");
+      result = -1;
+      goto free_and_return;
+  }  // switch
+
+  result = buf_do_map(maptype, &parsed_args, mode, is_abbrev, curbuf);
+
+free_and_return:
+  xfree(parsed_args.rhs);
+  xfree(parsed_args.orig_rhs);
+  return result;
 }
 
 /*

test/functional/api/keymap_spec.lua

@@ -313,7 +313,7 @@ describe('nvim_get_keymap', function()
   end)
 end)
 
-describe('nvim_[set/del]_keymap', function()
+describe('nvim_set_keymap, nvim_del_keymap', function()
   before_each(clear)
 
   -- generate_expected is truthy when we want to generate an expected output for
@@ -720,7 +720,7 @@ describe('nvim_[set/del]_keymap', function()
   end
 end)
 
-describe('nvim_buf_[set/del]_keymap', function()
+describe('nvim_buf_set_keymap, nvim_buf_del_keymap', function()
   before_each(clear)
 
   -- nvim_set_keymap is implemented as a wrapped call to nvim_buf_set_keymap,