spruce/style

Composable ANSI styling helpers.

A Style is an immutable value built with new and refined through piped combinators such as fg, bold, and underline. Apply it to text with render, which downgrades or drops colors to match the context’s color level and resolves adaptive colors against its background.

import spruce
import spruce/style

pub fn main() {
  let sp = spruce.detect()
  let heading = style.new() |> style.fg(style.Cyan) |> style.bold
  echo style.render(sp, heading, "Hello")
}

Types

Color

</>

A color usable as a foreground or background.

The named constructors map to the 16 standard ANSI colors. Rgb, Hex, and Ansi256 give finer control and are downgraded to the nearest representable color when the terminal lacks support. Complete and Adaptive select a color based on the color level and terminal background respectively (see complete and adaptive).

pub type Color {
  Black
  Red
  Green
  Yellow
  Blue
  Magenta
  Cyan
  White
  Gray
  BrightRed
  BrightGreen
  BrightYellow
  BrightBlue
  BrightMagenta
  BrightCyan
  BrightWhite
  Rgb(r: Int, g: Int, b: Int)
  Hex(value: Int)
  Ansi256(index: Int)
  Complete(ansi: Color, ansi256: Color, truecolor: Color)
  Adaptive(light: Color, dark: Color)
}

Constructors

```
Black
```
```
Red
```
```
Green
```
```
Yellow
```
```
Blue
```
```
Magenta
```
```
Cyan
```
```
White
```
```
Gray
```
```
BrightRed
```
```
BrightGreen
```
```
BrightYellow
```
```
BrightBlue
```
```
BrightMagenta
```
```
BrightCyan
```
```
BrightWhite
```
```
Rgb(r: Int, g: Int, b: Int)
```
```
Hex(value: Int)
```
```
Ansi256(index: Int)
```

Complete(ansi: Color, ansi256: Color, truecolor: Color)

```
Adaptive(light: Color, dark: Color)
```

Style

opaque </>

An immutable set of text attributes (colors and SGR flags). Build one with new and the combinators in this module, then apply it with render.

pub opaque type Style

Values

adaptive

</>

pub fn adaptive(light light: Color, dark dark: Color) -> Color

Build a color that adapts to the terminal background: light is used on a light background, dark on a dark (or Unknown) background. Each side may be any Color, including complete, so this also covers “complete-adaptive” colors. Resolved against spruce.background at render.

bg

</>

pub fn bg(style: Style, color: Color) -> Style

Set the background color.

bold

</>

pub fn bold(style: Style) -> Style

Enable bold text.

complete

</>

pub fn complete(
  ansi ansi: Color,
  ansi256 ansi256: Color,
  truecolor truecolor: Color,
) -> Color

Build a color with an explicit variant per color level: ansi for basic terminals, ansi256 for 256-color, and truecolor for truecolor. The level detected in the context selects which variant is used at render time.

dim

</>

pub fn dim(style: Style) -> Style

Enable dim (faint) text.

faint

</>

pub fn faint(style: Style) -> Style

Enable faint text. This is an alias for dim.

fg

</>

pub fn fg(style: Style, color: Color) -> Style

Set the foreground (text) color.

inline

</>

pub fn inline(style: Style) -> Style

Collapse newlines in the text to single spaces when rendering, keeping a styled value on one line.

italic

</>

pub fn italic(style: Style) -> Style

Enable italic text.

new

</>

pub fn new() -> Style

Create an empty style with no color and no attributes set.

render

</>

pub fn render(
  sp: spruce.Spruce,
  style: Style,
  text: String,
) -> String

Apply a style to text, returning the styled string.

When the context does not support color, all color and attribute styling is dropped (only the inline transform is applied). Colors the terminal cannot represent are downgraded to the nearest available color, and Adaptive colors are resolved against the context’s background.

reverse

</>

pub fn reverse(style: Style) -> Style

Enable reverse video, swapping the foreground and background colors.

strikethrough

</>

pub fn strikethrough(style: Style) -> Style

Enable strikethrough text.

underline

</>

pub fn underline(style: Style) -> Style

Enable underlined text.