Terminal definitions
Type of terminals.
Exception raised when an encoding does not exist.
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
is_a_tty term
whether the intput and output of the given
terminal are connected to a tty device.
incoming_is_a_tty term
whether the output of term
is a tty
device.
Time waited before returning the escape key. This is not used on windows.
Exception raised when trying to use a function that can only be used on terminals.
Returns the curent size of the terminal.
It raises Not_a_tty if the output of the given terminal is not a tty.
Type of terminal modes.
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.
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.
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'e'
, which means that the function prints on stderrand <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 stringNote that if the terminal is not a tty, styles are stripped.
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.
A context for styled printing.
update_style ctx style
updates the style of the context with
style
. If needed styles of the terminal are modified.
Returns the output channel used by the given context. Note that this channel cannot be used after with_context has terminated.
encode_char term ch
encodes an unicode character using the
terminal encoding.
Change the style of the termina for subsequent unstyled output. It does nothing if the output is not a tty.
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.
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.
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.
get_size_from_fd fd
returns the size of the terminal accessible via
the given file descriptor.
set_size_from_fd fd size
tries to set the size of the terminal
accessible via the given file descriptor.
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.