spectrum 0.6.0 · OCaml Package

README

Library for colour and formatting in the terminal.

It's a little DSL which is exposed via OCaml Format module's "semantic tags" feature. String tags are defined for ANSI styles such as bold, underline etc and for named colours from the xterm 256-color palette, as well as 24-bit colours via CSS-style hex codes and RGB or HSL values.

It's inspired by the examples given in "Format Unraveled", a paper by Richard Bonichon & Pierre Weis, which also explains the cleverness behind OCaml's highly type-safe format string system.

Goals

Simple and ergonomic formatting of strings, especially where multiple styles are applied to same line.
Focus on colours and text styling
Support full colour range on modern terminals

Non-goals

Any extended "Terminal UI" kind of features, we're just doing text styling (but hopefully it should fit in fine with Format or Fmt's existing box and table features etc)
Maximum performance: if you are formatting high volumes of logs you may like to look at the alternatoive below. (Performance should be ok but it's not benchmarked and at the end of the day we have to parse the string tags)

Installation

It's released on opam, so:

opam install spectrum

Usage

To use Spectrum we have to configure a pretty-print formatter (type: Format.formatter, often just called a ppf) in order to enable our custom tag handling.

This looks something like:

let reset_ppf = Spectrum.prepare_ppf Format.std_formatter;;
Format.printf "@{<green>%s@}\n" "Hello world 👋";;
(* when you're done with Spectrum printing you can use the returned function
   to restore the original ppf state (Spectrum disabled)... *)
reset_ppf ();;

The pattern is @{<TAG-NAME>CONTENT@}.

So in the example above <green> is matching one of the 256 xterm color names. Tag names are case-insensitive.

Spectrum also provides an "instant gratification" interface, where the prepare/reset of the ppf happens automatically. This looks like:

Spectrum.Simple.printf "@{<green>%s@}\n" "Hello world 👋";;

This is handy when doing ad hoc printing, but bear in mind that it is doing the prepare/reset, as well as flushing the output buffer, every time you call one the methods. For most efficient use in your application it's better to use the explicit prepare_ppf form.

NOTE: Format.sprintf uses its own buffer (not the Format.str_formatter singleton) so AFAICT there is no way for prepare_pff to enable Spectrum with it. This means if you need a styled sprintf you have to use Spectrum.Simple.sprintf, or use the longer way with Format.fprintf and your own buffer described in the Format docs.

Interface

Spectrum provides two versions of the main module:

The default is Spectrum and, like stdlib Format, it will swallow any errors so that invalid tags will simply have no effect on the output string.
Alternatively Spectrum.Exn will raise an exception if your tags are invalid (i.e. malformed or unrecognised colour name, style name).

Both modules expose the same interface:

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

module Simple : sig
  (** equivalent to [Format.printf] *)
  val printf : ('a, Format.formatter, unit, unit) format4 -> 'a

  (** equivalent to [Format.eprintf] *)
  val eprintf : ('a, Format.formatter, unit, unit) format4 -> 'a

  (** equivalent to [Format.sprintf] *)
  val sprintf : ('a, Format.formatter, unit, string) format4 -> 'a
end

As you can see in the examples in the previous section, Spectrum.Simple.printf works just like Format.printf from the OCaml stdlib, and eprintf and sprintf also work just like their Format counterparts.

Capabilities detection

I've ported the logic from the https://github.com/chalk/supports-color/ nodejs lib, which performs some heuristics based on env vars to determine what level of color support is available in the current terminal.

In most cases you can also override the detected level by setting the FORCE_COLOR env var.

The following method is provided:

Spectrum.Capabilities.supported_color_levels () -> color_level_info

type color_level_info = {
  stdout : color_level;
  stderr : color_level;
}

The following levels are recognised:

type color_level =
  | Unsupported (* FORCE_COLOR=0 or FORCE_COLOR=false *)
  | Basic       (* FORCE_COLOR=1 or FORCE_COLOR=true *)
  | Eight_bit   (* FORCE_COLOR=2 *)
  | True_color  (* FORCE_COLOR=3 *)

Unsupported: probably best not to use colors or styling
Basic: supports 16 colors, i.e. the 8 basic colors plus "bright" version of each. They are equivalent to the first eight colours of the xterm 256-color set, with bright version accessed by setting the style to bold. So the available colour name tags are:
- black (with bold will display as: grey)
- maroon (with bold will display as: red)
- green (with bold will display as: lime)
- olive (with bold will display as: yellow)
- navy (with bold will display as: blue)
- purple (with bold will display as: fuchsia)
- teal (with bold will display as: aqua)
- silver (with bold will display as: white)
- grey
- red
- lime
- yellow
- blue
- fuchsia
- aqua
- white
Eight_bit: supports the xterm 256-color palette. Named colours beyond the first 16 above should keep their hue when bolded. CSS 24-bit colours likely won't work.
- NOTE: colour names from that list have been normalised by hyphenating, and where names are repated they are made unique with an alphabetical suffix, e.g. SpringGreen3 is present in Spectrum as:
  - spring-green-3a
  - spring-green-3b
- See the defs at https://github.com/anentropic/ocaml-spectrum/blob/main/lib/lexer.mll#L24
True_color: should support everything

Changelog

0.6.0

finally understood what the interface should be 😅
expose main interface via the parent Spectrum module (instead of Spectrum.Printer as it used to be)
main interface is now Spectrum.prepare_ppf, allowing Spectrum tag handling with the usual Format.printf methods, with the usual buffering behaviour in user's control
"instant gratification" interface (previously our main interface) is now Spectrum.Simple.printf and friends, having the always-flush buffer behaviour
changed the colour names in Basic range to match the list at https://www.ditig.com/256-colors-cheat-sheet
make % char optional in HSL colours, to avoid ugly escaping

0.5.0

support CSS-style rgb(...) and hsl(...) color tags

0.4.0

port the terminal colour capabilities detection from chalk.js

0.3.0

expose separate Exn and Noexn interfaces
fix for buffer interaction issue (tests broke when updating dep Fmt.0.9.0) ...probably affected most uses of sprintf_into
replace sprintf_into kludge with a working sprintf implementation

0.2.0

first viable version

TODOs

tests for all methods (sprintf and the lexer are tested currently), property-based tests
publish the printer and capabilities-detection as separate opam modules?
expose variant types for use with explicit mark_open_stag and close calls?
auto coercion to nearest supported colour, for high res colours on unsupported terminals, as per chalk
- don't output any codes if level is Unsupported

spectrum