`colr`

Color utilities - parse hex and RGB, convert between RGB and HSL, adjust brightness and darkness, invert, greyscale, compute relative luminance and WCAG contrast ratio, generate complementary/triadic/analogous/monochromatic palettes, produce random colors, and emit terminal ANSI escape codes.

Load with: use colr

What this module does

colr provides a complete color toolkit for ilusm programs. You can parse hex strings ("#ff6600" or shorthand "#f60") into RGB objects, convert between RGB and HSL for hue-based manipulations, adjust brightness or darkness by a fixed amount, invert colors, and convert to greyscale.

For accessibility work, clrlm computes the WCAG relative luminance of a color and clrcr gives the contrast ratio between two colors. Palette generators create complementary (2 colors), triadic (3 colors), analogous (3 colors), and monochromatic (N lightness steps) palettes from a base color. ANSI escape code functions colorise terminal output.

Functions are available both as bare names and via the colr namespace object.

Quick example

use colr

# Parse a hex color
rgb = clrhx("#3498db")   # {r:52, g:152, b:219}

# Convert to hex string
hex = clrrg(rgb)         # "#3498db"

# Convert to HSL
hsl = clrhl(rgb)         # {h:204.0, s:0.70, l:0.53}

# Brighten by 30
light = clrbr(rgb, 30)

# Contrast ratio (WCAG)
ratio = clrcr("#ffffff", "#3498db")

# Complementary palette
pair = clrcp("#3498db")  # ["#3498db", "#db7734"]

# Terminal color
prn(clrfg("cyan") + "Hello" + clrrs())

Functions

Parsing and construction

clrhx(hex)

Parses a hex color string ("#rrggbb" or "#rgb") into {r, g, b} integers 0–255. Strips the leading # and expands 3-digit shorthand.

clrmk(r, g, b)

Creates an RGB object from three integer components.

clrrg(rgb)

Converts an RGB object to a lowercase hex string like "#3498db".

RGB ↔ HSL conversion

clrhl(rgb)

Converts an RGB object to HSL. h is in degrees (0–360), s and l are fractions (0–1). Returns {h, s, l}.

clrfh(hsl)

Converts an HSL object back to {r, g, b} integers. Uses the standard hue-to-RGB algorithm. Achromatic colors (s=0) return equal R, G, B.

Adjustments

clrbr(rgb, amount)

Brightens a color by adding amount to each channel, clamping to 255.

clrdk(rgb, amount)

Darkens a color by subtracting amount from each channel, clamping to 0.

clrnv(rgb)

Inverts a color: {255-r, 255-g, 255-b}.

clrgr(rgb)

Converts to greyscale using luminance weights: v = 0.299·r + 0.587·g + 0.114·b.

Accessibility

clrlm(rgb)

Computes the WCAG relative luminance (0–1) of a color. Applies gamma correction per the WCAG 2.x formula.

clrcr(color1, color2)

Computes the WCAG contrast ratio between two colors. Accepts hex strings or RGB objects. Returns a value between 1 (no contrast) and 21 (black on white). WCAG AA requires ≥4.5 for normal text.

Palettes

clrcp(base)

Returns a 2-color complementary palette - the base color and its opposite (hue + 180°).

clrtr(base)

Returns a 3-color triadic palette - base, base + 120°, base + 240°.

clran(base)

Returns a 3-color analogous palette - base − 30°, base, base + 30°.

clrmn(base, n)

Returns an N-step monochromatic palette (default 5) - the base hue and saturation at evenly spaced lightness values from 0.1 to 0.9.

clrrd()

Generates a random hex color using uniform random R, G, B values from det.detmi.

Terminal ANSI colors

clrfg(name)

Returns the ANSI foreground escape for a color name: "red", "green", "yellow", "blue", "magenta", "cyan", "white", "black". Unknown names return the default foreground reset.

clrbg(name)

Same as clrfg but for background colors.

clrrs()

Returns the ANSI reset escape (\x1b[0m).

clrbd() / clrdm() / clrit() / clrul()

Bold, dim, italic, and underline ANSI escape codes.

clrwp(text, fg)

Wraps text with a named foreground color and auto-reset.

clrwb(text, fg, bg)

Wraps text with named foreground and background colors and auto-reset.

`colr` namespace aliases

All functions are also available via the colr object: colr.hex, colr.rgb, colr.str, colr.hsl, colr.fhsl, colr.brt, colr.drk, colr.inv, colr.gry, colr.lum, colr.ctr, colr.comp, colr.tri, colr.ana, colr.mono, colr.rnd, colr.fg, colr.bg, colr.rst, colr.wrap, colr.col.

Notes

All palette functions accept either a hex string or an RGB object as the base color.
Requires trl, txt, mth, and det.