blah

A minimal, vim-inspired terminal text editor built with Python and curses.

Overview

blah is a lightweight text editor that provides vim-like functionality with a focus on simplicity and extensibility through a plugin system. It's designed for terminal environments and supports Unicode-wide characters, multiple buffers, and a growing collection of plugins.

Features

• Vim-like keybindings: Familiar navigation and editing commands
• Unicode support: Proper handling of wide characters (CJK, etc.)
• Multiple buffers: Switch between open files
• Plugin system: Extensible architecture with various plugins
• Search & replace: Forward/backward search with case options
• Visual mode: Text selection and manipulation
• Undo/redo: Full change history with checkpoints
• External command integration: Filter text through shell commands

Installation

1. Clone this repository:

git clone <repository-url>
cd blah

2. Make the main script executable:

chmod +x blah

3. (Optional) Install optional dependencies for enhanced functionality:

pip install wcwidth  # For better Unicode character width handling

4. Create plugin directories:

mkdir -p ~/.config/blah/plugins
mkdir -p ~/.config/blah/snippets

Usage

Basic Usage

# Open a file
./blah filename.txt

# Open with a new file
./blah

# Open multiple files (use :bn, :bp to switch)
./blah file1.txt file2.txt

Keybindings

Movement

• h, j, k, l - Left, down, up, right
• w, W - Next word (word/space mode)
• b, B - Previous word (word/space mode)
• e, E - End of word
• 0 - Beginning of line
• ^ - First non-space character
• $ - End of line
• gg - Top of file
• G - Bottom of file (or to line number)
• {, } - Previous/next empty line

Modes

• i - Insert mode
• I - Insert at start of line
• a - Append after cursor
• A - Append at end of line
• R - Replace mode
• v - Visual mode
• Esc - Normal mode

Editing

• x - Delete character
• dd - Delete line
• yy - Yank (copy) line
• p - Paste after cursor
• P - Paste before cursor
• u - Undo
• Ctrl+r - Redo (via undo history)

Search

• / - Search forward
• ? - Search backward
• n - Next match
• N - Previous match

Commands

• :w - Save
• :q - Quit
• :wq - Save and quit
• :e filename - Edit file
• :bn, :bp - Next/previous buffer
• :bd - Delete buffer
• !command - Execute shell command and insert output

Plugins

blah includes several built-in plugins that can be placed in ~/.config/blah/plugins/:

Included Plugins

1. autocomplete - Word completion using tmux menus (Ctrl+N)
2. simplesnippets - Text snippets expansion (Tab key)
3. syntaxhl - Syntax highlighting
4. hms - Home/End key improvements
5. autosave - Auto-save functionality
6. clipboard - System clipboard integration
7. gotodefinition - Jump to definitions
8. impmov - Import movement utilities
9. jedi_python_autocomplete - Python autocompletion via Jedi
10. monkeytestr - Testing utilities
11. rndpos - Random position jumping
12. ruff_check - Python linting with Ruff
13. snippets - Advanced snippet management
14. tabtrap - Tab character handling
15. todomojis - Todo tracking with emojis

Using Plugins

Simply copy plugin files to ~/.config/blah/plugins/ and restart blah. Plugins are automatically loaded on startup.

Creating Plugins

Plugins are Python files that can:

• Map new keybindings using editor.map_cmd()
• Access editor state and methods
• Hook into command processing via editor.cmd_handlers

Example plugin structure:

def my_function(editor=editor):
    editor.st_extra("Hello from plugin!")

# Map Ctrl+H to show a message
editor.map_cmd(modes="NV", k=[curses.ascii.ctrl('h')], cb=my_function)

Configuration

Environment Variables

• ESCDELAY - ESC key delay in milliseconds (default: 25)
• HOME - User home directory (for config files)

Directories

• ~/.config/blah/plugins/ - Plugin files
• ~/.config/blah/snippets/ - Text snippets

Snippets

Create text files in ~/.config/blah/snippets/ with the snippet name as the filename. The file content becomes the snippet expansion.

Requirements

• Python 3.6+
• Standard library modules:
  • curses
  • os
  • sys
  • unicodedata

Optional dependencies:

• wcwidth - Enhanced Unicode width calculation
• jedi - Python autocompletion
• ruff - Python linting
• tmux - Required for some plugin features (autocomplete menus)

Performance

• Lazy loading of plugins and modules for fast startup
• Efficient text rendering with Unicode support
• Minimal memory footprint with undo history management

Limitations

• No GUI interface (terminal only)
• Limited syntax highlighting (plugin-dependent)
• Some advanced vim features may not be implemented
• Plugin system requires manual setup

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by vim's modal editing philosophy
• Built with Python's curses library
• Plugin architecture influenced by various text editors
• Unicode handling techniques from the wcwidth project