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@}

Interface

Spectrum provides two module variants:

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

Terminal capability detection for color support.

Sourcemodule Lexer : module type of Lexer

Lexer for parsing color/style tags and ANSI escape sequences.

Sourcemodule Parser : module type of Parser

Parser for converting lexer output into structured tokens.

Sourcemodule type Printer = sig ... end

Printer module type - provides formatted printing with ANSI color codes.

Sourcemodule type Serializer = sig ... end

Serializer module type - converts parsed tokens to ANSI escape codes.

Sourcemodule Stag : sig ... end

Type-safe semantic tags for programmatic use with Format.

Printer that raises exceptions on invalid color/style tags.

Printer that silently ignores invalid color/style tags (default).

Default printer behavior (equivalent to Noexn).

Includes all functions from Noexn at the top level for convenient access.

include Printer
Sourceval prepare_ppf : Format.formatter -> unit -> unit

Prepare a formatter to handle color tags. Returns a reset function to restore original formatter state.

This enables Spectrum's tag processing on a Format.formatter, allowing you to use @{<tag>content@} syntax in your format strings. The returned function restores the formatter to its original state.

  (* 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 ()
  • returns

    Function to restore the formatter's original state

Sourcemodule Simple : sig ... end

Simple one-shot printing interface that handles formatter setup/teardown.

Sourcemodule Private : sig ... end

Internal modules exposed for testing purposes.