~xigoi/nvim-manual-pairs

Neovim plugin that rethinks the concept of automatically pairing delimiters
Clarifications in README
Added license and copyright information
Initial implementation

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~xigoi/nvim-manual-pairs
read/write
git@git.sr.ht:~xigoi/nvim-manual-pairs

You can also use your local clone with git send-email.

#nvim-manual-pairs

manual-pairs is a Neovim plugin that rethinks the concept of automatically pairing delimiters.

Conventional auto-pairs plugins are convenient, but also annoying. They make it hard to avoid their behavior if you just want to type something as-is.

What if, instead of having the [ key insert a pair of brackets, we juat had a different mapping for inserting a pair of brackets? The plugin is an implementation of this idea. It also includes a possibility to add mappings for skipping past the nearest occurence of a given delimiter, inspired by the “fly mode” feature of some auto-pairs plugins.

#Comparison to auto-pairs plugins

#Advantages

  • Does not override the behavior of keys that normally insert characters
  • Works flawlessly with characters that are only sometimes used as delimiters, such as <, ', /, |, *, etc.
  • Does not screw up triple-quoted strings
  • Makes it possible to create custom multi-character pairs such as \(•\) in LaTeX, {.•.} in Nim, etc.
  • Works in command (Ex) mode
  • Simple implementation with less than 100 lines of straightforward code in a single file

#Disadvantages

  • Takes some time to get used to
  • Higher usage of modifier keys

#Installation

Use your favorite way to install Neovim plugins. For example, with lazy.nvim:

require("lazy").setup {
  -- ...
  {
    "https://git.sr.ht/~xigoi/nvim-manual-pairs",
    config = function()
      -- ...
    end,
  }
  -- ...
}

#Usage

The plugin does not require (or allow) any setup. It provides functions that can be used to create mappings.

Here is an example configuration that creates mappings for common delimiters using the Alt key:

local manual_pairs = require "manual-pairs"

manual_pairs.map_pair("<a-s-9>", "(", ")")
manual_pairs.map_pair("<a-[>", "[", "]")
manual_pairs.map_pair("<a-s-[>", "{", "}")
manual_pairs.map_pair("<a-s-,>", "<", ">")
manual_pairs.map_pair("<a-'>", "'", "'")
manual_pairs.map_pair("<a-s-'>", '"', '"')
manual_pairs.map_pair("<a-`>", "`", "`")

manual_pairs.map_fly("<a-s-0>", ")")
manual_pairs.map_fly("<a-]>", "]")
manual_pairs.map_fly("<a-s-]>", "}")

manual_pairs.map_cr("<a-cr>")
manual_pairs.map_right("<a-l>")
manual_pairs.map_backspace("<a-bs>")

Note that this setup is based on the common US QWERTY keyboard layout, it may need to be adjusted for other layouts.

#Available functions

The functions create mappings, they are not called when a mepping is used. Therefore, there is no overhead compared to creating the mappings manually.

map_pair(key, left, right)

Creates a mapping that inserts a pair of delimiters and places the cursor between them. Supports multiple-character delimiters. Works in insert mode and command mode.

map_fly(key, right)

Creates a mapping that moves past the nearest occurence of the given delimiter. Supports multiple-character delimiters and works over multiple lines. Works only in insert mode.

map_cr(key)

Creates a mapping that creates an empty line at the cursor position with the appropriate indent as determined by Neovim’s indent functionality. Works only in insert mode.

map_right(key)

Creates a mapping that moves the cursor one character to the right. This can be used as a substitute for the common feature of auto-pairs plugins that skip past a delimiter rather than inserting it if it is the character after the cursor. Works in insert mode and command mode.

map_backspace(key)

Creates a mapping that deletes one character to the left and right of the cursor. Works in insert mode and command mode.

#Contributing

If you have any issues, feature requests or patches, please open a ticket in the ticket tracker or send an e-mail to the mailing list (no SourceHut account required). Both of these are common to all my Neovim plugins.

#Badges

Written by human, not by AI Please don’t upload to GitHub