raxol

---
title: ANSI Sequence Processing
description: How Raxol's Terminal Subsystem Handles ANSI Escape Sequences
date: 2024-07-27 # Updated date
author: Raxol Team
section: terminal
tags: [ansi, terminal, documentation, parser, emulator]
---

# ANSI Sequence Processing

Raxol's terminal subsystem is responsible for interpreting the byte stream received from a connected process or user input, specifically handling ANSI escape sequences that control terminal behavior and appearance. This process is distributed across several key modules rather than being handled by a single monolithic ANSI processor.

## Processing Flow

1. **Input Reception (`Raxol.Terminal.Driver`)**: The `Driver` receives raw bytes from the input source (e.g., a pseudoterminal or stdin). It operates in raw mode (if possible) to capture control sequences directly.
2. **Parsing (`Raxol.Terminal.Parser`)**: The raw byte stream is fed into the `Parser`. This module implements a state machine designed to recognize different types of ANSI sequences (CSI, OSC, ESC, DCS, simple C0/C1 controls).
   - The parser identifies sequence boundaries and parameters.
   - It transitions between states (e.g., `ground`, `escape`, `csi_entry`, `osc_string`) based on the input bytes.
   - Specific state handlers are implemented in `Raxol.Terminal.Parser.States.*`.
3. **Dispatching & Handling**: Once a complete sequence is parsed, the `Parser` dispatches it for handling:
   - **Simple Control Codes (C0/C1) & ESC sequences**: Handled primarily by `Raxol.Terminal.ControlCodes`. This module contains functions for actions like line feeds, carriage returns, tabs, and simpler ESC-based commands.
   - **Control Sequence Introducer (CSI)**: Complex sequences starting with `ESC [` are dispatched based on their final character. For example, cursor movement (`A`, `B`, `C`, `D`, `H`, `f`), erasing (`J`, `K`), and Select Graphic Rendition (SGR - `m`) sequences are typically handled by updating the state within the `Raxol.Terminal.Emulator`. The `Parser` contains CSI dispatch logic to route these.
   - **Device Control String (DCS)**: Sequences like Sixel graphics (`ESC P ... ESC \`) are routed to specialized handlers, such as `Raxol.Terminal.ANSI.SixelGraphics`, which manages its own stateful parsing for the specific protocol.
   - **Operating System Command (OSC)**: Used for things like setting the window title or hyperlink notifications. Handled by the `Emulator` or specific OSC handlers.
4. **State Management (`Raxol.Terminal.Emulator`)**: This core module maintains the terminal's state, including:
   - Cursor position and visibility.
   - Current graphic rendition attributes (colors, bold, italic, etc., applied via SGR sequences).
   - Screen buffer contents (managed via `Raxol.Terminal.Buffer`).
   - Scrolling regions (`DECSTBM`).
   - Screen modes (Alternate Screen Buffer, Origin Mode, etc.).
   - Character sets (`Raxol.Terminal.ANSI.Charsets`).
     The `Emulator` provides an API for other parts of the system (like the `Parser` and `ControlCodes` handlers) to query and modify this state based on the processed ANSI sequences.

## Supported Features (Overview)

The processing pipeline supports a wide range of ANSI features, including:

- **Colors**: Standard 16, 256-color palette, and 24-bit True Color (via SGR sequences). Color state is managed by the `Emulator`.
- **Text Attributes**: Bold, italic, underline, reverse, blink, conceal, strikethrough (via SGR sequences). Managed by the `Emulator`.
- **Cursor Control**: Movement (absolute, relative), visibility, shape (`DECSCUSR`). Managed by the `Emulator`.
- **Erasing**: Clearing parts of the screen or lines (`ED`, `EL`). Implemented by modifying the `ScreenBuffer` via the `Emulator`.
- **Screen Modes**: Normal/Alternate Screen Buffer switching, Origin Mode (`DECOM`), Insert/Replace Mode (`IRM`). Managed by the `Emulator`.
- **Scrolling**: Setting scroll regions (`DECSTBM`), scrolling up/down (`SU`, `SD`). Managed by the `Emulator` and `ScreenBuffer`.
- **Character Sets**: Designation and invocation of character sets (e.g., DEC Special Graphics). Handled by `Raxol.Terminal.ANSI.Charsets` and the `Emulator`.
- **Window Manipulation**: Sequences like `DECSLPP` (Set Lines Per Page) or title setting (OSC). Handled by the `Emulator`.
- **Sixel Graphics**: Parsing and state management via `Raxol.Terminal.ANSI.SixelGraphics`, `SixelPalette`, `SixelPatternMap`. Triggered by DCS sequences.
- **Device Status Reports (DSR)**: Responding to requests for cursor position or terminal status. Handled by the `Emulator` and `Driver`.
- **Mouse Reporting**: Enabling/disabling various mouse tracking modes (X10, VT200, UTF-8, SGR). Input events are generated by the `Driver` based on the enabled mode.

## Implementation Notes

- The system aims for compatibility with common terminal emulators like xterm, VT220, etc., but focuses on features relevant for modern TUI applications.
- Parsing is designed to be robust and handle potentially malformed or interleaved sequences.
- State changes triggered by ANSI sequences (e.g., color changes, cursor moves) are reflected in the `ScreenBuffer`, which is then used by the `Renderer` to update the visible terminal display.

(Previous sections on direct ANSI API, configuration, events, and examples have been removed as they are no longer applicable to the refactored architecture.)