package ansifmt

  1. Overview
  2. Docs

Module Ansi.Color

Color

type t = [
  1. | `Basic of int
  2. | `Rgb of int * int * int
]

Represents a ANSI color. It can be either 8-bit, which provides a portable palette of 256 colors, or 24-bit (RGB), which gives more granularity.

The 256-color palette can be found on the Wikipedia article on ANSI escape sequences: https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit

NOTE: Each constructor would normally expect integers between 0 and 255 - for convenience, they operate with the built-in int type which is technically too permissive, but allows direct use of numeric literals. To prevent generating invalid escape sequences, the integers get therefore normalized by taking their absolute value modulo 256.

val to_attributes : [ `Foreground | `Background ] -> t -> Attributes.t

to_attributes ground color produces the attribute record of the color.

Since the code depends on whether the color is applied to the foreground or the background, this latter piece of information must also be provided via ground.

Comparison

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

color1 = color2 determines whether two colors are equal.

Note: `Basic colors are never equal to `Rgb ones even if your terminal renders them identically.

Constants

These constants are provided for convenience. They correspond to the 4-bit ANSI colors.

Base colors

val black : t
val red : t
val green : t
val yellow : t
val blue : t
val magenta : t
val cyan : t
val white : t

Bright variants

val bright_black : t
val bright_red : t
val bright_green : t
val bright_yellow : t
val bright_blue : t
val bright_magenta : t
val bright_cyan : t
val bright_white : t

Checked constructors

These functions are equivalent to the type's constructors but check the integer values instead of normalizing them.

val basic : int -> [ `Basic of int ] option

basic index constructs a 8-bit color. index must be between 0 and 255 (both included) ; otherwise, it returns None.

val rgb : (int * int * int) -> [ `Rgb of int * int * int ] option

rgb (r, g, b) constructs an RGB color. All channels must be between 0 and 255 (both included) ; otherwise, it returns None.

Serialization/Deserialization

val serialize : t -> string

serialize color produces a serialized representation of the color.

Tip: the serialized color can be retreived back using parse.

Note: colors are normalized before serialization.

These functions parse strings to get a color from them.

val of_hex_repr : string -> [ `Rgb of int * int * int ] option

of_hex_repr string attempts to parse the string as the representation of an hexadecimal number.

It allows:

  • Leading hash (#f864a0, optional)
  • Implicitly doubled digits (#ddd)
val parse : string -> t option

parse string attempts to find a serialized color in the string.

It supports rgb(r, g, b) and basic(n), ignoring spaces and case. Numbers greater than 255 are allowed, but not less than 0.

Utility functions

val luminance : [ `Rgb of int * int * int ] -> float

luminance color returns the luminance of the color as a floating-point number between 0 and 1.

Important: This is NOT a function to estimate perceived lightness. For that, see perceived_lightness.

Note: the color is normalized before calculation.

Note: this function is only available for RGB colors.

val perceived_lightness : [ `Rgb of int * int * int ] -> int

perceived_lightness color returns the perceived lightness of the color as an integer between 0 and 100.

Note: the color is normalized before calculation.

Note: this function is only available for RGB colors.

val best_for_contrast : [ `Rgb of int * int * int ] -> [ `Light | `Dark ]

best_for_contrast color determines whether a light or dark opposite color is best.

For example, if color is a background color, this function will tell whether the text written on top of it should be light or dark for the best readability.

Note: the calculation is based on perceived lightness.

Note: the color is normalized before calculation.

Note: this function is only available for RGB colors.

module Basic : sig ... end

Functions to deal with basic colors.

module Rgb : sig ... end

Functions to deal with RGB colors.