spruce - v1.0.0

spruce

spruce — a terminal-UI kit for Gleam.

spruce renders styled terminal output — colors, boxes, semantic message lines, icons, deterministic hash-colors, ANSI-aware alignment, and grouped/indented output — that automatically respects the terminal’s color support. It is logging-agnostic and targets both Erlang and JavaScript.

The Spruce context

Every render function takes an explicit Spruce value. The context carries two things: the detected color level (so output is plain when color is unsupported) and the current indent depth (so grouped output nests without any global state).

import spruce

pub fn main() {
  let sp = spruce.detect()
  // pass `sp` to render functions in spruce/style, spruce/box, etc.
  echo spruce.supports_color(sp)
}

Use spruce.no_color() in tests to get deterministic, escape-free output.

Types

Background

</>

The terminal background, re-exported from the tty package. One of Light, Dark, or Unknown. Adaptive colors (see spruce/style.Adaptive) resolve against this, treating Unknown as Dark.

pub type Background =
  tty.Background

ColorLevel

</>

The terminal color support level, re-exported from the tty package. One of NoColor, Basic, Ansi256, or TrueColor.

pub type ColorLevel =
  tty.ColorLevel

Spruce

opaque </>

The rendering context. Carries the detected color level, the detected terminal background, and the current indent depth. Construct it with detect, with_color_level, or no_color, and deepen it with indented.

pub opaque type Spruce

Stream

</>

An output stream, re-exported from the tty package. One of Stdin, Stdout, or Stderr.

pub type Stream =
  tty.Stream

Values

background

</> 
pub fn background(sp: Spruce) -> tty.Background

Get the detected terminal background of a context.

color_level

</> 
pub fn color_level(sp: Spruce) -> tty.ColorLevel

Get the color level of a context.

depth

</> 
pub fn depth(sp: Spruce) -> Int

Get the current indent depth of a context (0 at the top level).

detect

</> 
pub fn detect() -> Spruce

Build a context by auto-detecting the color support of standard output.

Detection honors NO_COLOR, FORCE_COLOR, TERM, CI environment hints, and TTY status (via the tty package), falling back to NoColor when uncertain.

detect_stream

</> 
pub fn detect_stream(stream: tty.Stream) -> Spruce

Build a context by auto-detecting the color support of a specific stream.

indented

</> 
pub fn indented(sp: Spruce) -> Spruce

Return a copy of the context with its indent depth increased by one. spruce/group uses this to hand a deeper context to grouped bodies.

no_color

</> 
pub fn no_color() -> Spruce

Build a context that never emits color. All output is plain text. This is the recommended context for deterministic tests.

supports_color

</> 
pub fn supports_color(sp: Spruce) -> Bool

Whether the context will emit any color (i.e. its level is not NoColor).

with_background

</> 
pub fn with_background(
  sp: Spruce,
  background: tty.Background,
) -> Spruce

Return a copy of the context with an explicit terminal background, bypassing detection. Useful for forcing light/dark adaptive colors in tests or honoring a user --background flag.

with_color_level

</> 
pub fn with_color_level(level: tty.ColorLevel) -> Spruce

Build a context with an explicit color level, bypassing detection. Useful for forcing a level in tests or honoring a user --color flag. The background defaults to Unknown (treated as Dark by adaptive colors); override it with with_background.

✨ Search Document