Module SpectrumSource

Colour and formatting for terminal output.

Spectrum integrates ANSI color and style formatting with OCaml's Format semantic tags. String tags are defined for ANSI styles (bold, underline, etc.) and named colours from the xterm 256-color palette, plus 24-bit colours via CSS-style hex codes and RGB or HSL values.

Terminal capabilities are detected automatically and colours are quantized to match what the terminal supports, using perceptually accurate LAB color space distance calculations.

Basic Usage

  (* Prepare a formatter to handle color tags *)
  let reset = Spectrum.prepare_ppf Format.std_formatter in
  let () = Format.printf "@{<green>Hello@} @{<bold>world@}@." in
  reset ()

  (* Or use the Simple API for one-off printing *)
  let () = Spectrum.Simple.printf "@{<green>Hello@} @{<bold>world@}@."

Tag syntax: @{<TAG>content@}

• Named colors: @{<green>text@}, @{<dark-orange>text@}
• Hex colors: @{<#ff5733>text@}, @{<#f00>text@}
• RGB: @{<rgb(255 87 51)>text@}
• HSL: @{<hsl(60 100 50)>text@}
• Styles: @{<bold>text@}, @{<underline>text@}, @{<italic>text@}, @{<overline>text@}
• Qualifiers: @{<bg:red>text@}, @{<fg:blue>text@}
• Compound: @{<bold,bg:red,yellow>text@}

Interface

Spectrum provides two module variants:

• Exn raises exceptions on invalid color/style tags
• Noexn silently ignores invalid tags (default)

The default top-level interface (just Spectrum.xyz) is equivalent to Noexn. Both expose Printer, which includes prepare_ppf and the Printer.Simple convenience module.

Note: Format.sprintf uses its own buffer, so you must use Simple.sprintf for styled sprintf, or create your own buffer with Format.fprintf.

See Also

• GitHub repository
• Spectrum_tools for color conversion utilities
• Spectrum_palettes for pre-generated palette modules

  (* Basic usage with stdout *)
  let reset = Spectrum.prepare_ppf Format.std_formatter in
  Format.printf "@{<green>Success:@} Operation completed@.";
  Format.printf "@{<bold>%d@} items processed@." 42;
  reset ()

  (* Using with a custom formatter *)
  let buffer = Buffer.create 256 in
  let fmt = Format.formatter_of_buffer buffer in
  let reset = Spectrum.prepare_ppf fmt in
  Format.fprintf fmt "@{<red>Error:@} Something went wrong@.";
  Format.pp_print_flush fmt ();
  reset ();
  let result = Buffer.contents buffer in
  Printf.printf "Captured: %s\n" result

  (* Multiple formatters simultaneously *)
  let reset_out = Spectrum.prepare_ppf Format.std_formatter in
  let reset_err = Spectrum.prepare_ppf Format.err_formatter in
  Format.printf "@{<green>Info:@} Starting process@.";
  Format.eprintf "@{<yellow>Warning:@} Low memory@.";
  reset_out ();
  reset_err ()