Esc

Vt

moduleextensionSource
  • macOS: Everything works on macOS
  • Linux: Everything works on Linux
  • Windows: Everything works on Windows
  • Wasm: Everything works on Wasm
·since 0.36.1

#import "Extensions/Vt";

A sans-IO parser for terminal output: the DEC ANSI state machine behind escape sequences. Feed it bytes in any chunking and it calls you back with printable text, control bytes and CSI, ESC, OSC and DCS sequences. A Vt_Parser owns nothing, so there is nothing to free. Slices in a Vt_Action are borrowed until the callback returns.

Example↗
#import "Extensions/Vt";

count_prints :: (data: *void, action: Vt_Action) {
    if action.kind != .PRINT return;
    count := cast(*int) data;
    count.* += 1;
}

printed := 0;
parser: Vt_Parser;
error := vt_feed(*parser, "hi\x1b[31m!", count_prints, *printed);
assert(error.kind == .NONE && printed == 3);

Procedures#

vt_feedsince 0.36.1Source
(p: *Vt_Parser, bytes: string, callback: Vt_Callback, data: *void = null) -> Vt_Error

Feeds arbitrary chunks; returns the first limit error in this call while consuming all bytes. Example: error := vt_feed(*p, "\x1b[1;2H", on_action, user_data); Do not reenter this parser or change its options from a callback. Invalid options consume nothing.

vt_finishsince 0.36.1Source
(p: *Vt_Parser, callback: Vt_Callback, data: *void = null)

Ends a stream: emits U+FFFD for incomplete UTF-8 and unhooks an active DCS, then resets. Example: vt_finish(*p, on_action, user_data); // options and byte offset are retained

Types#

Vt_Optionsstructsince 0.36.1Source

Limits and modes for a Vt_Parser; set them before the first vt_feed. A sequence that goes over a limit is dropped and reported as .LIMIT.

Vt_Options :: struct {
    max_params: int = 32;
    max_param_value: u32 = 65535;
    max_intermediates: int = 2;
    max_osc_bytes: int = 4096;
    c1: bool;
}
Vt_Error_Kindenumsince 0.36.1Source

Why vt_feed reported a problem.

Vt_Error_Kind :: enum u8 {
    NONE;
    LIMIT;
    OPTIONS;
}
Vt_Errorstructsince 0.36.1Source

The outcome of vt_feed; kind is .NONE on success. message is static and offset counts bytes since the parser started.

Vt_Error :: struct {
    kind: Vt_Error_Kind;
    message: string;
    offset: u64;
}
Vt_Kindenumsince 0.36.1Source

What a Vt_Action reports.

Vt_Kind :: enum u8 {
    PRINT;
    EXECUTE;
    CSI_DISPATCH;
    ESC_DISPATCH;
    OSC_DISPATCH;
    DCS_HOOK;
    DCS_PUT;
    DCS_UNHOOK;
}
Vt_Paramstructsince 0.36.1Source

One numeric parameter of a control sequence.

Vt_Param :: struct {
    value: u32;
    subparam: bool;
}
Vt_Actionstructsince 0.36.1Source

A parsed event passed to a Vt_Callback. Which fields are set depends on kind.

Vt_Action :: struct {
    kind: Vt_Kind;
    code: u32;
    params: [] Vt_Param;
    intermediates: string;
    private_marker: u8;
    osc: [] string;
}
Vt_Stateenumsince 0.36.1Source

The parser's position in the escape-sequence grammar, between bytes.

Vt_State :: enum u8 {
    GROUND;
    ESCAPE;
    ESCAPE_INTERMEDIATE;
    CSI_ENTRY;
    CSI_PARAM;
    CSI_INTERMEDIATE;
    CSI_IGNORE;
    DCS_ENTRY;
    DCS_PARAM;
    DCS_INTERMEDIATE;
    DCS_PASSTHROUGH;
    DCS_IGNORE;
    OSC_STRING;
    SOS_PM_APC_STRING;
}
Vt_Parserstructsince 0.36.1Source

Zero initialization is ready to feed; no allocation or free is needed.

Vt_Parser :: struct {
    options: Vt_Options;
    state: Vt_State;
    offset: u64;
    params: [64] Vt_Param;
    param_count: int;
    intermediates: [8] u8;
    intermediate_count: int;
    private_marker: u8;
    osc_bytes: [4096] u8;
    osc_count: int;
    osc_fields: [64] string;
    osc_field_count: int = 1;
    dropped: bool;
    utf_code: u32;
    utf_min: u32;
    utf_left: int;
}