package ansifmt

  1. Overview
  2. Docs

Module Ansifmt.Ansi

This module defines the escape sequence data type.

Every value of this type is one styling (`Bold, `Reverse, `Foreground Color.red) or the composition of two of them (`Bold&`Reverse), which can be chained (`Dim & `Italic & `Blink & `Background Color.magenta).

open Ansifmt

let chesnay = `Italic
let rocquencout = Ansi.(`Bold & `Reverse & `Foreground Color.red)

(* compose to infinity! *)
let inria = Ansi.(chesnay & rocquencourt)

chesnay, rocquencourt and inria all have the same type t.

In a composition chain, if two stylings are overlapping (for example, `Foreground Color.blue & `Foreground Color.red), the rightmost takes precedence.

type t = [
  1. | `Bold
  2. | `Dim
  3. | `Italic
  4. | `Underline
  5. | `Reverse
  6. | `Foreground of Color.t
  7. | `Background of Color.t
  8. | `Composed of t * t
]

Represents an ANSI SGR escape sequence.

val compose : t -> t -> t

compose left right combines the left and right sequences into one.

See also: ( & )

val (=) : t -> t -> bool

ansi1 = ansi2 determines whether two escape sequences are equal.

val serialize : t -> string

serialize ansi produces a serialized representation of the ansi escape sequence.

Example

open Ansifmt

let styling = Ansi.(`Dim & `Background (`Rgb (0, 0, 0)))
let () = Printf.printf "%s\n" (Ansi.serialize styling)

dim & background(rgb(0, 0, 0)) will be printed.

See also: deserialize.

val deserialize : string -> t option

deserialize string produces an escape sequence from a serialization string. If it fails to parse, returns None.

Example

open Ansifmt

let serialized = "blink & BOLD & foreground(rgb(255, 0, 0))"

let () =
match Ansi.deserialize serialized with
| None -> Printf.eprintf "oh nothing don't worry\n"
| Some ansi -> 
    Printf.printf "%sHACKED!\n" (Ansi.show ansi)
;;

A blinking bold HACKED! will be printed in red.

See also: serialize.

val show : t -> string

show ansi renders the ansi escape sequence into a string.

Example

open Ansifmt

let versailles = Ansi.(`Underline & `Background Color.green)
let () = Printf.printf "%s hello!\n" (Ansi.show versailles)

hello! will be printed with an underline and a green background.

See also: Ansifmt.Fmt, wrap, unshow.

val unshow : t -> string

unshow ansi renders the ANSI escape sequence that cancels ansi into a string.

Example

open Ansifmt

let cergy = Ansi.(`Blink & `Dim & `Foreground Color.blue)

let () =
Printf.printf
    "%s hello! %s bye.\n"
    (Ansi.show cergy)
    (Ansi.unshow cergy)
;;

While hello! will be printed dim, blinking and in blue, bye. will be unstylized.

See also: Ansifmt.Fmt, wrap, show.

val wrap : t -> string -> string

wrap ansi string wraps string with the rendered ansi escape sequence and its cancelling counterpart.

For example, if string is "Hello" and ansi is `Bold, the result will be "\x1b[1mHello\x1b[22m", which makes the string appear bold but not what comes after.

Example

open Ansifmt

let styling = `Foreground (`Rgb (255, 127, 0))
let text = "I love OCaml"

let () = Printf.printf "%s\n" (Ansi.wrap styling text)

I love OCaml will be printed in a beautiful orange color.

See also: Ansifmt.Fmt, show, unshow.

val enrich : t -> string -> string

enrich is a synonym of wrap.

val (&) : t -> t -> t

left & right is the same as compose left right.

NOTE: & is associative but not commutative.

Example

open Ansifmt

let styling = Ansi.(`Bold & `Foreground Color.yellow)
module Attributes : module type of Attributes
module Color : module type of Color