Overview

Relevant source files

• .github/workflows/test.yml
• README.md
• doc/lexima.txt

Purpose and Scope

lexima.vim is an intelligent text input management plugin for Vim and Neovim that provides rule-based character pairing, text transformation, and context-aware input assistance. This document provides a comprehensive overview of the plugin's architecture, core concepts, and operational model.

The plugin automatically closes pairs like parentheses, brackets, and quotes while maintaining full dot-repeatability and offering extensive customization through a sophisticated rule system. Unlike simple auto-pairing plugins, lexima.vim provides a complete framework for defining context-sensitive input transformations across different Vim modes.

For detailed information about specific subsystems, see Architecture for component interactions, Rule System for rule definition and processing, and Configuration and Usage for setup and customization options.

Core Concept

lexima.vim operates on a rule-based input transformation model. When a user types a character, the plugin:

1. Intercepts the input through Vim mappings
2. Evaluates all applicable rules based on current context
3. Applies the highest-priority matching rule
4. Executes the rule's defined actions (input text, move cursor, delete characters)

This approach enables sophisticated text manipulation while preserving Vim's native undo behavior and dot-repeat functionality.

Sources: doc/lexima.txt43-55 README.md6-10

Key Features

Rule-Based Architecture

The plugin's core strength lies in its flexible rule system where each rule defines:

• Trigger character: The input that activates the rule
• Context pattern: Where the rule applies (using regex with cursor position markers)
• Actions: What happens when the rule fires (text insertion, cursor movement, deletion)
• Scope: Which modes, filetypes, or syntax contexts enable the rule

Dot-Repeatability

Unlike many auto-pairing plugins, lexima.vim maintains full compatibility with Vim's . (dot) repeat command. This is achieved through careful use of insert-mode mappings and avoiding cursor movement keys that break repeat functionality.

Sources: doc/lexima.txt50-51 doc/lexima.txt484-514

Multi-Mode Support

The plugin operates across different Vim modes:

• Insert mode: Primary text input with auto-pairing and smart completion
• Command-line mode: Auto-pairing in Ex commands, search patterns, and expressions

Sources: doc/lexima.txt374-382

Default Rule Categories

Four main categories of built-in rules provide comprehensive text input assistance:

Rule Type	Purpose	Examples
Basic Rules	Character pairing	( → `(
Newline Rules	Smart indentation	`{
Space Rules	Whitespace handling	`{
Endwise Rules	Language keywords	if condition + <CR> → adds end

Sources: doc/lexima.txt68-197 README.md29-109

System Architecture

Component Overview

Input Processing Pipeline

Sources: autoload/lexima.vim autoload/lexima/insmode.vim autoload/lexima/cmdmode.vim

Integration with Vim

Initialization Sequence

Runtime Operation Model

The plugin operates through Vim's expression mapping system (inoremap <expr>), allowing each keypress to be evaluated dynamically:

1. Key Interception: Mapped keys call lexima#expand(char, mode)
2. Context Evaluation: Current buffer state is analyzed using regex patterns
3. Rule Resolution: Matching rules are prioritized and the best one selected
4. Action Execution: The winning rule's actions modify the buffer
5. State Preservation: Changes are recorded for dot-repeat compatibility

Sources: plugin/lexima.vim doc/lexima.txt298-310

Performance Considerations

lexima.vim uses several optimization strategies:

• Sorted Rule Lists: Rules are pre-sorted by priority to minimize evaluation time
• Context Caching: Buffer context analysis is optimized for common patterns
• Lazy Loading: Advanced features like endwise rules are loaded on-demand
• Efficient Mappings: Expression mappings avoid the overhead of function calls where possible

Sources: autoload/lexima/sortedlist.vim doc/lexima.txt596

This architecture provides a robust foundation for intelligent text input while maintaining the performance and integration standards expected of Vim plugins. The modular design allows for extensive customization while keeping the core functionality reliable and efficient.