Declaring terminals
Module Notty_unix

Fullscreen input and output


module Term : sig ... end

Terminal IO abstraction for fullscreen, interactive applications.

Inline output

These operations do not assume exclusive access to the output. This means that they can be combined with other means of producing output. At the same time, it means that they are affected by the current terminal state, and that this state is not tracked.

val winsize : Unix.file_descr -> (int * int) option

winsize fd is Some (columns, rows), the current dimensions of fd's backing tty, or None, when fd is not backed by a tty.

eol image is image, producing an extra newline when printed.

val output_image : ?cap:Notty.Cap.t -> ?fd:out_channel -> Notty.image -> unit

output_image ?cap ?fd image writes image to fd.

The image is displayed in its full height. If the output is a tty, image width is clipped to the output width. Otherwise, full width is used.

~cap is the optional terminal capability set.

~fd defaults to stdout.

val output_image_size : ?cap:Notty.Cap.t -> ?fd:out_channel -> ( (int * int) -> Notty.image ) -> unit

output_image_size ?cap ?fd f is output_image ?cap ?fd (f size) where size are fd's current output dimensions.

If fd is not backed by a tty, as a matter of convenience, f is applied to (80, 24). Use Unix.isatty or winsize to detect whether the output has a well-defined size.

val show_cursor : ?cap:Notty.Cap.t -> ?fd:out_channel -> bool -> unit

show_cursor ?cap ?fd visible toggles the cursor visibility on fd.

val move_cursor : ?cap:Notty.Cap.t -> ?fd:out_channel -> [ `Home | `By of int * int | `To of int * int ] -> unit

move_cursor ?cap ?fd motion moves the cursor on fd.

motion is one of:

  • `To (column, line), positioning the cursor to (column, line). Origin is (0, 0), the upper-left corner of the screen.
  • `Home, moving the cursor the beginning of line.
  • `By (columns, lines), moving the cursor columns to the right (left if negative) and lines down (up if negative).

    Note Behavior is terminal dependent if the movement overshoots the output size.

Capability detection

All image output requires terminal capabilities.

When not provided, capabilities are auto-detected, by checking that the output is a tty, that the environment variable $TERM is set, and that it is not set to either "" or "dumb". If these conditions hold, ANSI escapes are used. Otherwise, no escapes are used.