caffee 2.10.2

A simple CUI editor for Caffee.

☕ CAFFEE Terminal Text Editor

A lightweight, modern, and extensible text editor that runs in your terminal.

PyPI total downloads exceeded 10K! 🎉
PyPI total downloads exceeded 5K! 🎉

🇯🇵 日本語 | Technical Specs (JP) | Plugin Dev (JP) | Nuitka Guide | PATH Setup

Official Japanese UI Plugin | Light version(CAFFEETERIA)

---

CAFFEE is a terminal text editor written in Python, designed for a simple, extensible, and efficient editing experience with modern IDE-like features.

Table of Contents

• 💡 Features
• 💻 Installation
• ⌨️ Keybindings
• 🚀 Command Mode
• ⚙️ Configuration
• 🧩 Plugin System
• 📜 Technical Documentation
• 🛠️ Troubleshooting
• 🤝 Contributing
• 📄 License

---

💡 Features

🎨 Modern UI & Navigation

• Multi-Tab Editing - Handle multiple files simultaneously with a visual tab system (Ctrl+S, Ctrl+L, Ctrl+X).
• Breadcrumb Bar - Real-time display of file paths and code symbols (functions/classes) for better context.
• Vim Mode - Optional modal editing support for high-efficiency navigation and text manipulation.
• Relative Line Numbers (Ctrl+U) - Toggle relative line numbers to speed up navigation.
• Nerd Font Integration - High-quality icons with an automated font installation helper.
• Smart Horizontal Scrolling - Nano-style smooth scrolling for long lines.

🚀 Productivity & Editing

• Interactive Search & Replace (Ctrl+W) - VSCode-style interface for finding and replacing text, including "Replace All" (Ctrl+A).
• System Clipboard Sync - Seamless copy-paste synchronization across Windows, macOS, and Linux.
• Predictive Text - Intelligent auto-completion suggestions powered by buffer content.
• Git Integration - View branch names, file status markers (~: modified, +: new), and unified diffs (Ctrl+D).
• Enhanced File Explorer (Ctrl+F) - Browse and manage files with sorting, wildcard search, and full-screen mode.
• Integrated Terminal (Ctrl+N) - Execute shell commands directly from the editor.
• CAFFEINE Macro Language - Automate editor tasks with a dedicated, simple macro language.
• Command Mode (Ctrl+P) - Execute powerful commands like :open, :saveas, :set, and :delcomm.

⚙️ Extensibility & Advanced Support

• Automated Build & Run (Ctrl+B) - Optimized templates and build commands for 20+ programming languages.
• Advanced Syntax Highlighting - Support for Python, JS/TS, C/C++, Go, Rust, Java, Ruby, Swift, and more.
• Plugin System - Extend functionality with custom Python scripts.
• Atomic File Saving - Safe file operations with automatic backup creation.
• Undo/Redo - Comprehensive history management with configurable limits.

---

💻 Installation

Requirements

• Python 3.8+
• Unix-like terminal (Linux, macOS, ChromeOS Linux shell)
• curses library (usually included with Python)

Quick Start

# Install from PyPI
pip install caffee

# Run the editor
caffee

# Or open a specific file
caffee /path/to/file.py

Upgrade

pip install caffee --upgrade

Optional: Speed Up with Nuitka

For significantly faster startup, compile with Nuitka. See the Nuitka Compilation Guide for detailed instructions.

---

⌨️ Keybindings

File Operations

Key	Action
Ctrl+O	Save current file
Ctrl+X	Close current tab / Exit
Ctrl+S	New tab / Start screen
Ctrl+L	Switch to next tab

Editing

Key	Action
Ctrl+Z	Undo
Ctrl+R	Redo
Ctrl+K	Cut (line or selection)
Ctrl+V	Paste (System Clipboard Sync)
Ctrl+C	Copy selection
Ctrl+U	Toggle relative line numbers
Ctrl+Y	Delete current line
Ctrl+/	Toggle comment

Navigation & Search

Key	Action
Ctrl+W	Search (with regex support)
Ctrl+G	Go to line number
Ctrl+Q	Move to beginning of line
Ctrl+E	Move to end of line
Ctrl+A	Select all / Clear selection
Ctrl+6	Set/Unset mark (selection start)

Panels & Tools

Key	Action
Ctrl+F	Toggle file explorer
Ctrl+N	Toggle integrated terminal
Ctrl+U	Toggle relative line numbers
Ctrl+T	Insert template
Ctrl+B	Build/Run current file
Ctrl+D	Show Git diff for the current file
Ctrl+P	Enter Command Mode (or Open Plugin Manager on Start Screen)
Esc	Return to editor from panels

---

🚀 Command Mode

Press Ctrl+P to enter Command Mode, then type a command and press Enter.

Command	Alias	Description
open <file>	o <file>	Open a file in a new tab.
save	w	Save the current file.
saveas <file>		Save the current file with a new name.
copy		Copy the selected range to the system clipboard.
paste		Paste content from the system clipboard.
close	q	Close the current tab.
quit	qa	Exit the editor (prompts for unsaved files).
new		Create a new empty tab.
set <key> <val>		Change a setting (e.g., set tab_width 2).
undo		Undo the last action.
redo		Redo the last undone action.
goto <line>		Jump to the specified line number.
next	tabn	Switch to the next tab.
prev	tabp	Switch to the previous tab.
find <query>		Search for the specified query.
replace <old> <new>		Replace occurrences of <old> with <new>.
expw <width>	explorer_width	Set the file explorer width.
termh <height>	terminal_height	Set the integrated terminal height.
diff		Show a Git diff of the current file in a new tab.
delcomm		Remove all comments from the current buffer.
template <lang>		Insert a template for the specified language.
macro <file>		Execute a CAFFEINE macro file.
csv		Show a formatted table preview of the current CSV buffer.
gemini <prompt>		Ask Google's Gemini AI a question using the buffer as context.
openai <prompt>		Ask OpenAI's ChatGPT a question using the buffer as context.
claude <prompt>		Ask Anthropic's Claude AI a question using the buffer as context.

---

⚙️ Configuration

User settings are stored in ~/.caffee_setting/setting.json. You can edit this file directly or use the interactive settings manager from the start screen (Ctrl+S -> [2] Choice setting).

Example Configuration

{
  "tab_width": 4,
  "history_limit": 50,
  "use_soft_tabs": true,
  "auto_indent": true,
  "backup_count": 5,
  "enable_predictive_text": true,
  
  "templates": {
    "python": "def main():\\n    print(\"Hello, world!\")\\n\\nif __name__ == \"__main__\":\\n    main()",
    "javascript": "function main() {\\n    console.log('Hello, world!');\\n}\\n\\nmain();"
  },

  "start_screen_mode": true,
  "show_explorer_default": true,
  "explorer_show_details": true,
  
  "colors": {
    "header_text": "BLACK",
    "header_bg": "WHITE",
    "keyword": "YELLOW",
    "string": "GREEN",
    "comment": "MAGENTA",
    "number": "BLUE",
    "diff_add": "GREEN",
    "diff_remove": "RED"
  }
}

Key Configuration Options

• auto_indent: Enable/disable automatic indentation.
• enable_predictive_text: Enable/disable auto-completion suggestions.
• explorer_show_details: Show file size and modification date in the explorer.
• displayed_keybindings: Customize which keybindings appear in the footer bar.
• colors: Comprehensive color customization for all UI elements.

AI Configuration

To use the AI commands (:gemini, :openai, :claude), you must configure your API keys. Create a file named ~/.caffee_setting/ai_api.json with the following format:

{
  "gemini_api_key": "your_google_gemini_api_key",
  "openai_api_key": "your_openai_api_key",
  "claude_api_key": "your_anthropic_claude_api_key"
}

---

☕ CAFFEINE Macro Language

CAFFEINE is a simple macro language designed specifically for CAFFEE. Macros allow you to automate repetitive tasks by defining a sequence of editor actions.

Macro Syntax

Macros are stored in .caffeine files. Each line can be a command, a cursor movement, or text insertion.

Command	Description
# comment	Lines starting with # are ignored.
:command	Execute any CAFFEE editor command.
MOVE <y> <x>	Move the cursor to the specified row and column.
INSERT "text"	Insert the specified text at the cursor position.
TYPE "text"	Simulate typing text character by character.
WAIT <ms>	Pause execution for the specified number of milliseconds.
COMMAND "cmd"	Alias for executing an editor command.
SET <var> <expr>	Set a variable to the result of an expression.
IF <expr>	Conditional block. Starts with IF, ends with ENDIF.
ELSE	Optional block within an IF statement.
LOOP <count>	Repeat a block of commands for the specified number of times.
ENDLOOP	End of a LOOP block.

Variable Substitution

You can use variables in your macro commands using the {var_name} syntax. For example, INSERT "Iteration {i}" will insert the current value of variable i. Variables are also automatically substituted in editor commands (lines starting with :).

Advanced Macro Example

# Simple loop with variables and arithmetic
SET i 1
LOOP 5
  INSERT "Line {i}\n"
  SET i i + 1
ENDLOOP

# Conditional logic
SET x 10
IF x > 5
  INSERT "x is greater than 5\n"
ELSE
  INSERT "x is 5 or less\n"
ENDIF

Usage

To run a macro, use the :macro <filename> command in Command Mode (Ctrl+P). CAFFEE will look for the file in the current directory or in ~/.caffee_setting/macros/.

---

📜 Technical Documentation

For more in-depth technical information and extension guides, please refer to the following documents (currently in Japanese):

• Technical Specifications (TECHNICAL_ja.md) - Details on architecture, rendering pipeline, and macro engine.
• Plugin Development Guide (PLUGINS_ja.md) - Instructions for creating plugins and API reference.
• Nuitka Compilation Guide - Procedures for standalone binary creation and startup acceleration.

---

🧩 Plugin System

Extend CAFFEE's functionality with custom Python scripts placed in ~/.caffee_setting/plugins/. Use the interactive Plugin Manager (Start Screen -> Ctrl+P) to enable or disable plugins.

Plugin API

Plugins can access the editor's state and functions via an init(editor) entry point, allowing you to:

• Bind custom key combinations.
• Register new syntax highlighting rules.
• Add new build commands.
• Manipulate buffers and the cursor.
• Display custom messages in the status bar.

---

🛠️ Troubleshooting

• Display Issues: If colors or special characters don't render correctly, ensure your terminal supports 256 colors and UTF-8. For environments like iSH, CAFFEE attempts to set a compatible TERM variable automatically.
• File Access: If you encounter errors saving files or creating backups, check the permissions for ~/.caffee_setting/.
• Terminal Not Working: The integrated terminal requires pty support (standard on Linux and macOS).

---

🤝 Contributing / Branching Strategy

Contributions are always welcome! To ensure the stability of the editor and prevent accidental deployments to PyPI, this project uses a standard branching model.

Please do not push directly to the main branch.

• main: The stable, release-ready branch. (Tags created here trigger automatic PyPI deployment).
• develop: The main development and integration branch. All new features and bug fixes should be merged here first for testing.

How to contribute:

1. Fork the repository.
2. Create a new feature branch branching off from develop (e.g., feature/add-new-theme or fix/typo).
3. Make your changes and commit them.
4. Push your branch to your forked repository.
5. Submit a Pull Request (PR) targeting the develop branch of this original repository.

---

📄 License

This project is licensed under the GNU General Public License v3. See the LICENSE file for details.

---

Made with ☕ and Python.