module TermColors

Overview

Color-related functions for term/console applications.

Terminal apps can use 5 different palettes: 1. Monochrome (2-color) 2. Low color (8-color) 3. ANSI / XTerm color (16-color) 4. High color (256-color) 5. TrueColor (16M-color/24-bit color)

Direct including types

• TermColors::Data

Defined in:

Constant Summary

CACHE_MATCH = {} of Int32 => Int32

Storage cache for #match method

CACHE_MATCH_LIMIT = 65536

Upper bound on CACHE_MATCH. Key is the full 24-bit RGB value, so an animated TrueColor source can feed #match unbounded distinct keys; on overflow the cache is cleared wholesale.

ColorNames = {"default" => -1, "normal" => -1, "bg" => -1, "fg" => -1, "black" => 0, "red" => 1, "green" => 2, "yellow" => 3, "blue" => 4, "magenta" => 5, "cyan" => 6, "white" => 7, "lightblack" => 8, "lightred" => 9, "lightgreen" => 10, "lightyellow" => 11, "lightblue" => 12, "lightmagenta" => 13, "lightcyan" => 14, "lightwhite" => 15, "brightblack" => 8, "brightred" => 9, "brightgreen" => 10, "brightyellow" => 11, "brightblue" => 12, "brightmagenta" => 13, "brightcyan" => 14, "brightwhite" => 15, "grey" => 8, "gray" => 8, "lightgrey" => 7, "lightgray" => 7, "brightgrey" => 7, "brightgray" => 7}

Mapping of notable color names to 16 color indices.

CSS_HUE = /(#{CSS_NUM})(deg|grad|rad|turn)?/i

The hsl() first argument: a number with an optional CSS angle unit.

CSS_NUM = /-?(?:\d+(?:\.\d+)?|\.\d+)/

A CSS <number>: optionally negative, integer or decimal.

CSS_RGB_COMPONENT = /(#{CSS_NUM})(%)?/

A single #rgb() component: an optionally-signed number with an optional trailing %. The sign is load-bearing: CSS clamps a negative channel to 0, so it must be read as negative rather than as its magnitude (rgb(-10, …) is 0, not 10).

HI2HH = ["#000000", "#cd0000", "#00cd00", "#cdcd00", "#0000ee", "#cd00cd", "#00cdcd", "#e5e5e5", "#7f7f7f", "#ff0000", "#00ff00", "#ffff00", "#5c5cff", "#ff00ff", "#00ffff", "#ffffff", "#000000", "#00005f", "#000087", "#0000af", "#0000d7", "#0000ff", "#005f00", "#005f5f", "#005f87", "#005faf", "#005fd7", "#005fff", "#008700", "#00875f", "#008787", "#0087af", "#0087d7", "#0087ff", "#00af00", "#00af5f", "#00af87", "#00afaf", "#00afd7", "#00afff", "#00d700", "#00d75f", "#00d787", "#00d7af", "#00d7d7", "#00d7ff", "#00ff00", "#00ff5f", "#00ff87", "#00ffaf", "#00ffd7", "#00ffff", "#5f0000", "#5f005f", "#5f0087", "#5f00af", "#5f00d7", "#5f00ff", "#5f5f00", "#5f5f5f", "#5f5f87", "#5f5faf", "#5f5fd7", "#5f5fff", "#5f8700", "#5f875f", "#5f8787", "#5f87af", "#5f87d7", "#5f87ff", "#5faf00", "#5faf5f", "#5faf87", "#5fafaf", "#5fafd7", "#5fafff", "#5fd700", "#5fd75f", "#5fd787", "#5fd7af", "#5fd7d7", "#5fd7ff", "#5fff00", "#5fff5f", "#5fff87", "#5fffaf", "#5fffd7", "#5fffff", "#870000", "#87005f", "#870087", "#8700af", "#8700d7", "#8700ff", "#875f00", "#875f5f", "#875f87", "#875faf", "#875fd7", "#875fff", "#878700", "#87875f", "#878787", "#8787af", "#8787d7", "#8787ff", "#87af00", "#87af5f", "#87af87", "#87afaf", "#87afd7", "#87afff", "#87d700", "#87d75f", "#87d787", "#87d7af", "#87d7d7", "#87d7ff", "#87ff00", "#87ff5f", "#87ff87", "#87ffaf", "#87ffd7", "#87ffff", "#af0000", "#af005f", "#af0087", "#af00af", "#af00d7", "#af00ff", "#af5f00", "#af5f5f", "#af5f87", "#af5faf", "#af5fd7", "#af5fff", "#af8700", "#af875f", "#af8787", "#af87af", "#af87d7", "#af87ff", "#afaf00", "#afaf5f", "#afaf87", "#afafaf", "#afafd7", "#afafff", "#afd700", "#afd75f", "#afd787", "#afd7af", "#afd7d7", "#afd7ff", "#afff00", "#afff5f", "#afff87", "#afffaf", "#afffd7", "#afffff", "#d70000", "#d7005f", "#d70087", "#d700af", "#d700d7", "#d700ff", "#d75f00", "#d75f5f", "#d75f87", "#d75faf", "#d75fd7", "#d75fff", "#d78700", "#d7875f", "#d78787", "#d787af", "#d787d7", "#d787ff", "#d7af00", "#d7af5f", "#d7af87", "#d7afaf", "#d7afd7", "#d7afff", "#d7d700", "#d7d75f", "#d7d787", "#d7d7af", "#d7d7d7", "#d7d7ff", "#d7ff00", "#d7ff5f", "#d7ff87", "#d7ffaf", "#d7ffd7", "#d7ffff", "#ff0000", "#ff005f", "#ff0087", "#ff00af", "#ff00d7", "#ff00ff", "#ff5f00", "#ff5f5f", "#ff5f87", "#ff5faf", "#ff5fd7", "#ff5fff", "#ff8700", "#ff875f", "#ff8787", "#ff87af", "#ff87d7", "#ff87ff", "#ffaf00", "#ffaf5f", "#ffaf87", "#ffafaf", "#ffafd7", "#ffafff", "#ffd700", "#ffd75f", "#ffd787", "#ffd7af", "#ffd7d7", "#ffd7ff", "#ffff00", "#ffff5f", "#ffff87", "#ffffaf", "#ffffd7", "#ffffff", "#080808", "#121212", "#1c1c1c", "#262626", "#303030", "#3a3a3a", "#444444", "#4e4e4e", "#585858", "#626262", "#6c6c6c", "#767676", "#808080", "#8a8a8a", "#949494", "#9e9e9e", "#a8a8a8", "#b2b2b2", "#bcbcbc", "#c6c6c6", "#d0d0d0", "#dadada", "#e4e4e4", "#eeeeee"]

Mapping of high color (256) indices to hex color values. Ported from the xterm color generation script (xterm defaults). Generated by bin/generate_colors_2.js.

HI2LI = [0, 1, 2, 3, 4, 5, 6, 7, 0, 1, 2, 3, 4, 5, 6, 7, 0, 4, 4, 4, 4, 4, 2, 6, 4, 4, 4, 4, 2, 2, 6, 4, 4, 4, 2, 2, 2, 6, 4, 4, 2, 2, 2, 2, 6, 4, 2, 2, 2, 2, 2, 6, 1, 5, 4, 4, 4, 4, 3, 0, 4, 4, 4, 4, 2, 2, 6, 4, 4, 4, 2, 2, 2, 6, 4, 4, 2, 2, 2, 2, 6, 4, 2, 2, 2, 2, 2, 6, 1, 1, 5, 4, 4, 4, 1, 1, 5, 4, 4, 4, 3, 3, 0, 4, 4, 4, 2, 2, 2, 6, 4, 4, 2, 2, 2, 2, 6, 4, 2, 2, 2, 2, 2, 6, 1, 1, 1, 5, 4, 4, 1, 1, 1, 5, 4, 4, 1, 1, 1, 5, 4, 4, 3, 3, 3, 7, 4, 4, 2, 2, 2, 2, 6, 4, 2, 2, 2, 2, 2, 6, 1, 1, 1, 1, 5, 4, 1, 1, 1, 1, 5, 4, 1, 1, 1, 1, 5, 4, 1, 1, 1, 1, 5, 4, 3, 3, 3, 3, 7, 4, 2, 2, 2, 2, 2, 6, 1, 1, 1, 1, 1, 5, 1, 1, 1, 1, 1, 5, 1, 1, 1, 1, 1, 5, 1, 1, 1, 1, 1, 5, 1, 1, 1, 1, 1, 5, 3, 3, 3, 3, 3, 7, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7]

Mapping of high color (256) indices to low color (8) indices. Generated by bin/generate_colors.rb.

HI2LN = ["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "black", "blue", "blue", "blue", "blue", "blue", "green", "cyan", "blue", "blue", "blue", "blue", "green", "green", "cyan", "blue", "blue", "blue", "green", "green", "green", "cyan", "blue", "blue", "green", "green", "green", "green", "cyan", "blue", "green", "green", "green", "green", "green", "cyan", "red", "magenta", "blue", "blue", "blue", "blue", "yellow", "black", "blue", "blue", "blue", "blue", "green", "green", "cyan", "blue", "blue", "blue", "green", "green", "green", "cyan", "blue", "blue", "green", "green", "green", "green", "cyan", "blue", "green", "green", "green", "green", "green", "cyan", "red", "red", "magenta", "blue", "blue", "blue", "red", "red", "magenta", "blue", "blue", "blue", "yellow", "yellow", "black", "blue", "blue", "blue", "green", "green", "green", "cyan", "blue", "blue", "green", "green", "green", "green", "cyan", "blue", "green", "green", "green", "green", "green", "cyan", "red", "red", "red", "magenta", "blue", "blue", "red", "red", "red", "magenta", "blue", "blue", "red", "red", "red", "magenta", "blue", "blue", "yellow", "yellow", "yellow", "white", "blue", "blue", "green", "green", "green", "green", "cyan", "blue", "green", "green", "green", "green", "green", "cyan", "red", "red", "red", "red", "magenta", "blue", "red", "red", "red", "red", "magenta", "blue", "red", "red", "red", "red", "magenta", "blue", "red", "red", "red", "red", "magenta", "blue", "yellow", "yellow", "yellow", "yellow", "white", "blue", "green", "green", "green", "green", "green", "cyan", "red", "red", "red", "red", "red", "magenta", "red", "red", "red", "red", "red", "magenta", "red", "red", "red", "red", "red", "magenta", "red", "red", "red", "red", "red", "magenta", "red", "red", "red", "red", "red", "magenta", "yellow", "yellow", "yellow", "yellow", "yellow", "white", "black", "black", "black", "black", "black", "black", "black", "black", "black", "black", "black", "black", "white", "white", "white", "white", "white", "white", "white", "white", "white", "white", "white", "white"]

Mapping of high color (256) indices to low color (8) names. Generated by bin/generate_colors.rb.

HI2RGB = [{0, 0, 0}, {205, 0, 0}, {0, 205, 0}, {205, 205, 0}, {0, 0, 238}, {205, 0, 205}, {0, 205, 205}, {229, 229, 229}, {127, 127, 127}, {255, 0, 0}, {0, 255, 0}, {255, 255, 0}, {92, 92, 255}, {255, 0, 255}, {0, 255, 255}, {255, 255, 255}, {0, 0, 0}, {0, 0, 95}, {0, 0, 135}, {0, 0, 175}, {0, 0, 215}, {0, 0, 255}, {0, 95, 0}, {0, 95, 95}, {0, 95, 135}, {0, 95, 175}, {0, 95, 215}, {0, 95, 255}, {0, 135, 0}, {0, 135, 95}, {0, 135, 135}, {0, 135, 175}, {0, 135, 215}, {0, 135, 255}, {0, 175, 0}, {0, 175, 95}, {0, 175, 135}, {0, 175, 175}, {0, 175, 215}, {0, 175, 255}, {0, 215, 0}, {0, 215, 95}, {0, 215, 135}, {0, 215, 175}, {0, 215, 215}, {0, 215, 255}, {0, 255, 0}, {0, 255, 95}, {0, 255, 135}, {0, 255, 175}, {0, 255, 215}, {0, 255, 255}, {95, 0, 0}, {95, 0, 95}, {95, 0, 135}, {95, 0, 175}, {95, 0, 215}, {95, 0, 255}, {95, 95, 0}, {95, 95, 95}, {95, 95, 135}, {95, 95, 175}, {95, 95, 215}, {95, 95, 255}, {95, 135, 0}, {95, 135, 95}, {95, 135, 135}, {95, 135, 175}, {95, 135, 215}, {95, 135, 255}, {95, 175, 0}, {95, 175, 95}, {95, 175, 135}, {95, 175, 175}, {95, 175, 215}, {95, 175, 255}, {95, 215, 0}, {95, 215, 95}, {95, 215, 135}, {95, 215, 175}, {95, 215, 215}, {95, 215, 255}, {95, 255, 0}, {95, 255, 95}, {95, 255, 135}, {95, 255, 175}, {95, 255, 215}, {95, 255, 255}, {135, 0, 0}, {135, 0, 95}, {135, 0, 135}, {135, 0, 175}, {135, 0, 215}, {135, 0, 255}, {135, 95, 0}, {135, 95, 95}, {135, 95, 135}, {135, 95, 175}, {135, 95, 215}, {135, 95, 255}, {135, 135, 0}, {135, 135, 95}, {135, 135, 135}, {135, 135, 175}, {135, 135, 215}, {135, 135, 255}, {135, 175, 0}, {135, 175, 95}, {135, 175, 135}, {135, 175, 175}, {135, 175, 215}, {135, 175, 255}, {135, 215, 0}, {135, 215, 95}, {135, 215, 135}, {135, 215, 175}, {135, 215, 215}, {135, 215, 255}, {135, 255, 0}, {135, 255, 95}, {135, 255, 135}, {135, 255, 175}, {135, 255, 215}, {135, 255, 255}, {175, 0, 0}, {175, 0, 95}, {175, 0, 135}, {175, 0, 175}, {175, 0, 215}, {175, 0, 255}, {175, 95, 0}, {175, 95, 95}, {175, 95, 135}, {175, 95, 175}, {175, 95, 215}, {175, 95, 255}, {175, 135, 0}, {175, 135, 95}, {175, 135, 135}, {175, 135, 175}, {175, 135, 215}, {175, 135, 255}, {175, 175, 0}, {175, 175, 95}, {175, 175, 135}, {175, 175, 175}, {175, 175, 215}, {175, 175, 255}, {175, 215, 0}, {175, 215, 95}, {175, 215, 135}, {175, 215, 175}, {175, 215, 215}, {175, 215, 255}, {175, 255, 0}, {175, 255, 95}, {175, 255, 135}, {175, 255, 175}, {175, 255, 215}, {175, 255, 255}, {215, 0, 0}, {215, 0, 95}, {215, 0, 135}, {215, 0, 175}, {215, 0, 215}, {215, 0, 255}, {215, 95, 0}, {215, 95, 95}, {215, 95, 135}, {215, 95, 175}, {215, 95, 215}, {215, 95, 255}, {215, 135, 0}, {215, 135, 95}, {215, 135, 135}, {215, 135, 175}, {215, 135, 215}, {215, 135, 255}, {215, 175, 0}, {215, 175, 95}, {215, 175, 135}, {215, 175, 175}, {215, 175, 215}, {215, 175, 255}, {215, 215, 0}, {215, 215, 95}, {215, 215, 135}, {215, 215, 175}, {215, 215, 215}, {215, 215, 255}, {215, 255, 0}, {215, 255, 95}, {215, 255, 135}, {215, 255, 175}, {215, 255, 215}, {215, 255, 255}, {255, 0, 0}, {255, 0, 95}, {255, 0, 135}, {255, 0, 175}, {255, 0, 215}, {255, 0, 255}, {255, 95, 0}, {255, 95, 95}, {255, 95, 135}, {255, 95, 175}, {255, 95, 215}, {255, 95, 255}, {255, 135, 0}, {255, 135, 95}, {255, 135, 135}, {255, 135, 175}, {255, 135, 215}, {255, 135, 255}, {255, 175, 0}, {255, 175, 95}, {255, 175, 135}, {255, 175, 175}, {255, 175, 215}, {255, 175, 255}, {255, 215, 0}, {255, 215, 95}, {255, 215, 135}, {255, 215, 175}, {255, 215, 215}, {255, 215, 255}, {255, 255, 0}, {255, 255, 95}, {255, 255, 135}, {255, 255, 175}, {255, 255, 215}, {255, 255, 255}, {8, 8, 8}, {18, 18, 18}, {28, 28, 28}, {38, 38, 38}, {48, 48, 48}, {58, 58, 58}, {68, 68, 68}, {78, 78, 78}, {88, 88, 88}, {98, 98, 98}, {108, 108, 108}, {118, 118, 118}, {128, 128, 128}, {138, 138, 138}, {148, 148, 148}, {158, 158, 158}, {168, 168, 168}, {178, 178, 178}, {188, 188, 188}, {198, 198, 198}, {208, 208, 208}, {218, 218, 218}, {228, 228, 228}, {238, 238, 238}]

Mapping of high color (256) indices to RGB color values. Ported from the xterm color generation script (xterm defaults). Generated by bin/generate_colors_2.js.

HSV_LUT = begin d = Data.new Array(Int32).new(360) do |hue| d.hsv_i(hue) end end

Precomputed #hsv_i for every integer hue 0...360 at full saturation and value (s = v = 1). Index it only with a hue already reduced by % 360; HSV_LUT[h] is then bit-identical to hsv_i(h). A variable s/v needs #hsv_i itself. (Initialized through a throwaway Data since the mixin's methods aren't module methods.)

VERSION = "1.0.1"

Xterm = {"#000000", "#cd0000", "#00cd00", "#cdcd00", "#0000ee", "#cd00cd", "#00cdcd", "#e5e5e5", "#7f7f7f", "#ff0000", "#00ff00", "#ffff00", "#5c5cff", "#ff00ff", "#00ffff", "#ffffff"}

16 XTerm Colors.

(Values taken from X11 sources, mapped to RGB, converted to hex.)

Instance Method Summary

• #adjust_lightness(rgb : Int32, delta : Float64) : Int32

  Moves a color's lightness by delta (positive = lighter, negative = darker), clamped to [0, 1].

• #color_distance(r1, g1, b1, r2, g2, b2)

  Finds color similarity (weighted Euclidean distance, no color-space conversion needed).

• #convert(color : Int)

  Parses a color spec into the native color value: -1 for the terminal default, or a 24-bit 0xRRGGBB integer.

• #convert(color : String)

  Parses a color spec into the native color value: -1 for the terminal default, or a 24-bit 0xRRGGBB integer.

• #convert(color : Tuple | Array)

  Strips the alpha channel off the two hex-with-alpha forms (#rgba, #rrggbbaa), returning the plain #rgb/#rrggbb the parser understands; any other string is returned as-is.

• #darken(rgb : Int32, amount : Float64) : Int32

  Darkens rgb by amount (0..1) of lightness.

• #darker(color : Int, factor : Int = 200) : Int32

  A darker shade of color ↔ Qt's QColor::darker(factor).

• #hex(rgb : Int32) : String

  0xRRGGBB -> "#rrggbb".

• #hex_to_int(hex : String) : Int32

  Converts a hex color value (#abc or #rrggbb) to a 24-bit 0xRRGGBB integer.

• #hex_to_rgb(hex : String)

  Converts hex color value (#col or #color) to {r,g,b}.

• #hsl_to_rgb(h : Float64, s : Float64, l : Float64) : Int32

  {h, s, l} -> 0xRRGGBB (inverse of #rgb_to_hsl).

• #hsv(h : Int | Float, s : Float64 = 1.0, v : Float64 = 1.0) : String

  Converts an HSV color to a #rrggbb hex string.

• #hsv_i(h : Int | Float, s : Float64 = 1.0, v : Float64 = 1.0) : Int32

  Converts an HSV color to a packed 0xRRGGBB integer (24-bit RGB).

• #lighten(rgb : Int32, amount : Float64) : Int32

  Lightens rgb by amount (0..1) of lightness.

• #lighter(color : Int, factor : Int = 150) : Int32

  A lighter shade of color ↔ Qt's QColor::lighter(factor).

• #luminance(rgb : Int32) : Float64

  Relative luminance (sRGB-weighted, 0..1) — how bright a color reads, used to choose a contrasting foreground.

• #match(r1 : Int, g1 : Int, b1 : Int)

  Takes color value and returns index of the nearest/closest matching color in the current palette.

• #match(r1 : String)

  Takes color value and returns index of the nearest/closest matching color in the current palette.

• #match(r1 : Array)

  Takes color value and returns index of the nearest/closest matching color in the current palette.

• #match(r1 : Tuple)

  Takes color value and returns index of the nearest/closest matching color in the current palette.

• #mix(c1 : Int, c2 : Int, alpha = 0.5) : Int32

  Mixes two 24-bit RGB colors in RGB space.

• #palette_to_rgb(idx : Int) : Int32

  Maps a 256-color palette index to its native 24-bit 0xRRGGBB value (used when parsing incoming 38;5;n/ANSI SGR codes into the RGB-native form).

• #parse_hsl_function(value : String) : Int32 | Nil

  Parses a CSS hsl(h, s%, l%) / hsla(...) function body into 0xRRGGBB.

• #parse_rgb_function(value : String) : Int32 | Nil

  Parses a CSS #rgb(r, g, b) / rgba(r, g, b, a) function body (commas or spaces) into 0xRRGGBB.

• #readable_on(bg : Int32, dark : Int32, light : Int32) : Int32

  Picks whichever of dark/light contrasts better against bg.

• #reduce(color, total)

  Converts color into lower/smaller color space.

• #rgb(r : Int, g : Int, b : Int) : Int32

  Packs three 0..255 channel bytes into a 0xRRGGBB color.

• #rgb_channels(rgb : Int) : Tuple(Int32, Int32, Int32)

  Public unpack of a packed 0xRRGGBB integer into its {r, g, b} byte channels — the inverse of #rgb, for callers that hold a packed color and need the individual 0..255 channels.

• #rgb_to_hex(r, g, b)

  Converts RGB to hex color value (#color)

• #rgb_to_hex(r : Array)

  Converts RGB to hex color value (#color)

• #rgb_to_hex(r : Tuple)

  Converts RGB to hex color value (#color)

• #rgb_to_hex(r : Colorize::ColorRGB)

  Converts RGB to hex color value (#color)

• #rgb_to_hsl(rgb : Int32) : Tuple(Float64, Float64, Float64)

  0xRRGGBB -> {h (0..360), s (0..1), l (0..1)}.

• #rgb_to_hsv(rgb : Int32) : Tuple(Float64, Float64, Float64)

  0xRRGGBB -> {h (0..360), s (0..1), v (0..1)}.

• #sgr_color(color : Int, fg : Bool, colors : Int) : String

  Builds the SGR parameter fragment encoding one color for a terminal that supports colors colors, choosing the richest encoding that fits: TrueColor (38;2;r;g;b), 256-color (38;5;n), or 16/8-color ANSI (30..37/90..97).

• #sgr_color_to(io : IO, color : Int, fg : Bool, colors : Int) : Nil

  Allocation-free counterpart of #sgr_color: writes the SGR parameter fragment for one color straight into io rather than returning a fresh String.

• #to_hex2(n)

  Converts number to hex value with 2 places.

• #to_hex4(n)

  Converts number to hex value with 4 places.

Instance Method Detail

reduce(color, @tput.colors)