Textobjects and motions for delimited blocks.

Usage

The plugin redefines the i/a textobjects and [/] motions for blocks, adds some new block objects, and makes definition of custom block objects easier.
There is also some support for AutoPairs, but it only works for one-character delimiters and they are deleted in pairs only when using Backspace/Delete from within an empty block.

Built-in objects

They are enhanced in the following ways:

1. Backslashes escape delimiter characters (for blocks that use the same character for opening and closing):

   "word \"wo|rd\" word" is one whole a" object.

2. Strings are properly recognized:

   call("string",| "string") - a"/i" won't match anything between strings.

3. Blocks don't cross the boundaries between code, comments, and strings[1]:

   (call "unbalan|ced) bracket") - a( will match the whole block.
   (call "(balan|ced) brackets") - a( will match the block inside the string.

   [1]: Works only for filetypes recognized by vis and having the notions of comment and/or string.

4. Backward motions - [(, [{ - are exclusive in operator-pending mode.

5. Inner textobjects are linewise-exclusive in visual-line mode.

6. Repeating textobjects in visual mode will select parent blocks - vibibib == v3ib.

7. The visual selection would only be extended to a complete block:

   Given (aaa|__)___bbb, ib will not result in (|_____)____bbb.
   The selection will either extend to a surrounding block that fully contained it or, if there was none, not change at all.
   If extending one end of the selection to the beginning/end of a block is desired, it can be done with the [ and ] motions, which matches the actual intent.

These enhancements apply to the other objects described below, too.

New objects

Any non-alphanumeric character C used as aC or iC will be treated as both opening and closing delimiter of a block:

s/regular |express\/ion/replacement/
After ci/:
s/|/replacement/

These objects assume that a particular delimiter can be simultaneously closing for one block and opening for the next block.
In some contexts this is not desirable, like with * and ** in Markdown.
In such cases these delimiters can be explicitly configured as described in the following section and will be properly handled.

Custom objects

local p = require'pairs'

p.map = {
    {
        ["_"] = {"*", "*", name = "italics"},
        ["*"] = {"**", "**"},
    },
    lua = {
        c = {"--[[", "]]"},
    },
    markdown = {
        i = {"*", "*"},
    },
    html = {
        i = {"<i>", "</i>"},
        c = {"<!--", "-->"},
    },
    latex = {
        i = {"\\emph{", "}"},
    },
}

The map table consists of sub-tables, [1] is global, and string-keyed ones are syntax specific.
Mappings in syntax-specific tables are with higher priority than global mappings of the same key. If a key has more than one syntax-specific mapping, each window will use a definition from the sub-table matching its syntax.
If a name element is added to a global definition, it will be displayed in the :help command output.

Besides characters and strings, LPeg expressions can be used as delimiters[2], too.
The plugin comes with a few such pattern-delimited blocks built in:

• t: XML/HTML tag block
• e: LaTeX environment (syntax: latex)
• b: "any bracket" block (syntax: scheme, clojure, or fennel)

[2]: The surround-add and surround-change operators in vis-surround will then need an extra hint about which particular pair of delimiters to insert. You can specify that by adding a third element to the table, to serve as an "insert template". If any of the delimiters in the template contain a U+FFFD placeholder, it will be replaced by user input. If a prompt element is added it will serve as a custom prompt for the user input.

Motions

[ and ] will work in combination with any block supported by the plugin, e.g. ]/, ]b, ]<, [", [t.

AutoPairs

Automatically inserts the closing delimiter when you insert an opening one.
It's a bit flaky; to disable it,

local p = require'pairs'
p.autopairs = false