mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-07-16 22:21:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge #10003 from justinmk/api-keymap

Browse Source 
API/nvim_set_keymap: minor cleanup
This commit is contained in:
Justin M. Keyes
2019-05-13 09:03:14 +02:00
committed by GitHub
parent fbf2c414ad 60aaae1c86
commit e882460e52
7 changed files with 139 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -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

59
runtime/doc/api.txt
View File

@@ -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})`
Example: >
call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
<
Is equivalent to,
`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|.

12
src/nvim/api/buffer.c
View File

@@ -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)
{

52
src/nvim/api/private/helpers.c
View File

@@ -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;
}

42
src/nvim/api/vim.c
View File

@@ -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})`
/// 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 (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)
{

57
src/nvim/getchar.c
View File

@@ -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;
}
/*

58
test/functional/api/keymap_spec.lua
View File

@@ -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,