b0o/mapx.nvim

🗺 A better way to create key mappings in Neovim

Mapx.nvim

A Neovim Lua plugin to make mapping and commands more manageable.

Mapx.nvim is a Lua library that mimics Vim's :map and :command family of commands. Its aim is to make configuring key mappings and commands from within Lua more ergonomic.

Without Mapx:

vim.api.nvim_set_keymap("n", "j", "v:count ? 'j' : 'gj'", { noremap = true, expr = true })
vim.api.nvim_set_keymap("n", "k", "v:count ? 'k' : 'gk'", { noremap = true, expr = true })

vim.api.nvim_set_keymap("n", "J", "5j", {})
vim.api.nvim_set_keymap("n", "K", "5k", {})

vim.api.nvim_set_keymap("i", "<Tab>", [[pumvisible() ? "\<C-n>" : "\<Tab>"]], { noremap = true, silent = true, expr = true })
vim.api.nvim_set_keymap("i", "<S-Tab>", [[pumvisible() ? "\<C-p>" : "\<S-Tab>"]], { noremap = true, silent = true, expr = true })

vim.api.nvim_set_keymap("", "<M-/>", ":Commentary<Cr>", { silent = true })

vim.cmd [[command -nargs=0 LspDiag lua vim.lsp.diagnostic.set_loclist()]]

With Mapx:

require'mapx'.setup{ global = true }

nnoremap("j", "v:count ? 'j' : 'gj'", "expr")
nnoremap("k", "v:count ? 'k' : 'gk'", "expr")

nmap("J", "5j")
nmap("K", "5k")

inoremap("<Tab>", [[pumvisible() ? "\<C-n>" : "\<Tab>"]], "silent", "expr")
inoremap("<S-Tab>", [[pumvisible() ? "\<C-p>" : "\<S-Tab>"]], "silent", "expr")

map("<M-/>", ":Commentary<Cr>", "silent")

cmd("LspDiag", function() vim.lsp.diagnostic.set_loclist() end, {nargs = 0})

Features

Create multiple mappings to the same action in one shot:

nnoremap({"<C-f><C-f>", "<C-f>f"}, ":lua require('telescope.builtin').find_files()<Cr>", "silent")

WhichKey Integration

Integrate with which-key.nvim by passing a label as the final argument:

local m = require'mapx'.setup{ global = true, whichkey = true }

nnoremap("gD", "<cmd>lua vim.lsp.buf.declaration()<Cr>", "silent", "LSP: Goto declaration")

-- Also supports setting WhichKey group names
m.nname("<leader>l", "LSP")
nnoremap("<leader>li", ":LspInfo<Cr>",    "LSP: Show LSP information")
nnoremap("<leader>lr", ":LspRestart<Cr>", "LSP: Restart LSP")
nnoremap("<leader>ls", ":LspStart<Cr>",   "LSP: Start LSP")
nnoremap("<leader>lS", ":LspStop<Cr>",    "LSP: Stop LSP")

FileType Mappings

FileType mappings will be applied only to buffers with a matching filetype.

nnoremap("<tab>",   [[:call search('\(\w\+(\w\+)\)', 's')<Cr>]],  "silent", { ft = "man" })
nnoremap("<S-tab>", [[:call search('\(\w\+(\w\+)\)', 'sb')<Cr>]], "silent", { ft = "man" })

Groups

Mappings with common options can be grouped to reduce repetition.

mapx.group("silent", { ft = "man" }, function()
  nnoremap("<tab>",   [[:call search('\(\w\+(\w\+)\)', 's')<Cr>]])
  nnoremap("<S-tab>", [[:call search('\(\w\+(\w\+)\)', 'sb')<Cr>]])
end)

Lua Function Mappings

The {rhs} of a mapping can be a Lua function.

map("<leader>hi", function() print("Hello!") end, "silent")

-- Expression maps work too:
nnoremap("j", function() return vim.v.count > 0 and "j" or "gj" end, "silent", "expr")
nnoremap("k", function() return vim.v.count > 0 and "k" or "gk" end, "silent", "expr")

Buffer Mappings

Mappings can be applied to the current buffer, or to a specific buffer.

-- Use the current buffer
nnoremap("<C-]>", ":call man#get_page_from_cword('horizontal', v:count)<CR>", "silent", "buffer")

-- Use a specific buffer
nnoremap("<C-]>", ":call man#get_page_from_cword('horizontal', v:count)<CR>", "silent", {
  buffer = vim.api.nvim_win_get_buf(myWindowVariable)
})

Map Options

There are various ways to specify map options:

-- Lua tables
nnoremap ("j", "v:count ? 'j' : 'gj'", { silent = true, expr = true })

-- Multiple Lua tables
nnoremap ("j", "v:count ? 'j' : 'gj'", { silent = true }, { expr = true })

-- Mapx's exported convenience variables
nnoremap ("j", "v:count ? 'j' : 'gj'", mapx.silent, mapx.expr)

-- Strings
nnoremap ("j", "v:count ? 'j' : 'gj'", "silent", "expr")

-- Vim-style strings
nnoremap ("j", "v:count ? 'j' : 'gj'", "<silent>", "<expr>")

Global Functions

Adding the Mapx map functions to the global scope is opt-in.

local mapx = require'mapx'
mapx.nmap("J", "5j")
mapx.nmap("K", "5k")

Commands

Create commands easily with the cmd and cmdbang functions. The cmdbang function only differs from the cmd function in that it creates a function with a bang which overwrites a previously defined function with the same name.

cmd("LspDiag",
  function() vim.lsp.diagnostic.set_loclist() end,
  {nargs = 0})
cmdbang("LspAddFolder",
  function(opt) vim.lsp.buf.add_workspace_folder(opt.arguments[1]) end,
  {nargs = 1, complete = 'file'})
cmdbang("LspRemFolder",
  function(opt) vim.lsp.buf.remove_workspace_folder(opt.arguments[1]) end,
  {nargs = 1, complete = 'file'})

Documentation

Mapx is fully documented. See :help mapx.

Autoconvert your Neovim-style mappings to Mapx

Mapx provides the ability to convert mappings that use Neovim's vim.api.nvim_set_keymap()/vim.api.nvim_buf_set_keymap() functions to the Mapx API.

See the conversion documentation for instructions.

Install

Packer:

use "b0o/mapx.nvim"

Wishlist

Mapx aims to be the most powerful way to configure key mappings. To that end, we'd like to include the following features in future versions:

• Autocommand mappings (a generalization of FileType mappings).

• VimL conversion tool.

• Telescope.nvim integration.

• API for creating user commands.

• API for creating user autocommands.

• Support passing mapping mode in opts.

• Support specifying multiple modes as a string like 'nvt'.

• Support specifying labels on groups which become which-key group names.

• Support progressively building up maps with groups, like:

  mapx.group({ prefix = "<leader>t" }, "LSP", function()
    mapx.group({ prefix = "g" }, "Goto", function()
      nnoremap("d", "<cmd>lua vim.lsp.buf.definition()<Cr>",      "Definition")
      nnoremap("D", "<cmd>lua vim.lsp.buf.declaration()<Cr>",     "Declaration")
      nnoremap("i", "<cmd>lua vim.lsp.buf.implementation()<Cr>",  "Implementation")
      nnoremap("t", "<cmd>lua vim.lsp.buf.type_definition()<Cr>", "Type definition")
      nnoremap("r", "<cmd>lua vim.lsp.buf.references()<Cr>",      "References")
    end)
    mapx.group({ prefix = "w" }, "Workspace", function()
      nnoremap("a", "<cmd>lua vim.lsp.buf.add_workspace_folder()<Cr>",                       "Add folder")
      nnoremap("r", "<cmd>lua vim.lsp.buf.remove_workspace_folder()<Cr>",                    "Rm folder")
      nnoremap("l", "<cmd>lua print(vim.inspect(vim.lsp.buf.list_workspace_folders()))<Cr>", "List folders")
    end)
  end)
  
  -- Would be equivalent to:
  mapx.nname("<leader>l", "LSP")
  mapx.nname("<leader>lg", "LSP-Goto")
  nnoremap ("<leader>lgd", "<cmd>lua vim.lsp.buf.definition()<Cr>",      "LSP-Goto: Definition")
  nnoremap ("<leader>lgD", "<cmd>lua vim.lsp.buf.declaration()<Cr>",     "LSP-Goto: Declaration")
  nnoremap ("<leader>lgi", "<cmd>lua vim.lsp.buf.implementation()<Cr>",  "LSP-Goto: Implementation")
  nnoremap ("<leader>lgt", "<cmd>lua vim.lsp.buf.type_definition()<Cr>", "LSP-Goto: Type definition")
  nnoremap ("<leader>lgr", "<cmd>lua vim.lsp.buf.references()<Cr>",      "LSP-Goto: References")
  mapx.nname("<leader>lw", "LSP-Workspace")
  nnoremap ("<leader>lwa", "<cmd>lua vim.lsp.buf.add_workspace_folder()<Cr>",                       "LSP-Workspace: Add folder")
  nnoremap ("<leader>lwr", "<cmd>lua vim.lsp.buf.remove_workspace_folder()<Cr>",                    "LSP-Workspace: Rm folder")
  nnoremap ("<leader>lwl", "<cmd>lua print(vim.inspect(vim.lsp.buf.list_workspace_folders()))<Cr>", "LSP-Workspace: List folders")

• Better test coverage

• Support setting default opts in .setup{}

• Benchmarks

• Performance optimization (especially WhichKey integration)

Changelog

01 Nov 2021                                                             v0.2.2
   Added user command support

10 Sep 2021                                                             v0.2.1
   Renamed project to Mapx.nvim
   Added tests
   Added config auto-conversion tool
   Fixed bugs

08 Sep 2021                                                             v0.2.0
   Breaking: Deprecated config.quiet in favor of `setup({global = "force"})`
             or `setup({global = "skip"})`

08 Sep 2021                                                             v0.1.2
   Added support for assigning WhichKey group names
   Allow wrapping string opts in <angle brackets>
   Refactored code
   Bug fixes

04 Sep 2021                                                             v0.1.1
   Added `mapx.group()`
   Added debug logging with `mapx-config-debug`
   Added support for `mapx-opt-filetype` maps
   Added support for Lua functions as a map's `{rhs}`
   Added `mapx-config-quiet`
   Fixed bugs

01 Sep 2021                                                             v0.1.0
   Added `mapx.setup()`
   Added `mapx-whichkey-support`
   Breaking: Deprecated `mapx.globalize()` in favor of `setup({global = true})`

28 Aug 2021                                                             v0.0.2
  Added `mapx.globalize()`

27 Aug 2021                                                             v0.0.1
  Initial Release

License

© 2021 Maddison Hellstrom

Released under the MIT License.

mapx.nvim's Issues

`v:lua` string doesn't work

I have the following code to be converted.

local escape = function(str)
  return vim.api.nvim_replace_termcodes(str, true, true, true)
end

-- HACK
function _G.enhance_align()
  if not packer_plugins["vim-easy-align"].loaded then
    vim.cmd [[packadd vim-easy-align]]
  end
  return escape "<Plug>(EasyAlign)"
end

function M.setup_easy_align()
  vim.api.nvim_set_keymap("n", "ga", "v:lua.enhance_align()", { expr = true })
  vim.api.nvim_set_keymap("x", "ga", "v:lua.enhance_align()", { expr = true })
end

First I tried the following, which doesn't work

  mapx.nmap("ga", "v:lua.enhance_align()", mapx.expr)
  mapx.xmap("ga", "v:lua.enhance_align()", mapx.expr)

Then I make it work using the following

  mapx.nmap("ga", enhance_align, mapx.expr)
  mapx.xmap("ga", enhance_align, mapx.expr)

I am not sure whether this is a bug.

This should be default in nvim

Have you thought about contributing this to nvim ?
I would love to see something like this be default!

Support metatables with `__call` metamethod as rhs

For example, this currently does not work:

require'mapx'.map("<leader>t", setmetatable({}, { __call = function() print"test" end }))

Use the new builtin `nvim_set_keymap()` `callback` option for Lua mappings

This should simplify the code a bit and likely improve performance.

Use the new builtin `nvim_set_keymap()` `desc` option for WhichKey integration

This would dramatically simplify the code by obviating the need for direct coupling with WhichKey.

This can be partially implemented immediately by passing the desc option to nvim_set_keymap(), but the removal of WhichKey-specific code depends on folke/which-key.nvim#253 / folke/which-key.nvim#242.

Packer.nvim recompile error

Prevent packer.nvim from PackerCompile twice.

packer.compile: Complete
packer.nvim: Error running config for mapx.nvim: [string "..."]:0: attempt to call field 'setup' (a boolean value)

It's annoying as I have to delete the plugin/packer_compiled.lua manually.

`v:count` parameter passed to Lua functions causing conflicts

Hello, I really like the idea of this plugin and have something similar implemented in my dotfiles:

local escape_cmd = function(string)
    return string:gsub("'", "\\'"):gsub('"', '\\"'):gsub('\\[', '\\['):gsub('\\]', '\\]'):gsub('<', '<lt>')
end

local bounded_funcs = 'global_bounded_funcs_namespace'
_G[bounded_funcs] = {}
for _, mode in ipairs { '', 'n', 'i', 'v', 't', 's' } do
    _G[mode .. 'noremap'] = function(input, output)
        if type(output) == 'function' then
            local func_name = mode .. '_' .. input
            local func_name_escaped = escape_cmd(func_name)
            _G[bounded_funcs][func_name] = output
            local lua_cmd = ':lua ' .. bounded_funcs .. "['" .. func_name_escaped .. "']()<cr>"
            vim.api.nvim_set_keymap(mode, input, lua_cmd, { noremap = true, silent = true })
        elseif type(output) == 'string' then
            vim.api.nvim_set_keymap(mode, input, output, { noremap = true, silent = true })
        else
            error(mode .. 'noremap' .. ' expects a string or callback', 2)
        end
    end
end

This generates the [nivts]noremap family of functions which have two arguments. The first argument is the input keybinding and the second is either a string which can be a vim command OR it can be lua callback. This allows me to make the following types of mappings:

1. Mappings where the second argument is a string.

nnoremap('<leader>a', ':echo "using lua string"')

2. Mappings where the second argument is an anonymous function.

nnoremap('<leader>b', function() print('using anonymous function') end)

3. Mappings where the second argument is a named function (useful for mapping functions provided by other plugins).

my_func = function() print('using named function') end
nnoremap('<leader>c', my_func)

I tried switching to mapx.nvim, mainly for the which-key.nvim integration and while example 1 and 2 work I'm not able to bind named functions. I know I can wrap the functions in an anonymous function but I'm just wondering why it doesn't work and what mistake I'm making.

Announcements

Important information will be announced here, such as new major versions and breaking changes. Please subscribe to this issue to receive a notification when there's a new announcement.

Execute multiple commands using a dictionary

I'm looking for a quick way to execute vim commands without writing functions, like so.

nnoremap([[keymap]], {Command1, Command2, Command3}, silent)

So if the second function in nnoremap is a table, each command in the table can be called using vim.fn.execute or similar.

Is something like this feasible or available, without using Lua functions?

Proposal: map with multiple modes

map({"i", "s"}, '<c-e>', function() ls.expand_or_jump() end())

Integration with whichkey doesn't work

Hi, when enable the whichkey integration, the following works

  mapx.nmap("]t", '<cmd>lua require("trouble").next({skip_groups = true, jump = true})<CR>')
  mapx.nmap("[t", '<cmd>lua require("trouble").previous({skip_groups = true, jump = true})<CR>')

while the following doesn't

  mapx.nmap("]t", '<cmd>lua require("trouble").next({skip_groups = true, jump = true})<CR>', "Next Trouble")
  mapx.nmap("[t", '<cmd>lua require("trouble").previous({skip_groups = true, jump = true})<CR>', "Previous Trouble" )