notty 0.2.3 · OCaml Package

Terminal IO abstraction for fullscreen, interactive applications.

This module provides both input and output. It assumes exclusive ownership of the IO streams between initialization and shutdown.

type t

Representation of the terminal, giving structured access to IO.

Construction and destruction

val create : 
  ?dispose:bool ->
  ?nosig:bool ->
  ?mouse:bool ->
  ?bpaste:bool ->
  ?input:Unix.file_descr ->
  ?output:Unix.file_descr ->
  unit ->
  t

create ~dispose ~nosig ~mouse ~input ~output () creates a fresh terminal. It has the following side effects:

Unix.tcsetattr is applied to input to disable echo and canonical mode.
output is set to alternate screen mode, and the cursor is hidden. Mouse and bracketed paste reporting are (optionally) enabled.
SIGWINCH signal, normally ignored, is handled.

~dispose arranges for automatic cleanup of the terminal before the process terminates. The downside is that a reference to this terminal is retained until the program exits. Defaults to true.

~nosig additionally turns off signal delivery and flow control (isig and ixon) on input. Inhibits automatic handling of CTRL-{C,Z,\,S,Q}. Defaults to true.

~mouse activates mouse reporting. Defaults to true.

~bpaste activates bracketed paste reporting. Defaults to true.

~input is the input file descriptor. Defaults to stdin.

~output is the output file descriptor. Defaults to stdout.

val release : t -> unit

Dispose of this terminal. Original behavior of input fd is reinstated, cursor is restored, mouse reporting disabled, and alternate mode is terminated.

It is an error to use the commands on a released terminal, and will raise Invalid_argument, while release itself is idempotent.

Commands

val image : t -> Notty.image -> unit

image t i sets i as t's current image and redraws the terminal.

val refresh : t -> unit

refresh t redraws the terminal using the current image.

Useful if the output might have become garbled.

val cursor : t -> (int * int) option -> unit

cursor t pos sets and redraws the cursor.

None hides it. Some (x, y) places it at column x and row y, with the origin at (0, 0), mapping to the upper-left corner.

Events

val event : t -> [ Notty.Unescape.event | `Resize of int * int | `End ]

Wait for a new event. event t can be:

#Unescape.event, an event from the input fd;
`End if the input fd is closed, or the terminal was released; or
`Resize (cols, rows) giving the current size of the output tty, if a SIGWINCH was delivered before or during this call to event.

Note event is buffered. Calls can either block or immediately return. Use pending to detect when the next call would not block.

val pending : t -> bool

pending t is true if the next call to event would not block and the terminal has not yet been released.

Properties

val size : t -> int * int

size t is the current size of the terminal's output tty.

val fds : t -> Unix.file_descr * Unix.file_descr

fds t are t's input and output file descriptors.

Window size change notifications

module Winch : sig ... end

Manual SIGWINCH handling.

package notty

Construction and destruction

Commands

Events

Properties

Window size change notifications