index (spectrum.index)

Overview

Spectrum provides ANSI color and style formatting integrated with OCaml's Format module using semantic tags. It supports named colours from the xterm 256-color palette, CSS-style hex codes, and RGB or HSL values.

Terminal capabilities are detected automatically and colours are quantized to the nearest match using LAB color space distance.

opam install spectrum

Spectrum.Simple.printf "@{<green>Hello@} @{<bold>world@}!@."

Documentation

Tutorial

getting_started — Install Spectrum, write your first colored output, learn the tag syntax step by step.

Tag Syntax Reference

The pattern is @{<TAG-NAME>CONTENT@}. Tags are case-insensitive and can be nested arbitrarily.

Colors

Named: @{<green>text@}, @{<dark-orange>text@} — all 256 xterm color names
Hex: @{<#f0c090>text@}, @{<#f00>text@} — CSS-style 3 or 6 digit hex codes
RGB: @{<rgb(240 192 144)>text@} — CSS-style with optional commas
HSL: @{<hsl(60 100 50)>text@} — hue (degrees), saturation, lightness; % sign optional

Styles

bold, dim, italic, underline, blink, rapid-blink, inverse, hidden, strikethru, overline

Qualifiers and Compound Tags

Background: @{<bg:#f00>text@}
Explicit foreground: @{<fg:blue>text@}
Compound: @{<bold,bg:red,yellow>text@} — comma-separated list

How-to Guides

custom_palettes — Define a custom palette for terminals with non-standard color mappings (advanced, rarely needed)

Explanation

color_quantization — How Spectrum matches colors to terminal capabilities, why LAB color space, the package architecture

API Reference

Spectrum provides two module variants:

Spectrum.Exn — raises exceptions on invalid color/style tags
Spectrum.Noexn — silently ignores invalid tags (default, also available as just Spectrum)

Both expose the same interface:

val prepare_ppf : Format.formatter -> unit -> unit

module Simple : sig
  val printf : ('a, Format.formatter, unit, unit) format4 -> 'a
  val eprintf : ('a, Format.formatter, unit, unit) format4 -> 'a
  val sprintf : ('a, Format.formatter, unit, string) format4 -> 'a
end

Spectrum.Simple.printf handles formatter setup/teardown automatically. For repeated printing, use Spectrum.prepare_ppf with the standard Format functions.

For programmatic (non-string) tag construction, see Spectrum.Stag.

Note: Format.sprintf uses its own buffer, so you must use Spectrum.Simple.sprintf for styled sprintf, or create your own buffer with Format.fprintf as described in the Format docs.

Terminal Capabilities

Spectrum detects terminal color support and quantizes accordingly:

True_color — 24-bit RGB, colors used exactly
Eight_bit — 256 colors, quantized to xterm palette
Basic — 16 colors, quantized to ANSI-16
Unsupported — same as Basic

let info = Spectrum.Capabilities.supported_color_levels () in
match info.stdout with
| True_color -> Printf.printf "24-bit color\n"
| Eight_bit -> Printf.printf "256 colors\n"
| Basic -> Printf.printf "16 colors\n"
| Unsupported -> Printf.printf "No color support\n"

Override with FORCE_COLOR=0|1|2|3. See Spectrum_capabilities.Capabilities for details, or color_quantization for how quantization works.

Libraries

Spectrum — Main library with formatting functions
Spectrum_capabilities — Terminal color capability detection (standalone, zero deps on rest of Spectrum)
Spectrum_tools — Color conversion utilities and terminal queries
Spectrum_palettes — Pre-generated palette modules (Basic, Xterm256)
Spectrum_palette_ppx — PPX extension for custom palette generation

Project

GitHub repository

Spectrum - Color and Formatting for Terminal Output