From 3fac583d94c205223cd5af182f2602acc5c269db Mon Sep 17 00:00:00 2001 From: David Gwilliam Date: Sun, 22 Mar 2026 16:42:40 -0700 Subject: [PATCH] Add REPL usage documentation and fix raw mode handling - Fix raw mode enabling to not duplicate with UI border mode - Add REPL_USAGE.md with comprehensive guide - Add examples/repl_demo_terminal.py example script --- REPL_USAGE.md | 116 +++++++++++++++++++++++++++++++++ engine/app/main.py | 3 +- examples/repl_demo_terminal.py | 54 +++++++++++++++ 3 files changed, 172 insertions(+), 1 deletion(-) create mode 100644 REPL_USAGE.md create mode 100644 examples/repl_demo_terminal.py diff --git a/REPL_USAGE.md b/REPL_USAGE.md new file mode 100644 index 0000000..93e930d --- /dev/null +++ b/REPL_USAGE.md @@ -0,0 +1,116 @@ +# REPL Usage Guide + +The REPL (Read-Eval-Print Loop) effect provides an interactive command-line interface for controlling Mainline's pipeline in real-time. + +## How to Access the REPL + +### Method 1: Using CLI Arguments (Recommended) + +Run Mainline with the `repl` effect added to the effects list: + +```bash +# With empty source (for testing) +python mainline.py --pipeline-source empty --pipeline-effects repl + +# With headlines source (requires network) +python mainline.py --pipeline-source headlines --pipeline-effects repl + +# With poetry source +python mainline.py --pipeline-source poetry --pipeline-effects repl +``` + +### Method 2: Using a Preset + +Add a preset to your `~/.config/mainline/presets.toml` or `./presets.toml`: + +```toml +[presets.repl] +description = "Interactive REPL control" +source = "headlines" +display = "terminal" +effects = ["repl"] +viewport_width = 80 +viewport_height = 24 +``` + +Then run: +```bash +python mainline.py --preset repl +``` + +### Method 3: Using Graph Config + +Create a TOML file (e.g., `repl_config.toml`): + +```toml +source = "empty" +display = "terminal" +effects = ["repl"] +``` + +Then run: +```bash +python mainline.py --graph-config repl_config.toml +``` + +## REPL Commands + +Once the REPL is active, you can type commands: + +- **help** - Show available commands +- **status** - Show pipeline status and metrics +- **effects** - List all effects in the pipeline +- **effect \ \** - Toggle an effect +- **param \ \ \** - Set effect parameter +- **pipeline** - Show current pipeline order +- **clear** - Clear output buffer +- **quit/exit** - Show exit message (use Ctrl+C to actually exit) + +## Keyboard Controls + +- **Enter** - Execute command +- **Up/Down arrows** - Navigate command history +- **Backspace** - Delete last character +- **Ctrl+C** - Exit Mainline + +## Visual Features + +The REPL displays: +- **HUD header** (top 3 lines): Shows FPS, frame time, command count, and output buffer size +- **Content area**: Main content from the data source +- **Separator line**: Visual divider +- **REPL area**: Output buffer and input prompt + +## Example Session + +``` +MAINLINE REPL | FPS: 60.0 | 12.5ms +COMMANDS: 3 | [2/3] +OUTPUT: 5 lines +──────────────────────────────────────── +Content from source appears here... +More content... +──────────────────────────────────────── +> help +Available commands: + help - Show this help + status - Show pipeline status + effects - List all effects + effect - Toggle effect + param - Set parameter + pipeline - Show current pipeline order + clear - Clear output buffer + quit - Show exit message +> effects +Pipeline effects: + 1. repl +> effect repl off +Effect 'repl' set to off +``` + +## Notes + +- The REPL effect needs a content source to overlay on (e.g., headlines, poetry, empty) +- The REPL uses terminal display with raw input mode +- Command history is preserved across sessions (up to 50 commands) +- Pipeline mutations (enabling/disabling effects) are handled automatically diff --git a/engine/app/main.py b/engine/app/main.py index 53f4750..4e65759 100644 --- a/engine/app/main.py +++ b/engine/app/main.py @@ -478,7 +478,8 @@ def run_pipeline_mode_direct(): break # Enable raw mode for REPL if present and not already enabled - if repl_effect and hasattr(display, "set_raw_mode"): + # Also enable for UI border mode (already handled above) + if repl_effect and ui_panel is None and hasattr(display, "set_raw_mode"): display.set_raw_mode(True) # Run pipeline loop diff --git a/examples/repl_demo_terminal.py b/examples/repl_demo_terminal.py new file mode 100644 index 0000000..3bc2f61 --- /dev/null +++ b/examples/repl_demo_terminal.py @@ -0,0 +1,54 @@ +#!/usr/bin/env python3 +""" +REPL Demo with Terminal Display - Shows how to use the REPL effect + +Usage: + python examples/repl_demo_terminal.py + +This demonstrates the REPL effect with terminal display and interactive input. +""" + +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent.parent)) + +from engine.effects.plugins import discover_plugins +from engine.pipeline.hybrid_config import PipelineConfig + + +def main(): + """Run REPL demo with terminal display.""" + print("REPL Demo with Terminal Display") + print("=" * 50) + + # Discover plugins + discover_plugins() + + # Create a pipeline with REPL effect + # Using empty source so there's content to overlay on + config = PipelineConfig( + source="empty", + effects=[{"name": "repl", "intensity": 1.0}], + display="terminal", + ) + + pipeline = config.to_pipeline(viewport_width=80, viewport_height=24) + + # Initialize pipeline + if not pipeline.initialize(): + print("Failed to initialize pipeline") + return + + print("\nREPL is now active!") + print("Try typing commands:") + print(" help - Show available commands") + print(" status - Show pipeline status") + print(" effects - List all effects") + print(" pipeline - Show current pipeline order") + print(" clear - Clear output buffer") + print("\nPress Ctrl+C to exit") + + +if __name__ == "__main__": + main()