forked from Archives/delaytrain.nvim
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
166 lines
5.7 KiB
Markdown
166 lines
5.7 KiB
Markdown
<div align="center">
|
|
<h1>DelayTrain</h1>
|
|
<p><i>Train yourself to stop repeating keys... gently</i></p>
|
|
<p>
|
|
<a href="#how-does-it-work">How does it work?</a>
|
|
• <a href="#installation">Installation</a>
|
|
• <a href="#configuration">Configuration</a>
|
|
• <a href="#commands">Commands</a>
|
|
• <a href="#contributing">Contributing</a>
|
|
</p>
|
|
|
|
<img src="https://user-images.githubusercontent.com/114582891/192774339-4dc2c4a1-b527-4288-bf5a-9342a99003b9.gif"></img>
|
|
</div>
|
|
|
|
## "Stop using arrow keys!" "Stop using hjkl!"
|
|
|
|
If you're familiar with the (neo)vim community you've probably heard this a
|
|
million times. The whole point of vim is to seamlessly navigate where you
|
|
need to go without constantly repeating keypresses. Why press `j` ten times
|
|
when you can press `10j`, or `}`, or search.
|
|
|
|
But if you've been using vim for a while this may be a harder habit to break.
|
|
You try to stop relying on this type of navigation but you only catch
|
|
yourself after the fact. You might chastize yourself and move on but the
|
|
habit stays there.
|
|
|
|
Most recommendations involve disabling these keys altogether, but this only
|
|
increases frustration. Sometimes your next position is directly above and
|
|
the quickest option is to press `k`. This might help in the long run but
|
|
it's incredibly annoying and hard to stick with.
|
|
|
|
That's where DelayTrain comes in.
|
|
|
|
DelayTrain will still let you use these keybindings, but it only punishes
|
|
you when you _keep_ hitting them. If you need to navigate directly below,
|
|
you can still do that. But if you need to navigate 5 lines below using
|
|
repeated keypresses, DelayTrain will gently remind you that there might
|
|
be a better way by stopping the keypress from working for a certain
|
|
amount of time.
|
|
|
|
And DelayTrain doesn't just work for hjkl. Mappings are included to
|
|
prevent repeated arrow key presses and you can configure delaytrain to
|
|
prevent anything else like `w` or `b`.
|
|
|
|
## How does it work?
|
|
|
|
DelayTrain takes two configurable values, `delay_ms` and `grace_period`.
|
|
|
|
When you first hit a configured keypress (like `j`), the `delay_ms` timer
|
|
starts. You are given a `grace_period` of repeated keypresses within the
|
|
`delay_ms` timer before the key stops working. Once the `delay_ms` timer
|
|
ends, everything is reset.
|
|
|
|
### Examples
|
|
|
|
We'll use a few tables to show how this works. Assume the follwing:
|
|
|
|
* `delay_ms = 1000`
|
|
* `grace_period = 2`
|
|
|
|
By default the `grace_period` is 1, but setting it to 2 allows you to
|
|
press the key twice before it stops working.
|
|
|
|
| Keypress | Time | Grace Period | Does it work? |
|
|
| ---------- | ----------- | ------------ | ------------- |
|
|
| `j` | 0ms | 1 | Yes |
|
|
| `j` | 200ms | 2 | Yes |
|
|
| `j` | 500ms | 3 | No |
|
|
| `j` | 1000ms | 1 | Yes |
|
|
|
|
Each keypress starts a dedicated `delay_ms` timer and has a dedicated
|
|
`grace_period`. So if you're trying to navigate down and to the left,
|
|
this still works.
|
|
|
|
| Keypress | Time | Grace Period | Does it work? |
|
|
| ---------- | ----------- | ------------ | ------------- |
|
|
| `j` | 0ms | 1 | Yes |
|
|
| `j` | 200ms | 2 | Yes |
|
|
| `h` | 500ms | 1 | Yes |
|
|
| `j` | 700ms | 3 | No |
|
|
| `h` | 1000ms | 2 | Yes |
|
|
| `j` | 1200ms | 1 | Yes |
|
|
| `h` | 1400ms | 3 | No |
|
|
| `h` | 1500ms | 1 | Yes |
|
|
|
|
|
|
## Installation
|
|
|
|
Install with [vim-plug](https://github.com/junegunn/vim-plug):
|
|
|
|
```vim
|
|
Plug 'ja-ford/delaytrain.nvim'
|
|
```
|
|
|
|
or with [packer](https://github.com/wbthomason/packer.nvim):
|
|
|
|
```lua
|
|
-- Delay repeat execution of certain keys
|
|
use 'ja-ford/delaytrain.nvim'
|
|
```
|
|
|
|
For the default setup (see defaults below), you can simply place the following
|
|
into your `init.lua`:
|
|
|
|
```lua
|
|
require('delaytrain').setup()
|
|
```
|
|
|
|
## Configuration
|
|
|
|
You can configure all DelayTrain settings through the `setup()` function. The
|
|
default DelayTrain mappings are included below:
|
|
|
|
```lua
|
|
require('delaytrain').setup {
|
|
delay_ms = 1000, -- How long repeated usage of a key should be prevented
|
|
grace_period = 1, -- How many repeated keypresses are allowed
|
|
keys = { -- Which keys (in which modes) should be delayed
|
|
['nv'] = {'h', 'j', 'k', 'l'},
|
|
['nvi'] = {'<Left>', '<Down>', '<Up>', '<Right>'},
|
|
},
|
|
}
|
|
```
|
|
|
|
### Mappings
|
|
|
|
The keys option allows you to delay different keypresses in different modes.
|
|
This takes the following KV pair:
|
|
|
|
```lua
|
|
['list_of_applicable_modes'] = {'keys', 'you', 'want', 'delayed'},
|
|
```
|
|
|
|
Modes can be added based on their short-names (ex: normal is 'n', insert is
|
|
'i') and multiple modes can be added to a single keymap.
|
|
|
|
This option ties into a call to `vim.keymap.set()`, so mode short-names and
|
|
key names should match what is possible in that function.
|
|
|
|
### Options
|
|
|
|
Global options can be modified to change delay/grace period settings on the
|
|
fly:
|
|
|
|
* `g:delaytrain_delay_ms`
|
|
* `g:delaytrain_grace_period`
|
|
|
|
## Commands
|
|
|
|
The following commands allow you to turn DelayTrain on and off without
|
|
calling `setup()` again:
|
|
|
|
* `:DelayTrainEnable`
|
|
* `:DelayTrainDisable`
|
|
* `:DelayTrainToggle`
|
|
|
|
By default, DelayTrain is turned on when the `setup()` function is called.
|
|
|
|
## Contributing
|
|
|
|
This has been tested on my personal and work machines using nvim-nightly and
|
|
[Neovide](https://github.com/neovide/neovide). This is a REALLY SMALL plugin
|
|
so while there shouldn't be a lot of issues it's entirely possible I missed
|
|
something. I'm also brand new to plugin development so if you notice anything
|
|
off please feel free to open up an issue or send me a PR!
|