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.