Blink Pairs

Blink Pairs provides rainbow highlighting and matching pair detection.

Requirement: For highlights to work, you must have enabled the new Neovim UI2 core via require('vim._core.ui2').enable({}).

Highlight Options:

• enabled: Boolean to enable rainbow highlighting.
• cmdline: Boolean to enable highlighting in the command line.
• groups: A list of highlight groups for the rainbow effect (e.g., {'BlinkPairsOrange', 'BlinkPairsPurple', 'BlinkPairsBlue'}).
• separate: A list of delimiters whose nesting is counted separately (e.g., {'<'}). Set to true to count every pair separately.
• unmatched_group: The highlight group used for mismatched pairs.
• matchparen: Configuration for highlighting matching pairs under the cursor.
  • enabled: Boolean.
  • cmdline: Boolean.
  • include_surrounding: If true, includes pairs surrounding the cursor, not just the one on top.
  • group: The highlight group for matchparen (e.g., 'BlinkPairsMatchParen').
  • priority: Integer priority for the highlight.

opts = {
  highlights = {
    enabled = true,
    cmdline = true,
    groups = { 'BlinkPairsOrange', 'BlinkPairsPurple', 'BlinkPairsBlue' },
    separate = { '<' },
    unmatched_group = 'BlinkPairsUnmatched',
    matchparen = {
      enabled = true,
      cmdline = false,
      include_surrounding = false,
      group = 'BlinkPairsMatchParen',
      priority = 250,
    },
  },
}

The mappings table in the opts configuration allows you to control auto-pairing behavior and motion-based wrapping.

Key Options:

• enabled: Boolean to enable/disable mappings.
• cmdline: Boolean to enable/disable mappings in the command line.
• disabled_filetypes: A list of filetypes where mappings should be disabled.
• wrap: Configures how to move pairs using motions or Treesitter.
  • ['<C-b>'] = 'motion': Move the closing pair via a motion.
  • ['<C-S-b>'] = 'motion_reverse': Move the opening pair via a motion.
  • Use 'treesitter' or 'treesitter_reverse' to use Treesitter instead of motions.
• pairs: Custom pair definitions (refer to defaults for available keys).

opts = {
  mappings = {
    enabled = true,
    cmdline = true,
    disabled_filetypes = {},
    wrap = {
      ['<C-b>'] = 'motion',
      ['<C-S-b>'] = 'motion_reverse',
    },
    pairs = {},
  },
}

The MatcherDef struct defines the syntax for creating custom matchers. When using the macro, you provide a name followed by a braced block containing various configuration sections. Each section is identified by a name and a colon, followed by its content wrapped in either brackets [] or braces {}.

Supported Sections

Syntax Rules

• Delimiters/Brackets: Must use single characters. Format: "open" -> "close".
• Spans: Use braces and a colon to map a name to a pair. Format: name: { "open" -> "close" }.
• Lists: Sections like line_comment or string use comma-separated values inside brackets.

// Example of the conceptual macro structure defined by MatcherDef
my_matcher! {
    delimiters: ["(" -> ")", "[" -> "]"],
    line_comment: ["//", "#"],
    block_comment: ["/*" -> "*/"],
    inline_span: {
        comment: { "//" -> "\n" }
    }
}

The Match and MatchWithLine structs represent a detected pair or delimiter in the text. They are used to communicate the location and nature of a match to the consumer (e.g., a Lua script or a UI component).

Match Fields

• kind: The Kind of the match (e.g., Opening, Closing, or NonPair).
• token: The static Token definition associated with this match.
• col: The column position of the match.
• depth: The nesting depth of the match (if applicable).
• pair_depth: The depth specific to this particular pair, ignoring depth contributed by other types of pairs.

MatchWithLine Fields

MatchWithLine is an extension of Match that includes a line field, providing the specific line number where the match occurred.

Lua Interop

Both types implement IntoLua, meaning they can be converted into Lua tables. When converted to Lua, they follow this structure:

• [1]: The opening token string.
• [2]: The closing token string (if it exists).
• span: (Optional) The span if the token is an InlineSpan or BlockSpan.
• col: The column index.
• line: (Only in MatchWithLine) The line index.
• depth: The nesting depth.
• pair_depth: The pair-specific depth (omitted if depth is None).

The tokenize function processes an iterator of byte slices (lines) and produces an iterator of TokenizedLine tuples. It tracks the parser State across multiple lines, allowing for multi-line constructs like block comments or strings.

Each yielded TokenizedLine contains:

1. Vec<Match>: A list of matches (delimiters, comments, etc.) found on that specific line.
2. (u8, u8): The indentation of the line, represented as (tabs, spaces).
3. State: The parser state at the end of the line, which determines how the next line is processed.

To use this, you must provide an initial State and an implementation of the Matcher trait.

// Example conceptual usage
let lines = vec![b"fn foo<T>" as &[u8], b"{
" as &[u8], b"}" as &[u8]];
let matcher = MyMatcher::new();
let tokenized_lines = tokenize(lines.into_iter(), State::Normal, matcher);

for (matches, indent, next_state) in tokenized_lines {
    // Process matches and indentation
}

The MatchArm struct provides a builder pattern to construct match arms for pattern matching against strings. It handles the generation of the match condition (including lookahead and adjacency checks) and the resulting code body.

Builder Methods

• builder(pattern: String, lookahead: usize): Initializes the builder. adjacent is automatically set to true if the pattern length is greater than 1.
• input_state(input_state: TokenStream2): Sets the required State for this match arm.
• non_adjacent(): Forces the adjacent flag to false, meaning the pattern characters do not need to be strictly next to each other.
• ignore_escaped(): Sets the arm to ignore the escaped status of the token.
• if_condition(if_condition: TokenStream2): Adds an additional boolean condition to the match arm.
• body(body: TokenStream2): Defines the code block to execute when the pattern matches.
• build(): Consumes the builder and returns the generated TokenStream2 code block.

// Conceptual usage of MatchArm builder
let arm = MatchArm::builder("//".to_string(), 3)
    .input_state(quote! { State::Normal })
    .body(quote! { /* code to execute */ })
    .build();