Lumacs/documentation/ARCHITECTURE.md

Lumacs Architecture

Overview

Lumacs is designed as a modular, extensible editor engine inspired by Emacs. It strictly separates the core logic (buffer management, text editing, key bindings) from the user interface (GTK, TUI).

High-Level Diagram

graph TD
    User[User Input] -->|Key/Mouse| UI[UI Frontend]
    UI -->|Key Event| Lua[Lua API]
    Lua -->|Key Sequence| KeyBinding[KeyBindingManager]
    KeyBinding -->|Command Name| CommandSystem[CommandSystem]
    CommandSystem -->|Action| EditorCore[EditorCore]
    EditorCore -->|Modify| Buffer[Buffer]
    EditorCore -->|Modify| Window[Window]
    EditorCore -->|Event| UI
    UI -->|Render| Display[Display]

Core Components

1. EditorCore (editor_core.hpp)

The central hub of the application. It orchestrates all subsystems and holds the state of the editor.

• Responsibilities: Buffer management, Window layout (splits), Global Kill Ring, Event dispatching.
• Dependencies: Buffer, Window, CommandSystem, LuaApi, ThemeManager.

2. Buffer (buffer.hpp)

Represents a text file or scratch space.

• Data: List of strings (lines), file path, modification flag.
• Features: Gap buffer (conceptually), Styling attributes (syntax highlighting), Undo/Redo stack, Mark/Region.

3. Window (window.hpp)

A view into a Buffer.

• Data: Reference to a Buffer, Cursor position, Viewport (scroll offset).
• Logic: Cursor clamping, Scrolling logic.

4. Command System (command_system.hpp)

Registry of executable commands.

• Features: Command registration, Execution by name, Argument parsing, Autocompletion providers.
• Lua Integration: Commands can be defined in C++ or Lua.

5. Lua API (lua_api.hpp)

Bridge to the Lua 5.4 scripting environment.

• Role: init.lua loading, Key binding definitions, Exposing Core API to scripts.

6. Modeline Framework (modeline.hpp)

Generates the status line for each window.

• Design: Modular segments (ModelineSegment) managed by ModelineManager.

User Interface (Frontends)

The UI interacts with the core via the IEditorView interface (ui_interface.hpp).

GTK Frontend (gtk_editor.cpp)

• Uses GTK4 and Cairo for rendering.
• Pango for text layout and font handling.
• Supports window splits using Gtk::Paned.

TUI Frontend (tui_editor.cpp)

• Uses Ncurses.
• Fallback for terminal environments.

Event Loop

1. Input: UI captures input (e.g., Gtk::EventControllerKey).
2. Processing: Input is passed to LuaApi::process_key.
3. Binding: KeyBindingManager resolves the sequence to a command.
4. Execution: CommandSystem executes the command.
5. State Change: Command modifies Buffer or EditorCore state.
6. Notification: EditorCore emits EditorEvent (e.g., BufferModified).
7. Rendering: UI observes the event and requests a redraw.

Design Patterns

• Observer: IEditorView observes EditorCore.
• Factory: UI creation via factory functions.
• Command: Encapsulated actions in CommandSystem.
• Composite: Window layout tree (LayoutNode).