LTerm

# Module LTerm

    module LTerm: sig .. end

Terminal definitions

    type t

Type of terminals.

###### Creation

    exception No_such_encoding of string

Exception raised when an encoding does not exist.

    val create : ?windows:bool ->
           ?model:string ->
           ?incoming_encoding:string ->
           ?outgoing_encoding:string ->
           Lwt_unix.file_descr ->
           Lwt_io.input_channel ->
           Lwt_unix.file_descr -> Lwt_io.output_channel -> t Lwt.t

`create ?windows ?model ?incoming_encoding ?outgoing_encoding input_fd input_channel outout_fd output_channel` creates a new terminal using `input_fd` and `input_channel` for inputs and `output_fd` and `output_channel` for outputs.

- `windows` indicates whether the terminal is a windows console (not mintty, rxvt, ...). It defaults to `Lwt_sys.windows`.

- `model` is the type of the terminal, such as "rxvt" or "xterm". It defaults to the contents of the "TERM" environment variable, or to "dumb" if this one is not found. It is used to determine capabilities of the terminal, such as the number of colors. This is not used if `windows` is `true`.

- `incoming_encoding` is the encoding used for incoming data. It defaults to `LTerm_windows.get_console_cp` if `windows` is `true` and `LTerm_unix.system_encoding` otherwise.

- `outgoing_encoding` is the encoding used for outgoing data. It defaults to `LTerm_windows.get_console_output_cp` if `windows` is `true` and `LTerm_unix.system_encoding` otherwise. Note that transliteration is used so printing unicode character on the terminal will never fail.

If one of the two given encodings does not exist, it raises `No_such_encoding`.

Note about terminal resize: in the windows console resizes are not automatically detected. Lambda-term will only check for resize only when something happens. If you want it to poll just write somewhere in your program:

          Lwt_engine.on_timer 1.0 true ignore

###### Informations

    val model : t -> string

Returns the model of the terminal.

    val colors : t -> int

Number of colors of the terminal.

    val windows : t -> bool

Whether the terminal is a windows console or not.

    val is_a_tty : t -> bool

`is_a_tty term` whether the intput and output of the given terminal are connected to a tty device.

    val incoming_is_a_tty : t -> bool

`incoming_is_a_tty term` whether the input of `term` is a tty device.

    val outgoing_is_a_tty : t -> bool

`incoming_is_a_tty term` whether the output of `term` is a tty device.

    val escape_time : t -> float

Time waited before returning the escape key. This is not used on windows.

    val set_escape_time : t -> float -> unit

Set the time waited before returning the escape key.

    exception Not_a_tty

Exception raised when trying to use a function that can only be used on terminals.

    val size : t -> LTerm_geom.size

Returns the curent size of the terminal.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

###### Modes

    type mode

Type of terminal modes.

    val enter_raw_mode : t -> mode Lwt.t

`enter_raw_mode term` puts the terminal in ``raw mode''. In this mode keyboard events are returned as they happen. In normal mode only complete line are returned. It returns the current terminal mode that can be restored using `LTerm.leave_raw_mode`.

It raises `LTerm.Not_a_tty` if the input of the given terminal is not tty.

    val leave_raw_mode : t -> mode -> unit Lwt.t

`leave_raw_mode term mode` leaves the raw mode by restoring the given mode.

It raises `LTerm.Not_a_tty` if the input of the given terminal is not tty.

    val enable_mouse : t -> unit Lwt.t

Enable mouse events reporting.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

    val disable_mouse : t -> unit Lwt.t

Disable mouse events reporting.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

###### Cursor

    val show_cursor : t -> unit Lwt.t

Make the cursor visible.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

    val hide_cursor : t -> unit Lwt.t

Make the cursor invisible.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

    val goto : t -> LTerm_geom.coord -> unit Lwt.t

`goto term coord` moves the cursor to the given coordinates.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

    val move : t -> int -> int -> unit Lwt.t

`move term rows columns` moves the cursor by the given number of lines and columns. Both `rows` and `columns` may be negavite.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

###### Erasing text

    val clear_screen : t -> unit Lwt.t

`clear_screen term` clears the entire screen.

    val clear_screen_next : t -> unit Lwt.t

`clear_screen_next term` clears the screen from the cursor to the bottom of the screen.

    val clear_screen_prev : t -> unit Lwt.t

`clear_screen_prev term` clears the screen from the cursor to the top of the screen.

    val clear_line : t -> unit Lwt.t

`clear_line term` erases the current line.

    val clear_line_next : t -> unit Lwt.t

`clear_line_next term` erases the current line from the cursor to the end of the line.

    val clear_line_prev : t -> unit Lwt.t

`clear_line_prev term` erases the current line from the cursor to the beginning of the line.

###### State

    val save_state : t -> unit Lwt.t

Save the current state of the terminal so it can be restored latter.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

    val load_state : t -> unit Lwt.t

Load the previously saved state of the terminal.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

###### Events

    val read_event : t -> LTerm_event.t Lwt.t

Reads and returns one event. The terminal should be in raw mode before calling this function, otherwise event will not be reported as they happen. It does not fail if the terminal is not a tty.

Note: you must not call `LTerm.read_event` from multiple thread at the same time, it will raise `Failure` if you try to do so.

###### Printing

All these functions accept only valid UTF-8 strings (or unicode styled text). Strings are recoded on the fly using the terminal output encoding (except if the terminal output encoding is already UTF-8, in which case the string is just printed as-it).

The general name of a printing function is `<prefix>print<suffixes>`.

Where `<prefix>` is one of:

- `'f'`, which means that the function takes as argument a terminal
- nothing, which means that the function prints on `LTerm.stdout`
- `'e'`, which means that the function prints on `LTerm.stderr`

and `<suffixes>` is a combination of:

- `'l'` which means that a new-line character is printed after the message
- `'f'` which means that the function takes as argument a format instead of a string
- `'s'` which means that the function takes as argument a styled string instead of a string

Note that if the terminal is not a tty, styles are stripped.

    val fprint : t -> Zed_utf8.t -> unit Lwt.t

    val fprintl : t -> Zed_utf8.t -> unit Lwt.t

    val fprintf : t -> ('a, unit, Zed_utf8.t, unit Lwt.t) Pervasives.format4 -> 'a

    val fprints : t -> LTerm_text.t -> unit Lwt.t

    val fprintlf : t -> ('a, unit, Zed_utf8.t, unit Lwt.t) Pervasives.format4 -> 'a

    val fprintls : t -> LTerm_text.t -> unit Lwt.t

    val print : Zed_utf8.t -> unit Lwt.t

    val printl : Zed_utf8.t -> unit Lwt.t

    val printf : ('a, unit, Zed_utf8.t, unit Lwt.t) Pervasives.format4 -> 'a

    val prints : LTerm_text.t -> unit Lwt.t

    val printlf : ('a, unit, Zed_utf8.t, unit Lwt.t) Pervasives.format4 -> 'a

    val printls : LTerm_text.t -> unit Lwt.t

    val eprint : Zed_utf8.t -> unit Lwt.t

    val eprintl : Zed_utf8.t -> unit Lwt.t

    val eprintf : ('a, unit, Zed_utf8.t, unit Lwt.t) Pervasives.format4 -> 'a

    val eprints : LTerm_text.t -> unit Lwt.t

    val eprintlf : ('a, unit, Zed_utf8.t, unit Lwt.t) Pervasives.format4 -> 'a

    val eprintls : LTerm_text.t -> unit Lwt.t

Printing contexts
You shoud use these functions when you to print a lot of styled text that does not entirely fit in a single `LTerm_text.t` value.

This is more efficient than calling manually `LTerm.set_style` since styles will be modified only when needed.

    type context

A context for styled printing.

    val with_context : t -> (context -> 'a Lwt.t) -> 'a Lwt.t

`with_context term f` creates a new printing context and pass it to `f`. Note that calls to `with_context` are serialized.

    val update_style : context -> LTerm_style.t -> unit Lwt.t

`update_style ctx style` updates the style of the context with `style`. If needed styles of the terminal are modified.

    val context_term : context -> t

Returns the terminal used by the given context.

    val context_oc : context -> Lwt_io.output_channel

Returns the output channel used by the given context. Note that this channel cannot be used after `LTerm.with_context` has terminated.

    val encode_string : t -> Zed_utf8.t -> string

`encode_string term str` encodes an UTF-8 string using the terminal encoding.

    val encode_char : t -> CamomileLibrary.UChar.t -> string

`encode_char term ch` encodes an unicode character using the terminal encoding.

###### Styles

    val set_style : t -> LTerm_style.t -> unit Lwt.t

Change the style of the termina for subsequent unstyled output. It does nothing if the output is not a tty.

###### Rendering

    val render : t -> LTerm_draw.matrix -> unit Lwt.t

Render an offscreen array to the given terminal.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

    val render_update : t -> LTerm_draw.matrix -> LTerm_draw.matrix -> unit Lwt.t

`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.

It raises `LTerm.Not_a_tty` if the output of the given terminal is not a tty.

    val print_box : t -> LTerm_draw.matrix -> unit Lwt.t

`print_box term matrix` prints the contents of `matrix` starting at current cursor row. Note that when you have the choice between using `LTerm.fprints` and `LTerm.print_box` you should use `LTerm.print_box` because it works better under windows and is more efficient.

The cursor is moved to the beginning of the last displayed line.

    val print_box_with_newlines : t -> LTerm_draw.matrix -> unit Lwt.t

`print_box term matrix` Same as `LTerm.print_box` but `matrix` may contains newline characters. It must contain one more column that the terminal (in case a line of the length of the terminal ends with a newline).

The difference between `LTerm.print_box` and `LTerm.print_box_with_newlines` is that when the text is selected in the terminal, with `LTerm.print_box` it will always be a box with the dimensions of `matrix`. With `LTerm.print_box_with_newlines` it may contains lines longer than the width of the terminal.

The contents of a line after the first newline character (if any) in a row of `matrix` is ignored. The rest of the line get the style of the newline character.

###### Misc

    val flush : t -> unit Lwt.t

Flushes the underlying output channel used by the terminal.

###### Well known instances

    val stdout : t Lwt.t Lazy.t

Terminal using `Lwt_unix.stdin` as input and `Lwt_unix.stdout` as output.

    val stderr : t Lwt.t Lazy.t

Terminal using `Lwt_unix.stdin` as input and `Lwt_unix.stderr` as output.

###### Low-level functions

    val get_size_from_fd : Lwt_unix.file_descr -> LTerm_geom.size Lwt.t

`get_size_from_fd fd` returns the size of the terminal accessible via the given file descriptor.

    val set_size_from_fd : Lwt_unix.file_descr -> LTerm_geom.size -> unit Lwt.t

`set_size_from_fd fd size` tries to set the size of the terminal accessible via the given file descriptor.

###### Modification

    val set_io : ?incoming_fd:Lwt_unix.file_descr ->
           ?incoming_channel:Lwt_io.input_channel ->
           ?outgoing_fd:Lwt_unix.file_descr ->
           ?outgoing_channel:Lwt_io.output_channel -> t -> unit Lwt.t

Modifies file descriptors/channels of a terminal. Unspecified arguments are kept unchanged.

Note: before modifying a terminal you should ensure that no operation is pending on it.