(* File: ANSITerminal.mli Copyright 2004 Troestler Christophe Christophe.Troestler(at)umons.ac.be This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation, with the special exception on linking described in file LICENSE. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file LICENSE for more details. *) (** This module offers basic control of ANSI compliant terminals and the windows shell. The functions below do not send ANSI codes (i.e., do nothing or only print the output) when then output is not connected to a TTY. Functions providing information (such as {!pos_cursor}) fail when in that situation. TTY detection is configurable by changing the value of {!isatty}. This library is not thread safe. @author Christophe Troestler (Christophe.Troestler@umons.ac.be) @author Vincent Hugot (vincent.hugot@gmail.com) *) (** {2 Colors and style} *) (** Available colors. *) type color = | Black | Red | Green | Yellow | Blue | Magenta | Cyan | White | Default (** Default color of the terminal *) (** Various styles for the text. [Blink] and [Hidden] may not work on every terminal. *) type style = | Reset | Bold | Underlined | Blink | Inverse | Hidden | Foreground of color | Background of color val black : style (** Shortcut for [Foreground Black] *) val red : style (** Shortcut for [Foreground Red] *) val green : style (** Shortcut for [Foreground Green] *) val yellow : style (** Shortcut for [Foreground Yellow] *) val blue : style (** Shortcut for [Foreground Blue] *) val magenta : style (** Shortcut for [Foreground Magenta] *) val cyan : style (** Shortcut for [Foreground Cyan] *) val white : style (** Shortcut for [Foreground White] *) val default : style (** Shortcut for [Foreground Default] *) val on_black : style (** Shortcut for [Background Black] *) val on_red : style (** Shortcut for [Background Red] *) val on_green : style (** Shortcut for [Background Green] *) val on_yellow : style (** Shortcut for [Background Yellow] *) val on_blue : style (** Shortcut for [Background Blue] *) val on_magenta : style (** Shortcut for [Background Magenta] *) val on_cyan : style (** Shortcut for [Background Cyan] *) val on_white : style (** Shortcut for [Background White] *) val on_default : style (** Shortcut for [Background Default] *) val set_autoreset : bool -> unit (** Turns the autoreset feature on and off. It defaults to on. *) val print_string : style list -> string -> unit (** [print_string attr txt] prints the string [txt] with the attibutes [attr]. After printing, the attributes are automatically reseted to the defaults, unless autoreset is turned off. *) val prerr_string : style list -> string -> unit (** Like [print_string] but prints on the standard error. *) val printf : style list -> ('a, unit, string, unit) format4 -> 'a (** [printf attr format arg1 ... argN] prints the arguments [arg1],...,[argN] according to [format] with the attibutes [attr]. After printing, the attributes are automatically reseted to the defaults, unless autoreset is turned off. *) val eprintf : style list -> ('a, unit, string, unit) format4 -> 'a (** Same as {!printf} but prints the result on [stderr]. *) val sprintf : style list -> ('a, unit, string) format -> 'a (** Same as {!printf} but returns the result in a string. This only works on ANSI compliant terminals — for which escape sequences are used — and not under Windows — where system calls are required. On Windows, it is identical to the standard [sprintf]. *) (** {2 Erasing} *) type loc = Eol | Above | Below | Screen val erase : loc -> unit (** [erase Eol] clear from the cursor position to the end of the line without moving the cursor. [erase Above] erases everything before the position of the cursor. [erase Below] erases everything after the position of the cursor. [erase Screen] erases the whole screen. This function does not modify the position of the cursor. *) (** {2 Cursor} *) val set_cursor : int -> int -> unit (** [set_cursor x y] puts the cursor at position [(x,y)], [x] indicating the column (the leftmost one being 1) and [y] being the line (the topmost one being 1). If [x <= 0], the [x] coordinate is unchanged; if [y <= 0], the [y] coordinate is unchanged. *) val move_cursor : int -> int -> unit (** [move_cursor x y] moves the cursor by [x] columns (to the right if [x > 0], to the left if [x < 0]) and by [y] lines (downwards if [y > 0] and upwards if [y < 0]). *) val move_bol : unit -> unit (** [move_bol()] moves the cursor to the beginning of the current line. This is useful for progress bars for example. *) val pos_cursor : unit -> int * int (** [pos_cursor()] returns a couple [(x,y)] giving the current position of the cursor, [x >= 1] being the column and [y >= 1] the row. *) val save_cursor : unit -> unit (** [save_cursor()] saves the current position of the cursor. *) val restore_cursor : unit -> unit (** [restore_cursor()] replaces the cursor to the position saved with [save_cursor()]. *) (** {2 Size} *) val resize : int -> int -> unit (** [resize width height] resize the current terminal to the given [width] and [height]. *) val size : unit -> int * int (** [size()] returns a pair [(width, height)] giving the size of the terminal in character cells. *) (** {2 Scrolling} *) val scroll : int -> unit (** [scroll n] scrolls the terminal by [n] lines, up (creating new lines at the bottom) if [n > 0] and down if [n < 0]. *) (** {2 TTY} *) val isatty : (Unix.file_descr -> bool) ref (** Function used to detect whether the current output is connected to a TTY. Defaults to [Unix.isatty]. *) ;;