Module Notty.A

A is for attribute.

Construction and composition of styling characteristics of text.

Consult the basics for an overview.


type color

An ineffable quality of light.

There are three kinds of colors:

  • Core 16 colors.

    ANSI defines 8 color names, with the actual display colors considered an implementation detail. Historically, this palette was extended with their light (sometimes bright or high-intensity) counterparts. Their presentation is undefined too, but typically produces a brighter shade. These colors - often called the ANSI colors - tend to be unpredictable, but ubiquitously supported.

  • Extended 256-color palette.

    This common feature extends the palette by further 240 colors. They come in two groups:

    • The color cube, a 6*6*6 approximation to the usual 24-bit RGB color cube; and
    • the grayscale ramp, containing (merely) 24 shades of gray.

    XTerm was the first to support this extension. Many terminals have since cloned it, so the support is wide, but not universal.

    As the extended colors are still palette-driven they do not have a fixed presentation, and the presentation can be changed in some terminals. Default palette tends to match XTerm's.

  • True color

    A recently established convention allows directly sending 24-bit colors to the terminal. This has been adopted by a growing minority of terminals. A reasonably up-to-date status document maintained by the community can be found here.

Some of the technical and historical background can be found in XTerm's FAQ.

Note No attempt is made to remap colors depending on the terminal. Terminals might ignore, remap, or completely misinterpret unsupported colors.

Core 16 colors

The first 8 have their standard ANSI names.

val black : color
val red : color
val green : color
val yellow : color
val blue : color
val magenta : color
val cyan : color
val white : color
val lightblack : color
val lightred : color
val lightgreen : color
val lightyellow : color
val lightblue : color
val lightmagenta : color
val lightcyan : color
val lightwhite : color

Extended 256-color palette

val rgb : r:int -> g:int -> b:int -> color

rgb ~r:red ~g:green ~b:blue is an extended-palette color from the color cube.

All three channels must be in the range 0 - 5. XTerm default palette maps this to 0x00, 0x5f, 0x87, 0xaf, 0xd7, and 0xff independently per channel.

  • raises Invalid_argument

    if a channel is outside the range.

val gray : int -> color

gray level is an extended-palette color from the grayscale ramp.

level must be in the range 0 - 23. XTerm default palette maps this to 8 + level * 10 on all three channels.

  • raises Invalid_argument

    if the level is outside the range.

True Color

val rgb_888 : r:int -> g:int -> b:int -> color

rgb_888 ~r:red ~g:green ~b:blue is a 24-bit color.

All three channels must be in the range 0 - 255.

  • raises Invalid_argument

    if a channel is outside the range.

Text styles

type style

Additional text properties.

val bold : style
val italic : style
val underline : style
val reverse : style

Attribute construction and composition

type t = attr
val equal : t -> t -> bool
val empty : attr

empty is the attribute with the default foreground and background color and empty style set.

val (++) : attr -> attr -> attr

a1 ++ a2 is the concatenation of a1 and a2, the attribute that has a2's foreground (resp. background), unless unset, in which case it is a1's, and the union of both style sets.

++ is left-associative, and forms a monoid with empty.

val fg : color -> attr

fg c is empty with foreground c.

val bg : color -> attr

bg c is empty with background c.

val st : style -> attr

st s is empty with style s.