Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lionc/nest.nvim
https://github.com/lionc/nest.nvim
neovim nvim
Last synced: 17 minutes ago
JSON representation
- Host: GitHub
- URL: https://github.com/lionc/nest.nvim
- Owner: LionC
- License: mit
- Created: 2021-08-14T13:41:56.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-10-28T06:34:52.000Z (about 2 years ago)
- Last Synced: 2024-07-31T20:51:28.221Z (4 months ago)
- Topics: neovim, nvim
- Language: Lua
- Homepage:
- Size: 22.5 KB
- Stars: 228
- Watchers: 4
- Forks: 7
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# nest.nvim
Neovim utility plugin to define keymaps in concise, readable, cascading lists
and trees
- Modular, maintainable pure Lua way to define keymaps
- Written in a single file of ~100 lines
- Supports mapping keys to Lua functions with `expr` support
- Allows grouping keymaps the way you think about them concisely
## Installation
### Using [packer.nvim](https://github.com/wbthomason/packer.nvim)
```lua
use { 'LionC/nest.nvim' }
```
### Using [vim-plug](https://github.com/junegunn/vim-plug)
```viml
Plug 'LionC/nest.nvim'
```
### Using [dein](https://github.com/Shougo/dein.vim)
```viml
call dein#add('LionC/nest.nvim')
```
## Quickstart Guide
The `nest` Lua module exposes an `applyKeymaps` function that can be called any
number of times with a list of (nested) keymaps to be set.
Keymaps will default to global, normal (`n`) mode, `noremap` and `silent`
unless overwritten. Overrides are inherited by nested keymaps.
```lua
local nest = require('nest')
nest.applyKeymaps {
-- Remove silent from ; : mapping, so that : shows up in command mode
{ ';', ':' , options = { silent = false } },
{ ':', ';' },
-- Prefix every nested keymap with
{ '', {
-- Prefix every nested keymap with f (meaning actually f here)
{ 'f', {
{ 'f', 'Telescope find_files' },
-- This will actually map fl
{ 'l', 'Telescope live_grep' },
-- Prefix every nested keymap with g (meaning actually fg here)
{ 'g', {
{ 'b', 'Telescope git_branches' },
-- This will actually map fgc
{ 'c', 'Telescope git_commits' },
{ 's', 'Telescope git_status' },
}},
}},
-- Lua functions can be right side values instead of key sequences
{ 'l', {
{ 'c', vim.lsp.buf.code_actions },
{ 'r', vim.lsp.buf.rename },
{ 's', vim.lsp.buf.signature_help },
{ 'h', vim.lsp.buf.hover },
}},
}},
-- Use insert mode for all nested keymaps
{ mode = 'i', {
{ 'jk', '' },
-- Set option for all nested keymaps
{ options = { expr = true }, {
{ '', 'compe#confirm("")' },
-- This is equivalent to viml `:inoremap compe#complete()`
{ '', 'compe#complete()' },
}},
-- Buffer `true` sets keymaps only for the current buffer
{ '', '' },
{ 'l>', '' },
-- You can also set bindings for a specific buffer
{ 'o>', 'o', buffer = 2 },
}},
}},
-- Keymaps can be defined for multiple modes at once
{ 'H', '^', mode = 'nv' },
}
```
The passed `table` can be understood as a tree, with prefixes and config fields
cascading down to all children. This makes it not only very readable and groupable,
but also eases refactoring and modularization. Because `nest`-keymapConfigs are just
simple Lua values, they can be defined in their own files, passed around, plugged
into different prefixes or options etc.
## Advanced Usage
### Change defaults
You can change the defaults used by `applyKeymaps`:
```lua
local nest = require('nest')
nest.defaults.options = {
noremap = false,
}
```
Defaults start out as
```lua
{
mode = 'n',
prefix = '',
buffer = false,
options = {
noremap = true,
silent = true,
},
}
```
## Reference
### `nest.applyKeymaps`
Expects a `keymapConfig`, which is a table with at least two indexed properties
in one of the following four shapes:
#### Keymap
```lua
{ 'inputsequence', 'outputsequence' }
```
Sets a keymap, mapping the input sequence to the output sequence similiar to
the VimL `:*map` commands.
#### Lua Function Keymap
```lua
{ 'inputsequence', someLuaFunction }
```
Sets a keymap, mapping the input sequence to call the given lua function. Also
works when `expr` is set - just `return` a string from your function (e.g.
`'echo "Hello"'`).
#### Config Subtree
```lua
{ 'inputprefix', keymapConfig }
```
Append the inputprefix to the current prefix and applies the given
`keymapConfig`s with the new prefix.
#### Config List
```lua
{
keymapConfig,
keymapConfig,
keymapConfig
-- ...
}
```
Applies all given `keymapConfig`s.
Each `keymapConfig` can also have any of the following fields, which will cascade
to all containing sub-`keymapConfig`s:
#### `mode`
Sets the Vim mode(s) for keymaps contained in the `keymapConfig`.
Accepts a string with each char representing a mode. The modes follow the Vim
prefixes (`n` for normal, `i` for insert...) **except the special character `_`**, which
stands for the empty mode (`:map `). See `:help map-table` for a reference.
#### `buffer`
Determines whether binding are global or local to a buffer:
- `false` means global
- `true` means current buffer
- A number means that specific buffer (see `:ls` for buffer numbering)
#### `options`
Sets mapping options like ``, `` etc. for keymaps contained in
the `keymapConfig`.
**Note that `options` gets merged** into the options in its context. This means
that you only have to pass the `options` you want to change instead of replacing
the whole object.
Accepts all values `nvim_set_keymap`s `options` parameter accepts. See `:help
nvim_set_keymap`.
### `nest.defaults`
`table` containing the defaults applied to keymaps. Can be modified or overwritten.
Has the same named fields as `keymapConfig`, with an additional field:
#### `prefix`
Sets a `string` prefix to be applied to all keymap inputs.
## Planned Features
See issues and milestones