clvnkhr/macaltkey.nvim

Simplify alt(i.e. option) keybindings for neovim on mac

macaltkey.nvim

A simple plug-in to make setting alt/option keybinds easier.

In some terminals (e.g. iTerm2, wezTerm), it is possible to set a keybind for option-a as follows:

vim.keymap.set("n", "å", {mapping}, {opts})

When you have many of these, it is hard to read the configs. This plugin allows you to write the following:

local mak = require"macaltkey"
mak.keymap.set("n", "<a-a>", {mapping}, {opts}, {opts2})

{opts2} can hold additional options that override those in mak.setup. This is implemented as a dict with a simple wrapper around vim.keymap.set. We implement the following convenience functions

mak.keymap.set
mak.keymap.del
mak.nvim_set_keymap
mak.nvim_buf_set_keymap
mak.nvim_del_keymap
mak.nvim_buf_del_keymap
mak.convert

These commands will transparently pass to the wrapped api function if Mac OS is not detected, or if there are no commands like <a-.> detected.

If you previously wrote

local set = vim.keymap.set

you can now simply write

local set = mak.keymap.set

One can also manually convert the lhs:

local mak = require"macaltkey"
vim.keymap.set("n", mak.convert("<a-a>"), {mapping}, {opts}, {opts2})

If you want some help converting your older keymaps, there is a deconvert function that takes in a converted string and outputs the corresponding <a-.> command:

mak.deconvert("") == "<a-K>"

Default setup

with Lazy.nvim:

require("lazy").setup({
    {
        "clvnkhr/macaltkey.nvim",
        config = function()
            require"macaltkey".setup()
        end
    }
})

Setup options

with Lazy.nvim:

require("lazy").setup({
    {
        "clvnkhr/macaltkey.nvim",

        config = function()
            require"macaltkey".setup({
            language = "en-US", -- American
            -- or "en-GB" British. US is default

            modifier = 'aA',
            -- If this is a single char like 'y', then
            -- will convert <y-x> or <Y-x> (case insensitive) to the character at option-x.
            -- also accepts arbitrary strings, e.g. 'abc' will convert
            -- any of <a-x>, <b-x>, and <c-x> (case sensitive).
            -- Can be passed to the extra opts table of the
            -- convenience functions.

            double_set = false,
            -- If this is true, then will set both the converted
            -- and unconverted keybind, e.g. both <a-a> and å.
            -- Can be passed to the extra opts table of the
            -- convenience functions.
            })

            -- I don't recommend it, but you can put
            -- require"macaltkey".os = "darwin" here to force conversions.
            -- require"macaltkey".dict = {...} here to use a custom dict.

        end
    }
})

It is possible to define your own dicts but non-ascii characters may need special code in mak.convert (see the implementation for "en-GB", which has to treat £ as two characters '\194\163'; contributions welcome for other layouts.)

Acknowledgements

Inspiration from 'Neovim Lua Plugin From Scratch' by TJ DeVries and bashbunni and 'Create Neovim Plugins with Lua' by DevOnDuty

The get_os function is from f-person/auto-dark-mode.nvim.

macaltkey.nvim's Issues

How to integrate with lazy to lazy load based on keymaps?

Is there any way that we can integrate it with Lazy to enable lazy loaded key maps?

In the following example I want <a-a> to load telescope-tabs plugin and then run the function.

{
  "LukasPietzschmann/telescope-tabs",
  dependencies = {"nvim-telescope/telescope.nvim"},
  keys = {
    {  "<a-t>",  function() require("telescope").extensions["telescope-tabs"].list_tabs() end }
  },
  config = true
}