Module Ansi.ParserSource

Streaming escape sequence parser.

Streaming ANSI escape sequence parser.

Converts byte streams into high-level tokens representing ANSI escape sequences, SGR attributes, and plain text. The parser handles partial input: incomplete escape sequences and UTF-8 multi-byte characters at chunk boundaries are buffered until the next feed call.

Parsing never raises on malformed input. Unrecognized sequences become Unknown controls and invalid UTF-8 is replaced with U+FFFD. Maximum sequence lengths (max_escape_length for CSI, max_osc_length for OSC) prevent unbounded buffering.

Tokens

Sourcetype control =
  1. | CUU of int
    (*

    Cursor Up by n lines.

    *)
  2. | CUD of int
    (*

    Cursor Down by n lines.

    *)
  3. | CUF of int
    (*

    Cursor Forward by n columns.

    *)
  4. | CUB of int
    (*

    Cursor Backward by n columns.

    *)
  5. | CNL of int
    (*

    Cursor Next Line (down n, column 1).

    *)
  6. | CPL of int
    (*

    Cursor Previous Line (up n, column 1).

    *)
  7. | CHA of int
    (*

    Cursor Horizontal Absolute to column n.

    *)
  8. | VPA of int
    (*

    Vertical Position Absolute to row n.

    *)
  9. | CUP of int * int
    (*

    Cursor Position to (row, col).

    *)
  10. | ED of int
    (*

    Erase in Display.

    *)
  11. | EL of int
    (*

    Erase in Line.

    *)
  12. | IL of int
    (*

    Insert n blank Lines.

    *)
  13. | DL of int
    (*

    Delete n Lines.

    *)
  14. | DCH of int
    (*

    Delete n Characters.

    *)
  15. | ICH of int
    (*

    Insert n blank Characters.

    *)
  16. | OSC of int * string
    (*

    Generic OSC with code and payload.

    *)
  17. | Reset
    (*

    RIS — reset to initial state (ESC c).

    *)
  18. | DECSC
    (*

    Save cursor position (ESC 7).

    *)
  19. | DECRC
    (*

    Restore cursor position (ESC 8).

    *)
  20. | Unknown of string
    (*

    Unrecognized sequence, preserved as raw bytes.

    *)

The type for control sequences other than SGR.

Sourcetype sgr_attr = [
  1. | `Reset
  2. | `Bold
  3. | `Dim
  4. | `Italic
  5. | `Underline
  6. | `Double_underline
  7. | `Inverse
  8. | `Hidden
  9. | `Strikethrough
  10. | `Overline
  11. | `Framed
  12. | `Encircled
  13. | `No_bold
  14. | `No_dim
  15. | `No_italic
  16. | `No_underline
  17. | `No_inverse
  18. | `No_hidden
  19. | `No_strikethrough
  20. | `No_overline
  21. | `No_framed
  22. | `No_encircled
  23. | `Fg of Color.t
  24. | `Bg of Color.t
]

The type for SGR (Select Graphic Rendition) attributes. Represents individual style changes from a single SGR sequence. A sequence like ESC [ 1 ; 31 m produces [`Bold; `Fg Red].

Sourcetype token =
  1. | Text of string
    (*

    Plain UTF-8 text between escape sequences. Always contains complete characters.

    *)
  2. | SGR of sgr_attr list
    (*

    SGR command. An empty list is equivalent to [`Reset].

    *)
  3. | Control of control
    (*

    Non-SGR control sequence.

    *)

The type for parsed tokens.

Parsers

Sourcetype t

The type for parsers. Mutable and not thread-safe.

Sourceval create : unit -> t

create () is a fresh parser in the default state.

Sourceval reset : t -> unit

reset p clears internal buffers and returns p to the default state. Discards buffered partial sequences.

Feeding

Sourceval feed : t -> bytes -> off:int -> len:int -> (token -> unit) -> unit

feed p buf ~off ~len f processes len bytes from buf starting at off, calling f for each complete token. Incomplete sequences are buffered until the next call.

Sourceval parse : string -> token list

parse s parses a complete string into tokens. Creates a temporary parser. Not suitable for streaming; use feed.

Inspection

Sourceval has_pending : t -> bool

has_pending p is true iff p has buffered data (incomplete escape sequences or pending UTF-8 bytes).

Sourceval pending : t -> bytes

pending p is a copy of raw input bytes not yet consumed. Escape sequence bodies being accumulated (CSI parameters, OSC payloads) are stored in separate internal buffers and are not included. Use has_pending to avoid allocation when only checking for pending data.