Module Lwt_term
module Lwt_term: sig..end
Terminal control
This modules allow you to write interactive programs using the
terminal.
with_raw_mode f executes f while the terminal is in ``raw
mode''. Raw mode means that character are returned as the user
type them (otherwise only complete line are returned to the
program).
If the terminal is already in raw mode, it just calls f.
val raw_mode : unit -> bool
Returns wether the terminal is currently in raw mode
val enter_drawing_mode : unit -> unit Lwt.t
Put the terminal into drawing mode
val leave_drawing_mode : unit -> unit Lwt.t
Restore the state of the terminal
val show_cursor : unit -> unit Lwt.t
show_cursor () makes the cursor visible
val hide_cursor : unit -> unit Lwt.t
hide_cursor () makes the cursor invisible
val clear_screen : unit -> unit Lwt.t
clear_screen () clears the entire screen
val clear_line : unit -> unit Lwt.t
clear_line () clears the current line
val goto_beginning_of_line : int -> unit Lwt.t
goto_beginning_of_line n put the cursor at the beginning of
the nth previous line.
- goto_beginning_of_line 0 goes to the beginning of the current line
- goto_beginning_of_line 1 goes to the beginning of the previous line
- ...
Terminal informations ¶
type size = {
lines : int; | |
columns : int; |
}
Terminal sizes:
val size : size React.signal
Size of the terminal.
val columns : int React.signal
Number of columns of the terminal
val lines : int React.signal
Number of lines of the terminal
Keys ¶
val parse_key_raw : Text.t Lwt_stream.t -> Text.t Lwt.t
parse_key_raw st recognize escape sequence in a stream of
unicode character.
It returns either:* either single characters, like "a", "é", ...
- either escape sequences
type key =
| | Key of Text.t | (* | A unicode character or an uninterpreted sequence | *) |
| | Key_up | |||
| | Key_down | |||
| | Key_left | |||
| | Key_right | |||
| | Key_f of int | |||
| | Key_next_page | |||
| | Key_previous_page | |||
| | Key_home | |||
| | Key_end | |||
| | Key_insert | |||
| | Key_delete | |||
| | Key_control of char | (* | A control key | *) |
Type of ``decoded'' keys.
This list is not exhaustive, but at least it should works on all
terminals:
val string_of_key : key -> string
string_of_key key string representation of a key
val control_mapping : (int * char) list
Mapping from control key codes to character codes.
Here is the list of control keys:
+------+-------+------+------+------+-------+------------------------------------------------+ | Char | Oct | Dec | Name | Hex | Key | Comment | +------+-------+------+------+------+-------+------------------------------------------------+ | '@' | 0o00 | 0 | NUL | 0x00 | ^@ \0 | Null byte | | 'a' | 0o01 | 1 | SOH | 0x01 | ^A | Start of heading | | 'b' | 0o02 | 2 | STX | 0x02 | ^B | Start of text | | 'c' | 0o03 | 3 | ETX | 0x03 | ^C | End of text | | 'd' | 0o04 | 4 | EOT | 0x04 | ^D | End of transmission | | 'e' | 0o05 | 5 | ENQ | 0x05 | ^E | Enquiry | | 'f' | 0o06 | 6 | ACK | 0x06 | ^F | Acknowledge | | 'g' | 0o07 | 7 | BEL | 0x07 | ^G | Ring terminal bell | | 'h' | 0o10 | 8 | BS | 0x08 | ^H \b | Backspace | | 'i' | 0o11 | 9 | HT | 0x09 | ^I \t | Horizontal tab | | 'j' | 0o12 | 10 | LF | 0x0a | ^J \n | Line feed | | 'k' | 0o13 | 11 | VT | 0x0b | ^K | Vertical tab | | 'l' | 0o14 | 12 | FF | 0x0c | ^L \f | Form feed | | 'm' | 0o15 | 13 | CR | 0x0d | ^M \r | Carriage return | | 'n' | 0o16 | 14 | SO | 0x0e | ^N | Shift out | | 'o' | 0o17 | 15 | SI | 0x0f | ^O | Shift in | | 'p' | 0o20 | 16 | DLE | 0x10 | ^P | Data link escape | | 'q' | 0o21 | 17 | DC1 | 0x11 | ^Q | Device control 1 (XON) | | 'r' | 0o22 | 18 | DC2 | 0x12 | ^R | Device control 2 | | 's' | 0o23 | 19 | DC3 | 0x13 | ^S | Device control 3 (XOFF) | | 't' | 0o24 | 20 | DC4 | 0x14 | ^T | Device control 4 | | 'u' | 0o25 | 21 | NAK | 0x15 | ^U | Negative acknowledge | | 'v' | 0o26 | 22 | SYN | 0x16 | ^V | Synchronous idle | | 'w' | 0o27 | 23 | ETB | 0x17 | ^W | End of transmission block | | 'x' | 0o30 | 24 | CAN | 0x18 | ^X | Cancel | | 'y' | 0o31 | 25 | EM | 0x19 | ^Y | End of medium | | 'z' | 0o32 | 26 | SUB | 0x1a | ^Z | Substitute character | | '[' | 0o33 | 27 | ESC | 0x1b | ^[ | Escape | | '\' | 0o34 | 28 | FS | 0x1c | ^\ | File separator, Information separator four | | ']' | 0o35 | 29 | GS | 0x1d | ^] | Group separator, Information separator three | | '^' | 0o36 | 30 | RS | 0x1e | ^^ | Record separator, Information separator two | | '_' | 0o37 | 31 | US | 0x1f | ^_ | Unit separator, Information separator one | | '?' | 0o177 | 127 | DEL | 0x7f | ^? | Delete | +------+-------+------+------+------+-------+------------------------------------------------+
val key_enter : key
key_enter = Key_control 'j'
val key_escape : key
key_escape = Key_control '['
val key_tab : key
key_escape = Key_control 'i'
val key_backspace : key
key_backspace = Key_control '?'
val sequence_mapping : (Text.t * key) list
Mapping from sequence to keys
val decode_key : Text.t -> key
Decode a key.
val standard_input : Text.t Lwt_stream.t
The input stream used by Lwt_term.read_key
Get and decode a key from Lwt_term.standard_input
Styles ¶
type color = int
Type of a color. Most modern terminals support either 88 or
256 colors.
set_color num (red, green, blue) sets the three components of
the color number num
Standard colors
val default : color
val black : color
val red : color
val green : color
val yellow : color
val blue : color
val magenta : color
val cyan : color
val white : color
Light colors
Note: these colors are not supposed to works on all terminals, but
in practice it works with all modern ones. By the way, using
standard colors + bold mode will give the same result as using a
light color.
val lblack : color
val lred : color
val lgreen : color
val lyellow : color
val lblue : color
val lmagenta : color
val lcyan : color
val lwhite : color
Text with styles
type styled_text_instruction =
| | Text of Text.t | (* | Some text | *) |
| | Reset | (* | Resets all styles to default | *) |
| | Bold | |||
| | Underlined | |||
| | Blink | |||
| | Inverse | |||
| | Hidden | |||
| | Foreground of color | |||
| | Background of color |
Elmement of a styled-text
type styled_text = styled_text_instruction list
A styled text is a list of instructions
val textf : ('a, unit, string, styled_text_instruction) Pervasives.format4 -> 'a
textf fmt formats a texts with fmt and returns Text txt
val text : Text.t -> styled_text_instruction
val reset : styled_text_instruction
val bold : styled_text_instruction
val underlined : styled_text_instruction
val blink : styled_text_instruction
val inverse : styled_text_instruction
val fg : color -> styled_text_instruction
fg col = Foreground col
val bg : color -> styled_text_instruction
bg col = Background col
val strip_styles : styled_text -> Text.t
Drop all styles
val styled_length : styled_text -> int
Returns the length (in unicode character) of the given styled
text. The following equality holds for all styled-texts:
styled_length st = Text.length (strip_styles st)
val write_styled : Lwt_text.output_channel -> styled_text -> unit Lwt.t
write_styled oc st writes st on oc using escape
sequences.
val printc : styled_text -> unit Lwt.t
printc st prints the given styled text on standard output. If
stdout is not a tty, then styles are stripped.
The text is encoded to the system encoding before being
output.
val eprintc : styled_text -> unit Lwt.t
Same as printc but prints on stderr.
val printlc : styled_text -> unit Lwt.t
printlc st prints st, then reset styles and prints a
newline
val eprintlc : styled_text -> unit Lwt.t
Same as printlc but prints on stderr
Rendering ¶
type style = {
bold : bool; | |
underlined : bool; | |
blink : bool; | |
inverse : bool; | |
hidden : bool; | |
foreground : color; | |
background : color; |
}
Character styles
A character on the screen:
val blank : point
A space with default color and styles
Render an offscreen array to the terminal.
render_update displayed to_display does the same as render
to_display but assumes that displayed contains the current
displayed text. This reduces the amount of text sent to the
terminal.
Drawing ¶
Off-screen zones
Drawing helpers