CandyAnsiInspect
ANSI escape-sequence inspector
Pipe styled output through CandyAnsiInspect and each escape becomes a labeled line. Decodes SGR / CSI / OSC / DCS / APC / SS3, DEC private modes, kitty keyboard protocol, synchronized output, unicode grapheme mode.
Install
composer require sugarcraft/candy-ansi-inspect
Quickstart
$ printf '\e[31mhello\e[0m world\n' | candy-ansi-inspect
ESC[31m SGR foreground red
hello
ESC[0m SGR reset
world
LF C0 LF (line feed)
$ printf '\e]0;new title\e\\' | candy-ansi-inspect
ESC]0;new titleBEL set window title to "new title"
$ printf '\e[?2026h' | candy-ansi-inspect
ESC[?2026h enable synchronized output
What's in the box
SGRForeground / background / underline (58/59) color (16 / 256 / 24-bit truecolor) + bold / italic / underline (all
4:N styles) / blink / reverse / conceal / strike / faint / overline / super- and subscript, plus matching off codes.CSICursor moves, erase (including ECH), scroll region (DECSTBM), insert/delete line/char, tab set + backtab (
g), repeat SGR (b), save/restore cursor (s/u), CR/LF/NEL (E/F), HVP/VPR/HPR positioning, Insert (2~), DSR + device-attributes reports, XTWINOPS, mouse reports (SGR / 1015 / X10), DECSCUSR cursor shape, DECRQM/DECRPM mode query.OSCTitle (0/2), icon (1), palette (4), cwd (7), hyperlink (8, params and URI split), color set/query (10/11/12 with
?), palette reset (104), shell prompt markers (133/1337).DEC privateCursor visibility, autowrap (7), blinking cursor (12), cursor-key application (1), origin mode (6), mouse modes (1000/1002/1003/1005/1006/1015), focused output (2031), alt screen (1047/1048/1049), bracketed paste (2004), sync output (2026).
Kitty keyboardQuery / push / pop progressive enhancement levels, flags via
=…u, layer pop by count.Library mode
Inspector::parse($bytes) yields Segment values, Inspector::report($bytes) renders the CLI's one-shot text, StreamingInspector drives live pipes, ExecRunner::run() reports a PTY child.Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by sequin (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Inspector | parse(bytes) | Parse ANSI bytes into segments |
| Inspector | report(bytes) | One-shot labeled report text — the exact lines the CLI prints |
| Inspector | reportAsJson(bytes) | Machine-readable JSON array of {type, content, description} |
| Inspector | encodeSegmentsJson(segments) | Render any segment list as that JSON array |
| Inspector | sanitizeLabelBytes(text) | Tokenize control bytes for safe display labels |
| Segment | raw() | Abstract — the segment's bytes verbatim (sequences in normalized form) |
| Segment | describe() | Abstract — printable bytes + decoded label, or the text payload verbatim |
| TextSegment | $value | Readonly property — visible text between escape sequences |
| SequenceSegment | $bytes | Readonly property — the escape sequence's raw bytes |
| SequenceSegment | $label | Readonly property — the decoded label (e.g. "SGR reset") |
| StreamingInspector | feed(chunk) | Incremental parse — returns the segments this chunk completed |
| StreamingInspector | finish() | Flush buffered text and report any dangling tail |
| Exec\ExecRunner | run(cmd, emitLine) | Spawn a PTY child and stream its report lines; returns the child's exit status |
Demos.
VHS-recorded GIFs of every example shipped with the library. Regenerated automatically on every push that touches the source.