forked from genewildish/Mainline
David Gwilliam
bfcad4963a
- Add scroll_offset to REPLState (max 50 lines) - Modify _render_repl() to use manual scroll position - Add scroll_output(delta) method for scroll control - Add PageUp/PageDown keyboard support (scroll 10 lines) - Add mouse wheel support via SGR mouse tracking - Update HUD to show scroll percentage (like vim) and position - Reset scroll when new output arrives - Add tests for scroll functionality
133 lines
3.6 KiB
Markdown
133 lines
3.6 KiB
Markdown
# 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 \<name\> \<on|off\>** - Toggle an effect
|
|
- **param \<effect\> \<param\> \<value\>** - 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 <name> <on|off> - Toggle effect
|
|
param <effect> <param> <value> - 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
|
|
```
|
|
|
|
## Scrolling Support
|
|
|
|
The REPL output buffer supports scrolling through command history:
|
|
|
|
**Keyboard Controls:**
|
|
- **PageUp** - Scroll up 10 lines
|
|
- **PageDown** - Scroll down 10 lines
|
|
- **Mouse wheel up** - Scroll up 3 lines
|
|
- **Mouse wheel down** - Scroll down 3 lines
|
|
|
|
**Scroll Features:**
|
|
- **Scroll percentage** shown in HUD (like vim, e.g., "50%")
|
|
- **Scroll position** shown in output line (e.g., "(5/20)")
|
|
- **Auto-reset** - Scroll resets to bottom when new output arrives
|
|
- **Max buffer** - 50 lines (excluding empty lines)
|
|
|
|
## 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
|