package matrix

  1. Overview
  2. Docs
package matrix
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module AnsiSource

ANSI terminal escape sequences.

Escape sequences are represented as functions (t) that write directly to a writer buffer. Combining sequences creates a new function, not a new string.

For quick one-off output, convert to a string with to_string:

  Ansi.(to_string (cursor_position ~row:10 ~col:5))

For render loops, use emit with a pre-allocated buffer:

  let buf = Bytes.create 65536 in
  let w = Ansi.Writer.make buf in
  Ansi.emit (Ansi.cursor_position ~row:1 ~col:1) w;
  Ansi.emit (Ansi.literal "Hello") w

For hot loops where even closure allocation matters, use sgr_direct or Sgr_state which write directly to the buffer.

Types

Sourcetype writer = Writer.t

The type for byte buffer writers. See Writer.

Sourcetype t = writer -> unit

The type for escape sequences. A function that writes bytes to a writer. Sequences compose by function application.

Sequence combinators

Sourceval empty : t

empty emits nothing.

Sourceval literal : string -> t

literal s emits s verbatim.

Sourceval char : char -> t

char c emits c.

Sourceval concat : t -> t -> t

concat a b emits a then b.

Sourceval seq : t list -> t

seq xs emits the sequences in xs in order.

Sourceval bytes : bytes -> off:int -> len:int -> t

bytes b ~off ~len copies a byte slice to the writer.

Raises Invalid_argument if the slice is out of bounds.

Sourceval utf8 : int -> t

utf8 cp encodes Unicode scalar value cp as UTF-8. Invalid codepoints (negative, > 0x10FFFF, or surrogates 0xD800–0xDFFF) are replaced with U+FFFD.

Output

Sourceval emit : t -> writer -> unit

emit seq w applies seq to w.

Sourceval to_string : t -> string

to_string seq converts seq to a string. Allocates a temporary buffer.

Sourceval to_buffer : t -> Buffer.t -> unit

to_buffer seq buf appends seq to buf. Allocates an intermediate string via to_string.

CSI and SGR primitives

Sourceval esc : string -> t

esc body emits ESC [ body.

Sourceval csi : params:string -> command:char -> t

csi ~params ~command emits ESC [ params command.

Sourceval sgr : int list -> t

sgr codes emits ESC [ codes m. sgr [] emits nothing; use reset or sgr [0] to clear attributes.

Sourceval sgr_direct : ((int -> unit) -> unit) -> writer -> unit

sgr_direct f w emits SGR codes generated by callback f. The callback receives a push function; every call to push code appends that integer to the SGR parameter list. Avoids list allocation.

Sourceval reset : t

reset emits ESC [ 0 m.

Cursor control

Relative movement

Sourceval cursor_up : n:int -> t

cursor_up ~n moves the cursor up n lines. Negative values are clamped to 0.

Sourceval cursor_down : n:int -> t

cursor_down ~n moves the cursor down n lines.

Sourceval cursor_forward : n:int -> t

cursor_forward ~n moves the cursor right n columns.

Sourceval cursor_back : n:int -> t

cursor_back ~n moves the cursor left n columns.

Sourceval cursor_next_line : n:int -> t

cursor_next_line ~n moves down n lines to column 1 (CNL).

Sourceval cursor_previous_line : n:int -> t

cursor_previous_line ~n moves up n lines to column 1 (CPL).

Absolute positioning

Sourceval cursor_horizontal_absolute : int -> t

cursor_horizontal_absolute col moves to 1-based column col. Values < 1 are clamped to 1.

Sourceval cursor_vertical_absolute : int -> t

cursor_vertical_absolute row moves to 1-based row row. Values < 1 are clamped to 1.

Sourceval cursor_position : row:int -> col:int -> t

cursor_position ~row ~col moves to 1-based (row, col).

State

Sourceval cursor_save : t

cursor_save saves cursor position (CSI s). Must be paired with cursor_restore.

Sourceval cursor_restore : t

cursor_restore restores cursor position (CSI u). Behaviour is undefined without a prior cursor_save.

Appearance

Sourcetype cursor_shape = [
  1. | `Default
  2. | `Blinking_block
  3. | `Block
  4. | `Blinking_underline
  5. | `Underline
  6. | `Blinking_bar
  7. | `Bar
]

The type for cursor shapes (DECSCUSR).

Sourceval cursor_style : shape:cursor_shape -> t

cursor_style ~shape sets the cursor shape.

Sourceval cursor_color : r:int -> g:int -> b:int -> t

cursor_color ~r ~g ~b sets the cursor color (OSC 12). Pair with reset_cursor_color or reset_cursor_color_fallback during teardown.

Sourceval reset_cursor_color : t

reset_cursor_color resets the cursor color (OSC 112).

Sourceval reset_cursor_color_fallback : t

reset_cursor_color_fallback resets the cursor color using OSC 12 "default". Fallback for terminals without OSC 112.

Screen control

Sourceval clear : t

clear erases the visible screen (ED 2) without moving the cursor.

Sourceval home : t

home moves the cursor to (1, 1).

Sourceval clear_and_home : t

clear_and_home moves to home then clears the screen.

Sourcetype erase_display_mode = [
  1. | `Below
  2. | `Above
  3. | `All
  4. | `Scrollback
]

The type for erase display modes.

Sourceval erase_display : mode:erase_display_mode -> t

erase_display ~mode erases parts of the screen (ED).

Sourceval erase_below_cursor : t

erase_below_cursor clears from cursor to end of screen (ED 0).

Sourcetype erase_line_mode = [
  1. | `Right
  2. | `Left
  3. | `All
]

The type for erase line modes.

Sourceval erase_line : mode:erase_line_mode -> t

erase_line ~mode erases parts of the current line (EL).

Sourceval insert_lines : n:int -> t

insert_lines ~n inserts n blank lines at the cursor.

Sourceval delete_lines : n:int -> t

delete_lines ~n deletes n lines at the cursor.

Sourceval scroll_up : n:int -> t

scroll_up ~n scrolls the viewport up by n lines (SU).

Sourceval scroll_down : n:int -> t

scroll_down ~n scrolls the viewport down by n lines (SD).

Sourceval set_scrolling_region : top:int -> bottom:int -> t

set_scrolling_region ~top ~bottom restricts scrolling to rows top through bottom. top must be >= 1 and bottom > top.

Raises Invalid_argument if bounds are invalid.

Sourceval reset_scrolling_region : t

reset_scrolling_region resets the scrolling region to the full screen.

Colors and attributes

Sourceval set_foreground : r:int -> g:int -> b:int -> t

set_foreground ~r ~g ~b sets the foreground to truecolor RGB. Components are clamped to [0, 255].

Sourceval set_background : r:int -> g:int -> b:int -> t

set_background ~r ~g ~b sets the background to truecolor RGB.

Sourceval reset_foreground : t

reset_foreground resets the foreground to terminal default (SGR 39).

Sourceval reset_background : t

reset_background resets the background to terminal default (SGR 49).

Terminal properties

Sourceval set_title : title:string -> t

set_title ~title sets the window title (OSC 0).

Sourceval explicit_width : width:int -> text:string -> t

explicit_width ~width ~text renders text as width cells wide (OSC 66). The text payload is emitted verbatim; ensure text does not contain unescaped ST sequences.

Sourceval explicit_width_bytes : width:int -> bytes:bytes -> off:int -> len:int -> t

explicit_width_bytes ~width ~bytes ~off ~len is like explicit_width but writes directly from a byte buffer.

Operating System Commands (OSC)

Sourcetype terminator = [
  1. | `Bel
  2. | `St
]

The type for OSC terminators.

Sourceval osc : ?terminator:terminator -> payload:string -> t

osc ~terminator ~payload emits an OSC sequence. terminator defaults to `St.

hyperlink_start ~params ~url opens a hyperlink. params defaults to "" and holds optional key=value pairs. Must be paired with hyperlink_end.

hyperlink_end closes the current hyperlink.

hyperlink ~params ~url ~text emits a complete linked text segment.

Terminal modes

Sourcetype mode =
  1. | Cursor_visible
    (*

    DECTCEM 25.

    *)
  2. | Mouse_tracking
    (*

    DECSET 1000 — basic click.

    *)
  3. | Mouse_button_tracking
    (*

    DECSET 1002 — button events.

    *)
  4. | Mouse_motion
    (*

    DECSET 1003 — all motion.

    *)
  5. | Mouse_sgr
    (*

    DECSET 1006 — SGR extended coords.

    *)
  6. | Mouse_sgr_pixel
    (*

    DECSET 1016 — SGR pixel coords.

    *)
  7. | Mouse_x10
    (*

    DECSET 9 — legacy X10.

    *)
  8. | Urxvt_mouse
    (*

    DECSET 1015.

    *)
  9. | Alternate_screen
    (*

    DECSET 1049.

    *)
  10. | Focus_tracking
    (*

    DECSET 1004.

    *)
  11. | Bracketed_paste
    (*

    DECSET 2004.

    *)
  12. | Sync_output
    (*

    DECSET 2026.

    *)
  13. | Unicode
    (*

    DECSET 2027.

    *)
  14. | Color_scheme
    (*

    DECSET 2031.

    *)

The type for DEC private modes.

Sourceval enable : mode -> t

enable m emits the DECSET sequence for m.

Sourceval disable : mode -> t

disable m emits the DECRST sequence for m.

Keyboard encoding

Sourceval csi_u_on : t

csi_u_on enables CSI-u extended keyboard encoding.

Sourceval csi_u_off : t

csi_u_off disables CSI-u encoding.

Sourceval csi_u_push : flags:int -> t

csi_u_push ~flags pushes Kitty keyboard protocol flags.

Sourceval csi_u_pop : t

csi_u_pop pops the Kitty keyboard protocol state.

Sourceval modify_other_keys_on : t

modify_other_keys_on enables Xterm modifyOtherKeys (level 1).

Sourceval modify_other_keys_off : t

modify_other_keys_off disables modifyOtherKeys.

Device and capability queries

Sourcetype query =
  1. | Cursor_position
    (*

    DSR 6.

    *)
  2. | Pixel_size
    (*

    CSI 14 t.

    *)
  3. | Device_attributes
    (*

    DA1.

    *)
  4. | Tertiary_attributes
    (*

    DA3.

    *)
  5. | Terminal_identity
    (*

    XTVERSION.

    *)
  6. | Device_status
    (*

    DSR 5.

    *)
  7. | Csi_u_support
    (*

    CSI ? u.

    *)
  8. | Kitty_graphics
    (*

    Kitty graphics probe.

    *)
  9. | Sixel_geometry
    (*

    Sixel geometry limits.

    *)
  10. | Explicit_width_support
    (*

    OSC 66 width probe.

    *)
  11. | Scaled_text_support
    (*

    OSC 66 scaled text probe.

    *)
  12. | Color_scheme_query
    (*

    DSR 996.

    *)
  13. | Focus_mode
    (*

    DECRQM 1004.

    *)
  14. | Sgr_pixels_mode
    (*

    DECRQM 1016.

    *)
  15. | Bracketed_paste_mode
    (*

    DECRQM 2004.

    *)
  16. | Sync_mode
    (*

    DECRQM 2026.

    *)
  17. | Unicode_mode
    (*

    DECRQM 2027.

    *)
  18. | Color_scheme_mode
    (*

    DECRQM 2031.

    *)

The type for terminal queries. The terminal responds asynchronously; parse responses via Parser.

Sourceval query : query -> t

query q emits the query sequence for q.

High-level convenience

Sourceval render : ?hyperlinks_enabled:bool -> (Style.t * string) list -> string

render ~hyperlinks_enabled segs renders styled segments to a string. Emits minimal SGR transitions by tracking terminal state. Closes open hyperlinks and appends a final reset.

hyperlinks_enabled defaults to true; when false, suppresses OSC 8 sequences.

Sourceval parse : string -> Parser.token list

parse s tokenizes s into ANSI tokens. Never raises; malformed sequences become Parser.control.Unknown controls.

Sourceval strip : string -> string

strip s removes all ANSI escape sequences from s, returning plain text only.

Sub-modules

Sourcemodule Writer : sig ... end

Byte buffer writers.

Sourcemodule Color : sig ... end

Terminal colors.

Sourcemodule Attr : sig ... end

Text attribute flags.

Sourcemodule Style : sig ... end

Terminal text styles.

Sourcemodule Parser : sig ... end

Streaming escape sequence parser.

Sourcemodule Sgr_state : sig ... end

SGR state tracker for render loops.