diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | runtime/doc/api.txt | 59 | ||||
| -rw-r--r-- | src/nvim/api/buffer.c | 12 | ||||
| -rw-r--r-- | src/nvim/api/private/helpers.c | 52 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 42 | ||||
| -rw-r--r-- | src/nvim/getchar.c | 57 | ||||
| -rw-r--r-- | test/functional/api/keymap_spec.lua | 58 |
7 files changed, 139 insertions, 143 deletions
diff --git a/.gitignore b/.gitignore index 57a90db188..bf9928ce15 100644 --- a/.gitignore +++ b/.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 diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 46e1c12090..ed6e4905b4 100644 --- a/runtime/doc/api.txt +++ b/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 - 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. + Unlike |:map|, leading/trailing whitespace is accepted as part + of the {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are + replaced as usual. - `call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})` - - Is equivalent to, + Example: > + call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) +< - `nmap <nowait> <Space><NL> <Nop>` + 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". + {mode} Mode short-name (map command prefix: "n", "i", + "v", "x", …) or "!" for |:map!|, or empty string + for |:map|. {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 - Booleans. Unrecognized keys will result in an - error. + including |noremap|. Values are Booleans. Unknown + key is an 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 - 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. + See also: ~ + |nvim_set_keymap()| 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|. diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 61e042ef40..9a5ffecad4 100644 --- a/src/nvim/api/buffer.c +++ b/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) { diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c index aa9b3f5f18..521ec11906 100644 --- a/src/nvim/api/private/helpers.c +++ b/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"); @@ -797,15 +797,14 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs, mode_val = get_map_mode(&p, true); // mapmode-ic } else { mode_val = get_map_mode(&p, false); - if (mode_val == VISUAL + SELECTMODE + NORMAL + OP_PENDING) { - // get_map_mode will treat "unrecognized" mode shortnames like "map" - // if it does, and the given shortname wasn't "m" or " ", then error - if (STRNCMP(p, "m", 2) && STRNCMP(p, " ", 2)) { - err_msg = "Invalid mode shortname: %s"; - err_arg = (char *)p; - err_type = kErrorTypeValidation; - goto FAIL_WITH_MESSAGE; - } + if ((mode_val == VISUAL + SELECTMODE + NORMAL + OP_PENDING) + && mode.size > 0) { + // get_map_mode() treats unrecognized mode shortnames as ":map". + // This is an error unless the given shortname was empty string "". + err_msg = "Invalid mode shortname: \"%s\""; + err_arg = (char *)p; + err_type = kErrorTypeValidation; + goto fail_with_message; } } @@ -813,7 +812,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 +828,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 +845,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, - 0, target_buf)) { + switch (buf_do_map(maptype_val, &parsed_args, mode_val, 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 +870,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 +911,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 +959,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; } diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 53aad1fe39..b8c863704a 100644 --- a/src/nvim/api/vim.c +++ b/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 -/// 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. +/// Unlike |:map|, leading/trailing whitespace is accepted as part of the {lhs} +/// or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual. /// -/// `call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})` -/// -/// Is equivalent to, +/// Example: +/// <pre> +/// call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) +/// </pre> /// -/// `nmap <nowait> <Space><NL> <Nop>` +/// is equivalent to: +/// <pre> +/// nmap <nowait> <Space><NL> <Nop> +/// </pre> /// -/// @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 mode Mode short-name (map command prefix: "n", "i", "v", "x", …) +/// 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 |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 opts Optional parameters map. Accepts all |:map-arguments| +/// as keys excluding |<buffer>| but including |noremap|. +/// Values are Booleans. Unknown key is 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| -/// 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. +/// @see |nvim_set_keymap()| void nvim_del_keymap(String mode, String lhs, Error *err) FUNC_API_SINCE(6) { diff --git a/src/nvim/getchar.c b/src/nvim/getchar.c index af9861d665..f8c7dc613b 100644 --- a/src/nvim/getchar.c +++ b/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, - bool is_abbrev, buf_T *buf) +/// @param mode @see do_map +/// @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; } /* diff --git a/test/functional/api/keymap_spec.lua b/test/functional/api/keymap_spec.lua index 47478dce5d..c150787425 100644 --- a/test/functional/api/keymap_spec.lua +++ b/test/functional/api/keymap_spec.lua @@ -313,18 +313,18 @@ 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 - -- maparg(); mapargs() won't take '!' as an input, though it will return '!' - -- in its output if getting a mapping set with |:map!| + -- `generate_expected` is truthy: for generating an expected output for + -- maparg(), which does not accept "!" (though it returns "!" in its output + -- if getting a mapping set with |:map!|). local function normalize_mapmode(mode, generate_expected) if not generate_expected and mode == '!' then - -- can't retrieve mapmode-ic mappings with '!', but can with 'i' or 'c'. + -- Cannot retrieve mapmode-ic mappings with "!", but can with "i" or "c". mode = 'i' - elseif mode == '' or mode == ' ' or mode == 'm' then - mode = generate_expected and ' ' or 'm' + elseif mode == '' then + mode = generate_expected and ' ' or mode end return mode end @@ -355,13 +355,12 @@ describe('nvim_[set/del]_keymap', function() return to_return end - -- Retrieve a mapargs dict from neovim, if one exists + -- Gets a maparg() dict from Nvim, if one exists. local function get_mapargs(mode, lhs) return funcs.maparg(lhs, normalize_mapmode(mode), false, true) end - -- Test error handling - it('throws errors when given empty lhs', function() + it('error on empty LHS', function() -- escape parentheses in lua string, else comparison fails erroneously expect_err('Invalid %(empty%) LHS', meths.set_keymap, '', '', 'rhs', {}) @@ -371,7 +370,7 @@ describe('nvim_[set/del]_keymap', function() expect_err('Invalid %(empty%) LHS', meths.del_keymap, '', '') end) - it('throws errors when given an lhs longer than MAXMAPLEN', function() + it('error if LHS longer than MAXMAPLEN', function() -- assume MAXMAPLEN of 50 chars, as declared in vim.h local MAXMAPLEN = 50 local lhs = '' @@ -421,22 +420,23 @@ describe('nvim_[set/del]_keymap', function() expect_err('Shortname is too long: xnoremap', meths.del_keymap, 'xnoremap', 'lhs') end) - it('throws errors when given unrecognized mode shortnames', function() - expect_err('Invalid mode shortname: ?', + it('error on invalid mode shortname', function() + expect_err('Invalid mode shortname: " "', + meths.set_keymap, ' ', 'lhs', 'rhs', {}) + expect_err('Invalid mode shortname: "m"', + meths.set_keymap, 'm', 'lhs', 'rhs', {}) + expect_err('Invalid mode shortname: "?"', meths.set_keymap, '?', 'lhs', 'rhs', {}) - - expect_err('Invalid mode shortname: y', + expect_err('Invalid mode shortname: "y"', meths.set_keymap, 'y', 'lhs', 'rhs', {}) - - expect_err('Invalid mode shortname: p', + expect_err('Invalid mode shortname: "p"', meths.set_keymap, 'p', 'lhs', 'rhs', {}) - - expect_err('Invalid mode shortname: ?', meths.del_keymap, '?', 'lhs') - expect_err('Invalid mode shortname: y', meths.del_keymap, 'y', 'lhs') - expect_err('Invalid mode shortname: p', meths.del_keymap, 'p', 'lhs') + expect_err('Invalid mode shortname: "?"', meths.del_keymap, '?', 'lhs') + expect_err('Invalid mode shortname: "y"', meths.del_keymap, 'y', 'lhs') + expect_err('Invalid mode shortname: "p"', meths.del_keymap, 'p', 'lhs') end) - it('throws errors when optnames are almost right', function() + it('error on invalid optnames', function() expect_err('Invalid key: silentt', meths.set_keymap, 'n', 'lhs', 'rhs', {silentt = true}) expect_err('Invalid key: sidd', @@ -445,7 +445,7 @@ describe('nvim_[set/del]_keymap', function() meths.set_keymap, 'n', 'lhs', 'rhs', {nowaiT = false}) end) - it('does not recognize <buffer> as an option', function() + it('error on <buffer> option key', function() expect_err('Invalid key: buffer', meths.set_keymap, 'n', 'lhs', 'rhs', {buffer = true}) end) @@ -462,7 +462,7 @@ describe('nvim_[set/del]_keymap', function() end -- Perform tests of basic functionality - it('can set ordinary mappings', function() + it('sets ordinary mappings', function() meths.set_keymap('n', 'lhs', 'rhs', {}) eq(generate_mapargs('n', 'lhs', 'rhs'), get_mapargs('n', 'lhs')) @@ -470,7 +470,7 @@ describe('nvim_[set/del]_keymap', function() eq(generate_mapargs('v', 'lhs', 'rhs'), get_mapargs('v', 'lhs')) end) - it('doesn\'t throw when lhs or rhs have leading/trailing WS', function() + it('does not throw when LHS or RHS have leading/trailing whitespace', function() meths.set_keymap('n', ' lhs', 'rhs', {}) eq(generate_mapargs('n', '<Space><Space><Space>lhs', 'rhs'), get_mapargs('n', ' lhs')) @@ -505,8 +505,8 @@ describe('nvim_[set/del]_keymap', function() end) -- Test some edge cases - it('accepts "!" and " " and "" as synonyms for mapmode-nvo', function() - local nvo_shortnames = {'', ' ', '!'} + it('"!" and empty string are synonyms for mapmode-nvo', function() + local nvo_shortnames = {'', '!'} for _, name in ipairs(nvo_shortnames) do meths.set_keymap(name, 'lhs', 'rhs', {}) meths.del_keymap(name, 'lhs') @@ -653,7 +653,7 @@ describe('nvim_[set/del]_keymap', function() end) -- Perform exhaustive tests of basic functionality - local mapmodes = {'n', 'v', 'x', 's', 'o', '!', 'i', 'l', 'c', 't', ' ', ''} + local mapmodes = {'n', 'v', 'x', 's', 'o', '!', 'i', 'l', 'c', 't', ''} for _, mapmode in ipairs(mapmodes) do it('can set/unset normal mappings in mapmode '..mapmode, function() meths.set_keymap(mapmode, 'lhs', 'rhs', {}) @@ -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, |