Interactive prompts — text, confirm, select, multi-select, textarea
Text, Confirm, Selection, MultiSelect, and Textarea prompts with full keyboard handling, filter-as-you-type, and pagination. Prompts are pure state machines — drive them directly, or let Readline wire them to a real TTY. No external readline dependency.
composer require sugarcraft/sugar-readline
use SugarCraft\Readline\{Key, MultiSelectPrompt, SelectionPrompt, TextPrompt};
// Prompts are immutable state machines: feed input, read the result.
$name = TextPrompt::new('Your name:')
->handleChar('A')->handleChar('d')->handleChar('a')
->submit();
$name->value(); // 'Ada'
$lang = SelectionPrompt::new('Pick a language:', ['PHP', 'Go', 'Rust', 'Python'])
->handleKey(Key::Down)
->handleKey(Key::Enter);
$lang->selectedValue(); // 'Go'
// Multi-select with constraints: Space toggles, Enter submits only when allowed
$tools = MultiSelectPrompt::new('Pick tools:', ['vim', 'git', 'docker', 'php'])
->withMinSelections(1)
->withMaxSelections(3)
->handleKey(Key::Space)->handleKey(Key::Down)->handleKey(Key::Space)
->handleKey(Key::Enter);
$tools->selectedValues(); // ['vim', 'git']
For a real terminal, the same prompts run under Readline, which reads keypresses through a sugar-input driver, repaints view() as you type, and returns the finished prompt. Pass an output stream (the terminal needs non-canonical mode for arrows and chords — the README's "Terminal mode" section carries the stty recipe):
use SugarCraft\Readline\{Readline, TextPrompt};
$prompt = Readline::fromStdin()->run(TextPrompt::new('Your name: '), STDOUT);
$prompt->isSubmitted(); // false on Esc / Ctrl+C / EOF
| Class | Method | Description |
|---|---|---|
| TextPrompt | static new(label) / withDefault() / withHidden() / withCompletions() / withValidator() / withCharLimit() / withHistory() / withAutoSuggest() / withUndoManager() / withDisplayWidth() / withMode() | Single-line input |
| TextPrompt | handleChar(char) / handleKey(key) / insertPastedText(text) / submit() / abort() / value() / isSubmitted() / mode() | Drive the prompt and read the result |
| ConfirmationPrompt | static new(label, defaultValue = false) / withConfirmLabel() / withCancelLabel() / withHint() | Yes / no prompt (Tab or Space toggles, Enter submits) |
| SelectionPrompt | static new(label, choices) / withPageSize() / withFilter() / handleChar() / handleKey() / selectedValue() | Single choice with type-to-filter and pagination (PageUp/PageDown jump pages) |
| MultiSelectPrompt | static new(label, choices) / withMinSelections(n) / withMaxSelections(n) / handleChar() / handleKey() / selectedValues() / canSubmit() | Several choices with min/max enforcement |
| TextareaPrompt | static new(label) / withDefault() / withMaxLines() / handleChar() / handleKey() / insertPastedText() / value() / lines() | Multi-line editor: Enter submits, Shift+Enter/Ctrl+J break lines |
| Readline | fromStdin() / new StreamInputDriver($stream) / onKey(name, handler) / onMouse() / onFocus() / onPaste() / stop() / run(prompt, output) | TTY loop: feeds key events into any prompt and repaints it |
| Mode\EmacsMode · Mode\ViMode | attach via TextPrompt::withMode() | Editing modes; vi normal drives history (j/k), edits (x/D), the unnamed register (yy/dd/diw → p) and undo (u) |
| History\InMemoryHistory | new(maxHistory = 0) / push() / previous() / next() / search(query, fromIndex, direction) / reset() / clear() | Per-process store; collapses adjacent duplicates |
| History\FileHistory | new(path, maxHistory = 0, tempDir = '', deferWrites = false) / push() / flush() / clear() / search() | Cross-process history: 0600 file, escaped one-line entries, sidecar-locked bounded writes, symlinked paths refused |
| UndoManager | push(state) / undo() / redo() / canUndo() / canRedo() | Immutable bounded (512) snapshot stack; attach via withUndoManager() |
| Key | Up, Down, Enter, Space, Escape, CtrlC, … | Canonical key names for handleKey() — raw control bytes normalize to the same language |
VHS-recorded GIFs from the shipped demos. Regenerated automatically on every push that touches the source.