spruce - v2.0.1

spruce/align

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

Types

Pos

</>

A position used for horizontal or vertical alignment.

pub type Pos {
  Start
  Center
  End
}

Constructors 

  • Start
  • Center
  • End

Values

height

</> 
pub fn height(text: String) -> Int

Count the number of lines in text.

join_horizontal

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

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

join_vertical

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

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

pad_center

</> 
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.

pad_left

</> 
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.

pad_right

</> 
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.

place

</> 
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.

size

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

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

truncate

</> 
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.

visual_length

</> 
pub fn visual_length(text: String) -> Int

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

wrap

</> 
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. Words longer than width are hard-wrapped at visible column boundaries. Widths less than or equal to zero return the input unchanged.

✨ Search Document