RasterExRatatui.Palette (RasterExRatatui v0.4.0)

Turns ExRatatui colour terms into RGB triples for colour panels.

A cell's fg and bg are ExRatatui.Style.color/0 terms: :reset, one of the 16 named ANSI colours, {:indexed, 0..255}, or {:rgb, r, g, b}. A terminal resolves the first three through its theme; a panel has no theme, so a palette carries one.

Named colours and indexed 0..15 come from the theme (xterm's defaults unless overridden).
Indexed 16..231 is the 6×6×6 colour cube and 232..255 the grayscale ramp, as in xterm.
{:rgb, r, g, b} is used as is.
:reset is the theme's default foreground or background, depending on which side of the cell it colours.

Examples

iex> alias RasterExRatatui.Palette
iex> palette = Palette.new(reset_bg: {16, 16, 32}, theme: %{red: {255, 85, 85}})
iex> Palette.rgb(:red, :fg, palette)
{255, 85, 85}
iex> Palette.rgb(:reset, :bg, palette)
{16, 16, 32}
iex> Palette.rgb({:indexed, 196}, :fg, palette)
{255, 0, 0}

Summary

Types

rgb()

An RGB triple, each channel 0..255.

role()

Which side of the cell a colour paints, which decides what :reset means.

t()

Functions

bright(name)

The bright variant of a dark named colour (:red → :light_red, :black → :dark_gray, :gray → :white, indexed 0..7 → 8..15). Every other colour is returned unchanged.

cell_colors(cell, palette)

A cell's {foreground, background} RGB, after its modifiers.

new(opts \\ [])

Builds a palette.

rgb(color, role, palette \\ new())

Resolves color to RGB. role only matters for :reset.

Types

rgb()

@type rgb() :: {0..255, 0..255, 0..255}

An RGB triple, each channel 0..255.

role()

@type role() :: :fg | :bg

Which side of the cell a colour paints, which decides what :reset means.

t()

@type t() :: %RasterExRatatui.Palette{
  bold_bright: boolean(),
  reset_bg: rgb(),
  reset_fg: rgb(),
  theme: %{required(atom()) => rgb()}
}

Functions

bright(name)

@spec bright(ExRatatui.Style.color()) :: ExRatatui.Style.color()

The bright variant of a dark named colour (:red → :light_red, :black → :dark_gray, :gray → :white, indexed 0..7 → 8..15). Every other colour is returned unchanged.

Examples

iex> RasterExRatatui.Palette.bright(:blue)
:light_blue

iex> RasterExRatatui.Palette.bright({:indexed, 3})
{:indexed, 11}

iex> RasterExRatatui.Palette.bright(:reset)
:reset

cell_colors(cell, palette)

@spec cell_colors(ExRatatui.CellSession.Cell.t(), t()) :: {rgb(), rgb()}

A cell's {foreground, background} RGB, after its modifiers.

:bold brightens a dark named foreground when the palette's bold_bright is on; :reversed then swaps the two sides. Other modifiers do not change colour.

Examples

iex> alias ExRatatui.CellSession.Cell
iex> alias RasterExRatatui.Palette
iex> Palette.cell_colors(%Cell{fg: :red, bg: :reset, modifiers: [:bold]}, Palette.new())
{{255, 0, 0}, {0, 0, 0}}
iex> Palette.cell_colors(%Cell{fg: :reset, bg: :blue, modifiers: [:reversed]}, Palette.new())
{{0, 0, 238}, {229, 229, 229}}

new(opts \\ [])

@spec new(keyword()) :: t()

Builds a palette.

Options

:theme — a map of named colours to RGB, merged over xterm's defaults, so a partial map overrides only what it names.
:reset_fg — the default foreground (default {229, 229, 229}, xterm's :gray).
:reset_bg — the default background, also used for margins and skipped cells (default {0, 0, 0}).
:bold_bright — paint bold text with the bright variant of a dark named colour, as most terminals do (default true). A bitmap font has no bold face, so this is the only visible trace of :bold.

Raises ArgumentError for a theme key that is not a named colour.

Examples

iex> RasterExRatatui.Palette.new().reset_bg
{0, 0, 0}

rgb(color, role, palette \\ new())

@spec rgb(ExRatatui.Style.color(), role(), t()) :: rgb()

Resolves color to RGB. role only matters for :reset.

Examples

iex> alias RasterExRatatui.Palette
iex> Palette.rgb({:rgb, 1, 2, 3}, :fg)
{1, 2, 3}
iex> Palette.rgb(:reset, :fg)
{229, 229, 229}
iex> Palette.rgb({:indexed, 9}, :fg)
{255, 0, 0}
iex> Palette.rgb({:indexed, 16 + 36 * 5 + 6 * 2 + 1}, :bg)
{255, 135, 95}
iex> Palette.rgb({:indexed, 244}, :bg)
{128, 128, 128}