package matrix

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

Module TerminfoSource

Typed access to terminfo capabilities.

Terminfo loads entries from the system terminfo database and exposes each capability as a typed token. The cap GADT encodes the return type of every capability so that get is type-safe at compile time.

Terminology.

  • A capability is a named terminal property: a boolean flag, an integer quantity, a fixed escape sequence, or a parameterized escape sequence.
  • An entry is the set of capabilities declared for a terminal type (e.g. xterm-256color).
  • A handle (t) is an immutable, in-memory representation of one entry.

Quick start

  match Terminfo.load () with
  | Error (`Parse_error msg) ->
      prerr_endline ("terminfo parse error: " ^ msg)
  | Error `Not_found -> prerr_endline "no terminfo entry"
  | Ok ti -> (
      Option.iter print_string (Terminfo.get ti Terminfo.Clear_screen);
      (match Terminfo.get ti Terminfo.Cursor_position with
      | Some goto -> print_string (goto (5, 10))
      | None -> ());
      match Terminfo.get ti Terminfo.Has_colors with
      | Some true -> print_endline "colors"
      | _ -> print_endline "monochrome")

Capabilities

Capability tokens

Sourcetype _ cap =
  1. | Auto_left_margin : bool cap
    (*

    Automatic left margins (bw).

    *)
  2. | Auto_right_margin : bool cap
    (*

    Automatic right margins (am).

    *)
  3. | Back_color_erase : bool cap
    (*

    Screen erased with background color (bce).

    *)
  4. | Can_change : bool cap
    (*

    Terminal can redefine existing colors (ccc).

    *)
  5. | Eat_newline_glitch : bool cap
    (*

    Newline ignored after rightmost column (xenl).

    *)
  6. | Has_colors : bool cap
    (*

    Terminal supports colors. Synthesized: true iff the numeric colors capability is present and greater than 0. Always yields Some true or Some false.

    See also Max_colors.

    *)
  7. | Has_meta_key : bool cap
    (*

    Terminal has a meta key (km).

    *)
  8. | Insert_null_glitch : bool cap
    (*

    Insert mode distinguishes nulls (in).

    *)
  9. | Move_insert_mode : bool cap
    (*

    Safe to move while in insert mode (mir).

    *)
  10. | Move_standout_mode : bool cap
    (*

    Safe to move while in standout mode (msgr).

    *)
  11. | Over_strike : bool cap
    (*

    Terminal can overstrike (os).

    *)
  12. | Transparent_underline : bool cap
    (*

    Underline character overstrikes (ul).

    *)
  13. | Xon_xoff : bool cap
    (*

    Terminal uses xon/xoff handshaking (xon).

    *)
  14. | Columns : int cap
    (*

    Number of columns in a line (cols).

    *)
  15. | Lines : int cap
    (*

    Number of lines on screen (lines).

    *)
  16. | Max_colors : int cap
    (*

    Maximum number of colors (colors).

    See also Has_colors.

    *)
  17. | Max_pairs : int cap
    (*

    Maximum number of color pairs (pairs).

    *)
  18. | Max_attributes : int cap
    (*

    Maximum combined attributes (ma).

    *)
  19. | Init_tabs : int cap
    (*

    Initial tab stop spacing (it).

    *)
  20. | Virtual_terminal : int cap
    (*

    Virtual terminal number (vt).

    *)
  21. | Bell : string cap
    (*

    Audible bell (bel).

    *)
  22. | Carriage_return : string cap
    (*

    Carriage return (cr).

    *)
  23. | Clear_screen : string cap
    (*

    Clear screen and home cursor (clear).

    *)
  24. | Clear_to_eol : string cap
    (*

    Clear to end of line (el).

    *)
  25. | Clear_to_eos : string cap
    (*

    Clear to end of screen (ed).

    *)
  26. | Cursor_down : string cap
    (*

    Move cursor down one line (cud1).

    *)
  27. | Cursor_home : string cap
    (*

    Home cursor to upper-left corner (home).

    *)
  28. | Cursor_invisible : string cap
    (*

    Make cursor invisible (civis).

    *)
  29. | Cursor_left : string cap
    (*

    Move cursor left one character (cub1).

    *)
  30. | Cursor_normal : string cap
    (*

    Restore cursor to normal visibility (cnorm).

    *)
  31. | Cursor_right : string cap
    (*

    Move cursor right one character (cuf1).

    *)
  32. | Cursor_up : string cap
    (*

    Move cursor up one line (cuu1).

    *)
  33. | Cursor_visible : string cap
    (*

    Make cursor very visible (cvvis).

    *)
  34. | Delete_character : string cap
    (*

    Delete one character (dch1).

    *)
  35. | Delete_line : string cap
    (*

    Delete one line (dl1).

    *)
  36. | Enter_alt_charset : string cap
    (*

    Start alternate character set (smacs).

    *)
  37. | Enter_bold_mode : string cap
    (*

    Turn on bold (bold).

    *)
  38. | Enter_dim_mode : string cap
    (*

    Turn on dim (dim).

    *)
  39. | Enter_insert_mode : string cap
    (*

    Enter insert mode (smir).

    *)
  40. | Enter_reverse_mode : string cap
    (*

    Turn on reverse video (rev).

    *)
  41. | Enter_standout_mode : string cap
    (*

    Begin standout mode (smso).

    *)
  42. | Enter_underline_mode : string cap
    (*

    Turn on underline (smul).

    *)
  43. | Exit_alt_charset : string cap
    (*

    End alternate character set (rmacs).

    *)
  44. | Exit_attribute_mode : string cap
    (*

    Turn off all attributes (sgr0).

    *)
  45. | Exit_insert_mode : string cap
    (*

    End insert mode (rmir).

    *)
  46. | Exit_standout_mode : string cap
    (*

    End standout mode (rmso).

    *)
  47. | Exit_underline_mode : string cap
    (*

    End underline mode (rmul).

    *)
  48. | Flash_screen : string cap
    (*

    Visible bell (flash).

    *)
  49. | Insert_character : string cap
    (*

    Insert one character (ich1).

    *)
  50. | Insert_line : string cap
    (*

    Insert one line (il1).

    *)
  51. | Keypad_local : string cap
    (*

    Leave keypad transmit mode (rmkx).

    *)
  52. | Keypad_xmit : string cap
    (*

    Enter keypad transmit mode (smkx).

    *)
  53. | Newline : string cap
    (*

    Newline, behaves like carriage return followed by line feed (nel).

    *)
  54. | Reset_1string : string cap
    (*

    Reset string 1 (rs1).

    *)
  55. | Reset_2string : string cap
    (*

    Reset string 2 (rs2).

    *)
  56. | Restore_cursor : string cap
    (*

    Restore saved cursor position (rc).

    *)
  57. | Save_cursor : string cap
    (*

    Save cursor position (sc).

    *)
  58. | Scroll_forward : string cap
    (*

    Scroll forward one line (ind).

    *)
  59. | Scroll_reverse : string cap
    (*

    Scroll reverse one line (ri).

    *)
  60. | Tab : string cap
    (*

    Tab character (ht).

    *)
  61. | Column_address : (int -> string) cap
    (*

    Column_address: move cursor to column n (hpa).

    *)
  62. | Cursor_position : ((int * int) -> string) cap
    (*

    Cursor_position: move cursor to (row, col) (cup). The terminfo %-expression applies coordinate transformations (e.g. %i for 1-based indexing).

    *)
  63. | Delete_chars : (int -> string) cap
    (*

    Delete_chars: delete n characters (dch).

    *)
  64. | Delete_lines : (int -> string) cap
    (*

    Delete_lines: delete n lines (dl).

    *)
  65. | Insert_chars : (int -> string) cap
    (*

    Insert_chars: insert n characters (ich).

    *)
  66. | Insert_lines : (int -> string) cap
    (*

    Insert_lines: insert n lines (il).

    *)
  67. | Parm_down_cursor : (int -> string) cap
    (*

    Parm_down_cursor: move cursor down n lines (cud).

    *)
  68. | Parm_left_cursor : (int -> string) cap
    (*

    Parm_left_cursor: move cursor left n characters (cub).

    *)
  69. | Parm_right_cursor : (int -> string) cap
    (*

    Parm_right_cursor: move cursor right n characters (cuf).

    *)
  70. | Parm_up_cursor : (int -> string) cap
    (*

    Parm_up_cursor: move cursor up n lines (cuu).

    *)
  71. | Repeat_char : ((char * int) -> string) cap
    (*

    Repeat_char: repeat character (c, n) times (rep).

    *)
  72. | Row_address : (int -> string) cap
    (*

    Row_address: move cursor to row n (vpa).

    *)
  73. | Set_background : (int -> string) cap
    (*

    Set_background: set background to color index n (setab).

    *)
  74. | Set_foreground : (int -> string) cap
    (*

    Set_foreground: set foreground to color index n (setaf).

    *)

The type for capability tokens.

The phantom type parameter encodes the OCaml type returned by get:

  • bool cap — boolean flags.
  • int cap — numeric quantities.
  • string cap — fixed escape sequences.
  • (… -> string) cap — parameterized escape sequences. The returned function evaluates the terminfo %-expression and allocates a fresh string on each call.

Each constructor maps to a standard terminfo capability whose short name appears in the constructor's documentation.

Entries

Sourcetype t

The type for terminfo entries. A value of this type is an immutable, in-memory handle to a parsed terminfo entry. It can be shared freely across threads.

Sourceval load : ?term:string -> unit -> (t, [ `Not_found | `Parse_error of string ]) result

load ?term () is the terminfo entry for terminal type term.

term defaults to the value of the TERM environment variable.

The search order is /usr/share/terminfo, /lib/terminfo, /etc/terminfo, and $HOME/.terminfo (when present). The entry is parsed eagerly; each call creates a fresh, independent handle.

Errors with `Not_found if no entry is found and `Parse_error msg if the file cannot be decoded.

Raises Sys_error if the entry exists but cannot be read.

Lookup

Sourceval get : t -> 'a cap -> 'a option

get ti cap is the value of cap in ti, if declared.

For parameterized capabilities the returned function evaluates the terminfo %-expression and allocates a fresh string on each call. The function never mutates ti.

Note. Has_colors is synthesized from Max_colors and always yields Some true or Some false.