spruce/box

Boxed and styled multiline terminal output.

A Box is a builder that describes how to frame a block of text: inner padding, outer margin, width and height constraints, horizontal and vertical alignment, foreground and background colors, an optional title, and a border with per-side visibility and colors. Build one with new (a rounded, cyan border with one cell of horizontal padding) or plain (no border, no padding), configure it with the combinators, and render it with render.

import spruce
import spruce/border
import spruce/box
import spruce/style

pub fn main() {
  let context = spruce.detect()

  box.new()
  |> box.title("Release")
  |> box.border(border.Double)
  |> box.border_color(style.Green)
  |> box.padding(top: 1, right: 2, bottom: 1, left: 2)
  |> box.render(context, "spruce 2.0.0\nready to ship", _)
  |> echo
}

Rendered boxes are indented to the context’s depth.

Types

Box

opaque </>

Box rendering options. See the module documentation for the builder.

pub opaque type Box

Values

align

</>

pub fn align(
  box: Box,
  horizontal horizontal: align.Pos,
  vertical vertical: align.Pos,
) -> Box

Align content horizontally within width and vertically within height.

background

</>

pub fn background(box: Box, color: style.Color) -> Box

Set the background color applied to content lines and padding.

border

</>

pub fn border(box: Box, border: border.Border) -> Box

Set the border style. border.Hidden draws no border at all.

border_color

</>

pub fn border_color(box: Box, color: style.Color) -> Box

Set one color for all four border sides.

border_colors

</>

pub fn border_colors(
  box: Box,
  top top: style.Color,
  right right: style.Color,
  bottom bottom: style.Color,
  left left: style.Color,
) -> Box

Set top, right, bottom, and left border colors independently.

border_sides

</>

pub fn border_sides(
  box: Box,
  top top: Bool,
  right right: Bool,
  bottom bottom: Bool,
  left left: Bool,
) -> Box

Set top, right, bottom, and left border visibility independently.

foreground

</>

pub fn foreground(box: Box, color: style.Color) -> Box

Set the foreground color applied to content lines.

height

</>

pub fn height(box: Box, height: Int) -> Box

Constrain content to a line count. Short content is padded with blank lines using vertical alignment; tall content is truncated from the bottom after wrapping.

margin

</>

pub fn margin(
  box: Box,
  top top: Int,
  right right: Int,
  bottom bottom: Int,
  left left: Int,
) -> Box

Set outer margin as top, right, bottom, left cell counts.

new

</>

pub fn new() -> Box

A box with a rounded cyan border, one cell of horizontal padding, and no title, margin, size constraints, or content colors.

padding

</>

pub fn padding(
  box: Box,
  top top: Int,
  right right: Int,
  bottom bottom: Int,
  left left: Int,
) -> Box

Set inner padding as top, right, bottom, left cell counts.

plain

</>

pub fn plain() -> Box

A box with no border and no padding: a bare styled block. Add a border with border to frame it.

print

</>

pub fn print(context: spruce.Spruce, content: String) -> Nil

Render a default box and print it to stdout.

render

</>

pub fn render(
  context: spruce.Spruce,
  content: String,
  box: Box,
) -> String

Render content with the given box.

simple

</>

pub fn simple(context: spruce.Spruce, content: String) -> String

Render content in a default box (new).

title

</>

pub fn title(box: Box, title: String) -> Box

Set the title shown in the top border. Newlines are replaced by spaces. An empty title (the default) draws an unbroken top border. A hidden border or top side does not affect content width.

width

</>

pub fn width(box: Box, width: Int) -> Box

Constrain content to a visual width, wrapping with spruce/align.wrap.