🍬 CandyAnsi
ANSI escape-sequence parser and state machine
Parse ANSI escape sequences into structured state transitions — SGR attributes, cursor movement, erase operations, and DEC private modes — without coupling to terminal-cell-grid concerns. Used by CandyVt to drive the VT500 state machine.
Install
composer require sugarcraft/candy-ansiQuickstart
use SugarCraft\Ansi\Parser\Parser;
use SugarCraft\Ansi\Parser\CsiHandler;
use SugarCraft\Ansi\Parser\AnsiState;
$state = new AnsiState();
$handler = new MyCsiHandler(); // implements CsiHandler
$parser = new Parser($state, $handler);
$parser->feed("\x1b[1;31m"); // CSI 1;31m → bold + red foreground
$parser->feed("Hello");
$parser->feed("\x1b[0m"); // resetWhat's in the box
CSI handler interfaceComplete set of CSI dispatch methods: CUu/CUD/CUF/CUB/CUP, CHA/VPA, DECSC/DECRC, EL/ED/ECH, SU/SD, IND/RI/NEL, DECSET/DECRST, DECSTBM, TBC, CHT/CBT, and SGR.
Structured state
AnsiState holds current SGR parameters, cursor position, erase mode, DEC mode flags, and scroll region bounds — parseable independently of terminal-cell-grid coupling.Partial-input safeFeed any byte chunk size; the parser maintains internal state and only dispatches when a complete sequence is recognized.
DEC mode supportPrivate marker (0x3C–0x3F) handling for DECSET/DECRST; covers 1049 alt screen, 25 cursor visibility, 1000/1002/1003/1006 mouse, 2004 bracketed paste, 2026 sync output, 7 auto-wrap.
SGR full set16-color, bright, 256-color, truecolor for fg+bg; bold / italic / underline / strikethrough / blink / reverse / dim / hidden toggles; underline styles 4:0–4:5; BCE-aware.
Use it for
- ANSI stream inspection — parse escape sequences into structured events without spawning a terminal.
- Feeding CandyVt — drive the VT500 state machine by passing parsed events to the terminal emulator.
- SGR attribute tracking — maintain current text attributes across a byte stream.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Port of charmbracelet/x/ansi (Go upstream)
API
| Class | Method | Description |
|---|---|---|
| Parser | feed(bytes) | Feed raw ANSI bytes to parser |
| AnsiState | sgr, cursor, eraseMode, decModes | Current parsed state |
| AnsiState | withSgr(array) | New state with updated SGR params |
| AnsiState | withCursor(int, int) | New state with cursor position |
| CsiHandler | printable(string) | Handle printable ASCII character |
| CsiHandler | cuu/cud/cuf/cub(int) | Cursor movement |
| CsiHandler | cup(int, int) | Cursor position (1-indexed) |
| CsiHandler | sgr(array) | Select Graphic Rendition |
| CsiHandler | ed/el(int) | Erase Display / Line |
| CsiHandler | decset/decrst(int, int) | DEC private mode set/reset |
| CsiHandler | decstbm(int, int) | Set top/bottom scroll margins |
| CsiHandler | tbc/cht/cbt(int) | Tab control |
