diff options
Diffstat (limited to 'runtime/lua/vim/keymap.lua')
| -rw-r--r-- | runtime/lua/vim/keymap.lua | 98 |
1 files changed, 45 insertions, 53 deletions
diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua index ef1c66ea20..bdea95f9ab 100644 --- a/runtime/lua/vim/keymap.lua +++ b/runtime/lua/vim/keymap.lua @@ -1,53 +1,41 @@ local keymap = {} ---- Add a new |mapping|. +--- Adds a new |mapping|. --- Examples: ---- <pre>lua ---- -- Can add mapping to Lua functions ---- vim.keymap.set('n', 'lhs', function() print("real lua function") end) --- ---- -- Can use it to map multiple modes ---- vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true }) +--- ```lua +--- -- Map to a Lua function: +--- vim.keymap.set('n', 'lhs', function() print("real lua function") end) +--- -- Map to multiple modes: +--- vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer = true }) +--- -- Buffer-local mapping: +--- vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 }) +--- -- Expr mapping: +--- vim.keymap.set('i', '<Tab>', function() +--- return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>" +--- end, { expr = true }) +--- -- <Plug> mapping: +--- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)') +--- ``` --- ---- -- Can add mapping for specific buffer ---- vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 }) ---- ---- -- Expr mappings ---- vim.keymap.set('i', '<Tab>', function() ---- return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>" ---- end, { expr = true }) ---- -- <Plug> mappings ---- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)') ---- </pre> ---- ---- Note that in a mapping like: ---- <pre>lua ---- vim.keymap.set('n', 'asdf', require('jkl').my_fun) ---- </pre> ---- ---- the ``require('jkl')`` gets evaluated during this call in order to access the function. ---- If you want to avoid this cost at startup you can wrap it in a function, for example: ---- <pre>lua ---- vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end) ---- </pre> ---- ----@param mode string|table Same mode short names as |nvim_set_keymap()|. +---@param mode string|table Mode short-name, see |nvim_set_keymap()|. --- Can also be list of modes to create mapping on multiple modes. ---@param lhs string Left-hand side |{lhs}| of the mapping. ----@param rhs string|function Right-hand side |{rhs}| of the mapping. Can also be a Lua function. --- ----@param opts table|nil A table of |:map-arguments|. ---- + Accepts options accepted by the {opts} parameter in |nvim_set_keymap()|, ---- with the following notable differences: ---- - replace_keycodes: Defaults to `true` if "expr" is `true`. ---- - noremap: Always overridden with the inverse of "remap" (see below). ---- + In addition to those options, the table accepts the following keys: ---- - buffer: (number or boolean) Add a mapping to the given buffer. ---- When `0` or `true`, use the current buffer. ---- - remap: (boolean) Make the mapping recursive. ---- This is the inverse of the "noremap" option from |nvim_set_keymap()|. +---@param rhs string|function Right-hand side |{rhs}| of the mapping, can be a Lua function. +--- +---@param opts table|nil Table of |:map-arguments|. +--- - Same as |nvim_set_keymap()| {opts}, except: +--- - "replace_keycodes" defaults to `true` if "expr" is `true`. +--- - "noremap": inverse of "remap" (see below). +--- - Also accepts: +--- - "buffer": (integer|boolean) Creates buffer-local mapping, `0` or `true` +--- for current buffer. +--- - "remap": (boolean) Make the mapping recursive. Inverse of "noremap". --- Defaults to `false`. ---@see |nvim_set_keymap()| +---@see |maparg()| +---@see |mapcheck()| +---@see |mapset()| function keymap.set(mode, lhs, rhs, opts) vim.validate({ mode = { mode, { 's', 't' } }, @@ -56,7 +44,9 @@ function keymap.set(mode, lhs, rhs, opts) opts = { opts, 't', true }, }) - opts = vim.deepcopy(opts) or {} + opts = vim.deepcopy(opts or {}) + + ---@cast mode string[] mode = type(mode) == 'string' and { mode } or mode if opts.expr and opts.replace_keycodes ~= false then @@ -69,7 +59,7 @@ function keymap.set(mode, lhs, rhs, opts) else -- remaps behavior is opposite of noremap option. opts.noremap = not opts.remap - opts.remap = nil + opts.remap = nil ---@type boolean? end if type(rhs) == 'function' then @@ -78,8 +68,8 @@ function keymap.set(mode, lhs, rhs, opts) end if opts.buffer then - local bufnr = opts.buffer == true and 0 or opts.buffer - opts.buffer = nil + local bufnr = opts.buffer == true and 0 or opts.buffer --[[@as integer]] + opts.buffer = nil ---@type integer? for _, m in ipairs(mode) do vim.api.nvim_buf_set_keymap(bufnr, m, lhs, rhs, opts) end @@ -93,14 +83,16 @@ end --- Remove an existing mapping. --- Examples: ---- <pre>lua ---- vim.keymap.del('n', 'lhs') --- ---- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 }) ---- </pre> +--- ```lua +--- vim.keymap.del('n', 'lhs') +--- +--- vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 }) +--- ``` +--- ---@param opts table|nil A table of optional arguments: ---- - buffer: (number or boolean) Remove a mapping from the given buffer. ---- When "true" or 0, use the current buffer. +--- - "buffer": (integer|boolean) Remove a mapping from the given buffer. +--- When `0` or `true`, use the current buffer. ---@see |vim.keymap.set()| --- function keymap.del(modes, lhs, opts) @@ -113,9 +105,9 @@ function keymap.del(modes, lhs, opts) opts = opts or {} modes = type(modes) == 'string' and { modes } or modes - local buffer = false + local buffer = false ---@type false|integer if opts.buffer ~= nil then - buffer = opts.buffer == true and 0 or opts.buffer + buffer = opts.buffer == true and 0 or opts.buffer --[[@as integer]] end if buffer == false then |