spruce/align

ANSI-aware text geometry: visual length, padding, wrapping, truncation, and multi-line block composition (join_vertical, join_horizontal, place).

Multiline layout treats CRLF pairs as LF line endings and preserves standalone CR characters, blank lines, and trailing newlines. wrap with a non-positive width returns the input unchanged.

Types

A position used for horizontal or vertical alignment.

pub type Pos {
  Start
  Center
  End
}

Constructors

  • Start
  • Center
  • End

Values

pub fn height(text: String) -> Int

Count the number of lines in text.

pub fn join_horizontal(pos: Pos, blocks: List(String)) -> String

Join blocks horizontally, aligning shorter blocks within the tallest block.

pub fn join_vertical(pos: Pos, blocks: List(String)) -> String

Stack blocks vertically, padding every line to the widest visual width.

pub fn pad_center(text: String, width: Int) -> String

Pad text on both sides with spaces until it reaches width visual columns. When an odd number of spaces is needed, the extra space is placed on the right. Text already at or beyond width is returned unchanged.

pub fn pad_left(text: String, width: Int) -> String

Pad text on the left with spaces until it reaches width visual columns. Text already at or beyond width is returned unchanged.

pub fn pad_right(text: String, width: Int) -> String

Pad text on the right with spaces until it reaches width visual columns. Text already at or beyond width is returned unchanged.

pub fn place(
  width width: Int,
  height height: Int,
  horizontal h: Pos,
  vertical v: Pos,
  content content: String,
) -> String

Place content in a region, preserving content larger than the requested size.

pub fn size(text: String) -> #(Int, Int)

Return the widest visual line and the number of lines in text.

pub fn truncate(
  text: String,
  width width: Int,
  ellipsis ellipsis: String,
) -> String

Truncate text to at most width visual columns, appending ellipsis when truncation is needed.

ANSI escape sequences do not count toward the width and are never split. Open SGR styles and OSC 8 hyperlinks are closed before the ellipsis. If ellipsis is wider than width, the ellipsis itself is visibly truncated to fit. Widths less than or equal to zero return an empty string.

pub fn visual_length(text: String) -> Int

The visual length of a string, excluding ANSI escape codes.

BMP emoji such as U+2705 count as two columns, using their Wide (W) property in Unicode 16.0.0.

pub fn wrap(text: String, width: Int) -> String

Wrap text to width visual columns.

ANSI escape sequences do not count toward the width and are never split. Active SGR styles and OSC 8 hyperlinks are closed and reopened at output line boundaries. Recognized SGR settings use category-specific resets, so unrelated styles applied around the wrapped output remain active. Unknown SGR settings require a full reset, which can cancel outer styles. Explicit resets in the input are preserved, including full resets. Bold and dim remain active together until SGR 22 or a full reset clears both. Words longer than width are hard-wrapped at visible column boundaries. Spaces that cause an automatic wrap are discarded without adding blank lines. Physical blank lines, trailing newlines, and spaces that fit are kept. A space-only physical line is limited to width without adding lines. A grapheme wider than width is kept intact on its own line. Widths less than or equal to zero return the input unchanged.

✨ Search Document