package matrix

  1. Overview
  2. Docs
Fast, modern terminal toolkit for OCaml

Install 

dune-project
 Dependency

github.com Readme Changelog Edit opam file Versions (1)

Authors

  1. Thibaut Mattio

Maintainers

  1. Thibaut Mattio

Sources

mosaic-0.1.0.tbz
sha256=9e4e90d17f9b2af1b07071fe425bc2c519c849c4f1d1ab73cde512be2d874849
sha512=06e9c4a741590942e81a27738d0b5c0413fafec8cf3b7dae047ad69f155e7b718aa4223818dc161b7d028efffcfd3365905e264d6fd31d453910ddfa91dcf9b9

doc/matrix.input/Input/index.html

Module InputSource

Terminal input.

This module parses raw terminal byte streams into structured events: keyboard input with modifiers, mouse actions, scroll wheel, bracketed paste, terminal resize, and focus tracking. Capability responses (device attributes, mode reports, cursor position) are separated into their own stream.

The module handles multiple terminal protocols transparently: Kitty keyboard protocol, SGR and URXVT mouse tracking, X10/Normal mouse tracking, bracketed paste, and OSC 52 clipboard responses.

Event model

The event type t covers user-facing input. Capability responses are reported separately as Caps.event values so applications can handle input and capability detection independently.

Parsing

Create a Parser and feed it raw terminal bytes:

  let p = Input.Parser.create () in
  Input.Parser.feed p buf 0 len ~now ~on_event:handle_event
    ~on_caps:handle_caps

Escape sequences may arrive fragmented across reads; the parser buffers partial sequences until they complete or time out. Ambiguous sequences (lone Escape vs. Alt+key) use a 50ms timeout; clearly incomplete sequences (CSI, OSC) use 100ms. Call Parser.drain after Parser.deadline to emit pending events.

Warning. The parser is not thread-safe; use one instance per input source.

Key bindings

Keymap maps key combinations to application commands:

  let km =
    Input.Keymap.empty
    |> Input.Keymap.add_char ~ctrl:true 'q' `Quit
    |> Input.Keymap.add Input.Key.Enter `Submit
  in
  match Input.Keymap.find km event with
  | Some `Quit -> exit 0
  | Some `Submit -> submit ()
  | None -> ()

Keys and modifiers

Sourcemodule Key : sig ... end

Keyboard keys.

Mouse

Sourcemodule Mouse : sig ... end

Mouse buttons and motion events.

Terminal capabilities

Sourcemodule Caps : sig ... end

Terminal capability responses.

Events

Sourcetype t =
  1. | Key of Key.event
    (*

    Keyboard input.

    *)
  2. | Mouse of Mouse.event
    (*

    Mouse button or motion.

    *)
  3. | Scroll of int * int * Mouse.scroll_direction * int * Key.modifier
    (*

    Scroll (x, y, dir, delta, mods) is a scroll wheel event at (x, y) with direction dir, step delta (usually 1), and modifiers mods. Coordinates are 0-based. Normalizes wheel actions across terminal protocols (SGR, URXVT, X10) into a single event.

    *)
  4. | Resize of int * int
    (*

    Resize (width, height) is a terminal resize.

    *)
  5. | Focus
    (*

    Terminal gained focus.

    *)
  6. | Blur
    (*

    Terminal lost focus.

    *)
  7. | Paste of string
    (*

    Paste text is bracketed paste content with ANSI escape sequences stripped. Empty payloads are dropped by the parser.

    *)
  8. | Clipboard of string * string
    (*

    Clipboard (selection, data) is an OSC 52 clipboard response. data is base64-decoded when possible, verbatim otherwise.

    *)
  9. | Osc of int * string
    (*

    Osc (number, payload) is an unhandled OSC sequence. payload is the raw text between introducer and terminator with no sanitization.

    *)

The type for terminal input events.

Predicates and comparisons

Sourceval equal : t -> t -> bool

equal a b is true iff a and b are semantically equal.

For Key events only the key and modifier fields are compared; event_type, associated_text, shifted_key and base_key are ignored. All other variants compare fields structurally.

See equal_full for full structural equality.

Sourceval equal_full : t -> t -> bool

equal_full a b is true iff all fields of a and b are structurally equal. Unlike equal, this compares all fields of Key events including event_type and associated_text.

Formatting

Sourceval pp : Format.formatter -> t -> unit

pp formats events for debugging.

Constructors

Sourceval key : ?modifier:Key.modifier -> ?event_type:Key.event_type -> ?associated_text:string -> ?shifted_key:Uchar.t -> ?base_key:Uchar.t -> Key.t -> t

key k is Key (Key.make k) with the given optional arguments. See Key.make for defaults.

Sourceval char : ?modifier:Key.modifier -> ?event_type:Key.event_type -> ?associated_text:string -> ?shifted_key:Uchar.t -> ?base_key:Uchar.t -> char -> t

char c is Key (Key.of_char c) with the given optional arguments. See Key.of_char for defaults.

Sourceval key_event : ?modifier:Key.modifier -> ?event_type:Key.event_type -> ?associated_text:string -> ?shifted_key:Uchar.t -> ?base_key:Uchar.t -> Key.t -> Key.event

key_event k is Key.make k. Alias useful when you need the raw Key.event without wrapping in t.

Sourceval char_event : ?modifier:Key.modifier -> ?event_type:Key.event_type -> ?associated_text:string -> ?shifted_key:Uchar.t -> ?base_key:Uchar.t -> char -> Key.event

char_event c is Key.of_char c.

Sourceval press : ?modifier:Key.modifier -> ?associated_text:string -> ?shifted_key:Uchar.t -> ?base_key:Uchar.t -> Key.t -> Key.event

press k is Key.make ~event_type:Press k.

Sourceval repeat : ?modifier:Key.modifier -> ?associated_text:string -> ?shifted_key:Uchar.t -> ?base_key:Uchar.t -> Key.t -> Key.event

repeat k is Key.make ~event_type:Repeat k.

Sourceval release : ?modifier:Key.modifier -> ?associated_text:string -> ?shifted_key:Uchar.t -> ?base_key:Uchar.t -> Key.t -> Key.event

release k is Key.make ~event_type:Release k.

Sourceval mouse_press : ?modifier:Key.modifier -> int -> int -> Mouse.button -> t

mouse_press x y button is Mouse (Button_press (x, y, button, modifier)). modifier defaults to Key.no_modifier.

Sourceval mouse_release : ?modifier:Key.modifier -> int -> int -> Mouse.button -> t

mouse_release x y button is Mouse (Button_release (x, y, button, modifier)). modifier defaults to Key.no_modifier.

Sourceval mouse_motion : ?modifier:Key.modifier -> int -> int -> Mouse.button_state -> t

mouse_motion x y state is Mouse (Motion (x, y, state, modifier)). modifier defaults to Key.no_modifier.

Helpers

Sourceval match_ctrl_char : t -> char option

match_ctrl_char e is Some c when e is a Key event with modifier.ctrl = true and the key is an ASCII Char (code point < 0x80). None otherwise.

Sourceval is_scroll : t -> bool

is_scroll e is true iff e is a Scroll event or a Mouse event with a wheel button (Wheel_up, Wheel_down, Wheel_left, Wheel_right).

Sourceval is_drag : t -> bool

is_drag e is true iff e is a Mouse Motion event with at least one primary button pressed.

Sourcemodule Keymap : sig ... end

Key binding maps. See Keymap.

Sourcemodule Parser : sig ... end

Incremental input parser. See Parser.