spruce

spruce, a terminal-UI kit for Gleam.

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

The `Spruce` context

Every render function takes an explicit Spruce value. The context carries four things: the detected color level (so output is plain when color is unsupported), the terminal background hint (light or dark, used for adaptive colors), the symbol mode (Unicode or ASCII glyphs), and the current indent depth (so grouped output nests without any global state).

import spruce

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

Use spruce.no_color() in tests to get deterministic, escape-free output, or spruce.with_color_level(spruce.TrueColor) to force a level.

Types

Background

</>

The terminal background. Adaptive colors (see spruce/style.adaptive) resolve against this, treating Unknown as Dark.

pub type Background {
  Light
  Dark
  Unknown
}

Constructors

```
Light
```
```
Dark
```
```
Unknown
```

ColorLevel

</>

The terminal’s color support level, in ascending order of capability.

pub type ColorLevel {
  NoColor
  Basic
  Ansi256
  TrueColor
}

Constructors

```
NoColor
```
```
Basic
```
```
Ansi256
```
```
TrueColor
```

Spruce

opaque </>

The rendering context. Carries the detected color level, the detected terminal background, the symbol mode, 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 to detect against.

pub type Stream {
  Stdin
  Stdout
  Stderr
}

Constructors

```
Stdin
```
```
Stdout
```
```
Stderr
```

SymbolMode

</>

Glyph rendering mode: Unicode for rich glyphs, Ascii for plain fallbacks. Every renderer that emits icons or bullets consults the context’s mode.

pub type SymbolMode {
  Unicode
  Ascii
}

Constructors

```
Unicode
```
```
Ascii
```

Values

background

</>

pub fn background(context: Spruce) -> Background

Get the detected terminal background of a context.

color_level

</>

pub fn color_level(context: Spruce) -> ColorLevel

Get the color level of a context.

depth

</>

pub fn depth(context: 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: Stream) -> Spruce

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

flat

</>

pub fn flat(context: Spruce) -> Spruce

Return a copy of the context with its indent depth reset to zero. Composing modules that own indentation at their boundary use this so that inner renderers do not double-indent content that the outer module will indent itself.

indent_prefix

</>

pub fn indent_prefix(context: Spruce) -> String

The indentation prefix for the context’s depth: two spaces per level. Block-producing renderers prepend this to every line they emit.

indented

</>

pub fn indented(context: Spruce) -> Spruce

Return a copy of the context with its indent depth increased by one. spruce/output.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(context: Spruce) -> Bool

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

symbol_mode

</>

pub fn symbol_mode(context: Spruce) -> SymbolMode

Get the glyph rendering mode of a context.

with_background

</>

pub fn with_background(
  context: Spruce,
  background: 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: 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.

with_symbol_mode

</>

pub fn with_symbol_mode(
  context: Spruce,
  mode: SymbolMode,
) -> Spruce

Return a copy of the context with an explicit symbol mode. Use Ascii for environments that cannot display Unicode glyphs.

The Spruce context

Constructors

Constructors

Constructors

Constructors

The `Spruce` context