Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Iron-E/nvim-cartographer
Create Neovim `:map`pings in Lua with ease!
https://github.com/Iron-E/nvim-cartographer
keybindings keymap lua mapping neovim neovim-configuration neovim-plugin plugin
Last synced: about 2 months ago
JSON representation
Create Neovim `:map`pings in Lua with ease!
- Host: GitHub
- URL: https://github.com/Iron-E/nvim-cartographer
- Owner: Iron-E
- License: other
- Created: 2021-07-06T18:19:58.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2023-06-19T14:56:48.000Z (over 1 year ago)
- Last Synced: 2024-07-31T20:51:28.005Z (4 months ago)
- Topics: keybindings, keymap, lua, mapping, neovim, neovim-configuration, neovim-plugin, plugin
- Language: Lua
- Homepage:
- Size: 36.1 KB
- Stars: 55
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-neovim - Iron-E/nvim-cartographer - a more convenient `:map`ping syntax for Lua environments. (Keybinding / Treesitter Based)
README
# nvim-cartographer
This is a plugin for Neovim which aims to simplify setting and deleting with keybindings / mappings in Lua The target audience is users who are trying to port from an `init.vim` to an `init.lua` following the release of Neovim 0.5.
Here is an example:
```lua
-- This is how you map with the Neovim API
vim.api.nvim_set_keymap('n', 'gr', 'lua vim.lsp.buf.references()', {noremap=true, silent=true})
-- This is how you do that with `nvim-cartographer`
map.n.nore.silent['gr'] = 'lua vim.lsp.buf.references()'
```
## Installation
This plugin can be installed with any plugin manager and used with Neovim 0.7+. I use [packer.nvim](https://github.com/wbthomason/packer.nvim):
```lua
local fn = vim.fn
local install_path = fn.stdpath('data')..'/site/pack/packer/opt/packer.nvim'
if not vim.loop.fs_stat(fn.glob(install_path)) then
os.execute('git clone https://github.com/wbthomason/packer.nvim '..install_path)
end
vim.api.nvim_command 'packadd packer.nvim'
return require('packer').startup {function(use)
use {'wbthomason/packer.nvim', opt=true}
use 'Iron-E/nvim-cartographer'
end}
```
## Usage
To import this plugin, add the following line to the top of any file you wish to use this plugin in:
```lua
local map = require 'cartographer'
```
This plugin implements a builder to make toggling options as easy as possible. You may specify zero to one of `nvim_set_keymap`'s `mode` argument (i.e. you can `map.x` or `map`). It also supports all of the `:h :map-arguments`. `nore` is used to perform a non-recursive `:map`. The ordering of arguments is not important:
```lua
assert(vim.deep_equal(map.n.nore.silent.unique, map.silent.n.unique.nore))
```
Here is an example:
```lua
-- `:map` 'gt' in normal mode to searching for symbol references with the LSP
map.n.nore.silent.unique['gr'] = 'lua vim.lsp.buf.references()'
```
The above is equivalent to the following VimL:
```vim
" This is how you bind `gr` to the builtin LSP symbol-references command
nnoremap gr lua vim.lsp.buf.references()
```
### Buffer-Local Mapping
You can create mappings for specific buffers:
```lua
local nnoremap = require('cartographer').n.nore.silent
-- Only buffer sets map to current buffer
nnoremap.buffer['gr'] = 'lua vim.lsp.buf.references()'
-- You can specify bufnr like
-- This keymap will be set for buffer 3
nnoremap.buffer3['gr'] = 'lua vim.lsp.buf.references()'
```
### Hooks
You can register a function to be called when mapping or unmapping. This function has the same parameters as `nvim_buf_set_keymap`.
```lua
local map = require 'cartographer'
map:hook(function(buffer, mode, lhs, rhs, opts)
-- setup which-key, etc
print(vim.inspect(lhs)..' was mapped to '..vim.inspect(rhs))
end)
map['zxpp'] = vim.lsp.buf.definition
```
The `buffer` parameter will be `nil` when the mapping is not [buffer-local](#buffer-local-mapping).
### Lua Functions
You can also register `local` lua `function`s to mappings, rather than attempt to navigate `v:lua`/`luaeval` bindings:
```lua
local map = require 'cartographer'
local function float_term()
local buffer = vim.api.nvim_create_buf(false, true)
local window = vim.api.nvim_open_win(buffer, true,
{
relative = 'cursor',
height = math.floor(vim.go.lines / 2),
width = math.floor(vim.go.columns / 2),
col = 0,
row = 0,
})
vim.api.nvim_command 'terminal'
end
map.n.nore.silent[''] = float_term
```
### Multiple Modes
You can `:map` to multiple `mode`s if necessary.
```lua
-- Map `gr` to LSP symbol references in 'x' and 'n' modes.
map.n.x.nore.expr[''] = 'pumvisible() ? "\\" : check_backspace() ? "\\" : compe#complete()'
```
### Unmapping
You can `:unmap` as well by setting a `` to `nil` instead of any ``:
```lua
-- `:unmap` 'zfo' in `x` mode
map.x['zfo'] = nil
```