vim-map-side.nvim

Plugin that improves support for Vim's map side (lhs and rhs) in Neovim.

Lua injection

Vim injection

Features

• Syntax highlighting of lhs and rhs thanks to tree-sitter-vim-map-side. Compatible with ^0.1.0
• New predicates with LSP configuration

Requirements

• Neovim >= 0.9.0
• nvim-treesitter
• lua parser: injection to lhs and rhs of keymap functions
• printf parser (optional): for printf() expression
• vim parser: for rhs that starts with : and command nodes of tree-siter-vim-map-side

Install

Installation examples for lazy.nvim and packer.nvim:

Important

This snippet is for neovim >= 0.11.0

{
  "nvim-treesitter/nvim-treesitter",
  lazy = false, -- if using `lazy.nvim`
  branch = 'main',
  -- `run` instead of `build` if using `packer.nvim`
  build = ':TSUpdate',
  -- `requires` instead of `dependencies` if using `packer.nvim`
  dependencies = { "Hdoc1509/vim-map-side.nvim" },
  config = function()
    -- NOTE: register parser before installation
    require("vim-map-side.tree-sitter").setup()

    require("nvim-treesitter").install({
      "lua", -- required
      "printf", -- optional
      "vim", -- required
      "vim_map_side", -- required
    })
  end,
}

Parser installation for previous versions of nvim-treesitter

ensure_install of main branch

Important

This snippet is for neovim >= 0.11.0. See Minit README for some details about possible compatibility for neovim 0.10.

Installation example

Use install module instead:

{
  "nvim-treesitter/nvim-treesitter",
  lazy = false, -- if using `lazy.nvim`
  branch = 'main',
  -- `run` instead of `build` if using `packer.nvim`
  build = ':TSUpdate',
  -- prior or equal to:
  commit = "73adbe597e8350cdf2773e524eb2199841ea2ab6",
  -- posterior or equal to:
  -- commit = "0bb981c87604200df6c8fb81e5a411101bdf93af",
  -- `requires` instead of `dependencies` if using `packer.nvim`
  dependencies = { 'Hdoc1509/vim-map-side.nvim' },
  config = function()
    -- NOTE: register parser before installation
    require("vim-map-side.tree-sitter").setup()

    require("nvim-treesitter.install").install({
      "lua", -- required
      "printf", -- optional
      "vim", -- required
      "vim_map_side", -- required
    })
  end,
}

configs module of old master branch

Important

This snippet is for neovim >= 0.9.0.

Installation example

{
  "nvim-treesitter/nvim-treesitter",
  lazy = false, -- if using `lazy.nvim`
  branch = 'master',
  -- `run` instead of `build` if using `packer.nvim`
  build = ':TSUpdate',
  -- `requires` instead of `dependencies` if using `packer.nvim`
  dependencies = { 'Hdoc1509/vim-map-side.nvim' },
  config = function()
    -- NOTE: register parser before installation
    require("vim-map-side.tree-sitter").setup()

    require("nvim-treesitter.configs").setup({
      ensure_installed = {
        "lua", -- required
        "printf", -- optional
        "vim", -- required
        "vim_map_side", -- required
      }
    })
  end,
}

Default configuration

vim-map-side.tree-sitter setup

Default configuration

---@type VimMapSide.TS.Opts
{
  -- Whether to `generate` files from the grammar before building it.
  from_grammar = nil,
  -- Path to local `tree-sitter-vim-map-side`.
  path = nil,
  -- Remote URL to `tree-sitter-vim-map-side`.
  url = "https://github.com/Hdoc1509/tree-sitter-vim-map-side",
  -- Version or commit of `tree-sitter-vim-map-side`.
  revision = nil,
  -- Branch of `tree-sitter-vim-map-side`.
  branch = "master",
  custom_fns = {
    -- custom functions with same parameters of `vim.keymap.set()`.
    keymap = {},
    -- same functions as `keymap` but without first parameter (`mode`).
    modemap = {},
  },
}

New predicates

is-keymap-fn? predicate

Check if the captured node is a function call that is a keymap function:

• vim.keymap.set()
• vim.api.nvim_set_keymap()
• custom functions defined in custom_fns.keymap of vim-map-side.tree-sitter setup

is-modemap-fn? predicate

Check if the captured node is a function call that is a modemap function defined in custom_fns.modemap of vim-map-side.tree-sitter setup.

These functions have the same parameters of vim.keymap.set() except the first: mode parameter.

LSP configuration

The ts-query-ls module exports an LSP configuration for ts_query_ls server in order to register the custom predicates used by this plugin.

Important

This is only needed if you will use the predicates defined by this plugin in your queries and you have set the valid_predicates setting for ts_query_ls.

---

Note

You can check my config for ts_query_ls for reference.

nvim-lspconfig + neovim < 0.11

Important

Be sure to set vim-map-side.nvim as a dependency

local lspconfig = require("lspconfig")
local vim_map_side = require("vim-map-side.ts-query-ls")

lspconfig.ts_query_ls.setup(vim.tbl_deep_extend("force", {
  -- your settings
}, vim_map_side))

vim.lsp.config + neovim >= 0.11

Important

Be sure to load vim-map-side.nvim before

local vim_map_side = require("vim-map-side.ts-query-ls")

vim.lsp.config(
  "ts_query_ls",
  vim.tbl_deep_extend("force", {
    -- your settings
  }, vim_map_side)
)
vim.lsp.enable("ts_query_ls")

after/lsp/ts_query_ls.lua + neovim >= 0.11

local vim_map_side = require("vim-map-side.ts-query-ls")

return vim.tbl_deep_extend("force", {
  -- your settings
}, vim_map_side)

Important

Be sure to load vim-map-side.nvim before calling vim.lsp.enable()

See LSP config merge

Then, in your init.lua:

vim.lsp.enable("ts_query_ls")

Troubleshooting

Important

Be sure to run :checkhealth vim.treesitter and :checkhealth nvim-treesitter before checking the following errors.

Incompatible ABI version

If you found the following error:

- ERROR Parser "vim_map_side" failed to load
  (path: .../vim_map_side.so): ...: ABI version mismatch for
  .../vim_map_side.so: supported between X and Y, found Z

Note

X and Y are the interval of ABI versions supported by neovim. Z is the ABI version that was used to develop the parser.

1. Install the following tools:

   • Node.js
   • tree-sitter cli

2. Run :TSInstallFromGrammar vim_map_side to re-install the parser with the correct ABI version.

It's also recommended to add the from_grammar option to the setup function of the tree-sitter module in order to avoid the need to run :TSInstallFromGrammar every time nvim-treesitter is updated:

require("vim-map-side.tree-sitter").setup({
  from_grammar = true,
})

Updates

This plugin will follow changes of tree-sitter-vim-map-side:

• queries updates
• grammar updates