LTerm (p.lambda-term.3.3.2.doc.lambda-term.LTerm)

Sourcetype t

Type of terminals.

Creation

Sourceexception No_such_encoding of string

Exception raised when an encoding does not exist.

val create : 
  ?windows:bool ->
  ?model: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 Sys.win32.

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

Sourceval model : t -> string

Returns the model of the terminal.

Sourceval colors : t -> int

Number of colors of the terminal.

Sourceval windows : t -> bool

Whether the terminal is a windows console or not.

Sourceval is_a_tty : t -> bool

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

Sourceval incoming_is_a_tty : t -> bool

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

Sourceval outgoing_is_a_tty : t -> bool

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

Sourceval escape_time : t -> float

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

Sourceval set_escape_time : t -> float -> unit

Set the time waited before returning the escape key.

Sourceexception Not_a_tty

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

Sourceval size : t -> LTerm_geom.size

Returns the curent size of the terminal.

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

Modes

Sourcetype mode

Type of terminal modes.

Sourceval 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 leave_raw_mode.

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

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

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

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

Sourceval enable_mouse : t -> unit Lwt.t

Enable mouse events reporting.

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

Sourceval disable_mouse : t -> unit Lwt.t

Disable mouse events reporting.

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

Cursor

Sourceval show_cursor : t -> unit Lwt.t

Make the cursor visible.

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

Sourceval hide_cursor : t -> unit Lwt.t

Make the cursor invisible.

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

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

goto term coord moves the cursor to the given coordinates.

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

Sourceval 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 Not_a_tty if the output of the given terminal is not a tty.

Erasing text

Sourceval clear_screen : t -> unit Lwt.t

clear_screen term clears the entire screen.

Sourceval clear_screen_next : t -> unit Lwt.t

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

Sourceval clear_screen_prev : t -> unit Lwt.t

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

Sourceval clear_line : t -> unit Lwt.t

clear_line term erases the current line.

Sourceval clear_line_next : t -> unit Lwt.t

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

Sourceval 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

Sourceval save_state : t -> unit Lwt.t

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

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

Sourceval load_state : t -> unit Lwt.t

Load the previously saved state of the terminal.

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

Events

Sourceval 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 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 stdout
'e', which means that the function prints on 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sourceval 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 set_style since styles will be modified only when needed.

Sourcetype context

A context for styled printing.

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

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

Sourceval context_term : context -> t

Returns the terminal used by the given context.

Sourceval context_oc : context -> Lwt_io.output_channel

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

Sourceval encode_string : Zed_utf8.t -> string

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

Sourceval encode_char : Uchar.t -> string

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

Styles

Sourceval 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

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

Render an offscreen array to the given terminal.

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

Sourceval 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 Not_a_tty if the output of the given terminal is not a tty.

Sourceval 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 fprints and print_box you should use print_box because it works better under windows and is more efficient.

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

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

print_box term matrix Same as 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 print_box and print_box_with_newlines is that when the text is selected in the terminal, with print_box it will always be a box with the dimensions of matrix. With 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

Sourceval flush : t -> unit Lwt.t

Flushes the underlying output channel used by the terminal.

Well known instances

Sourceval stdout : t Lwt.t Lazy.t

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

Sourceval stderr : t Lwt.t Lazy.t

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

Low-level functions

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

Sourceval 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

Source

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.