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