packages /
term 0.1.0
Terminal output: ANSI colors and styles (16, 256 and 24-bit color), stripping escapes, ANSI-aware width and padding, tables, progress bars, spinners, cursor ...
/// Terminal output: ANSI colors and styles (16, 256 and 24-bit color), stripping escapes,
/// ANSI-aware width and padding, tables, progress bars, spinners, cursor control and
/// hyperlinks. Everything builds strings and is pure, except `enabled`, `println`, `eprintln`
/// and `columns`, which use `env` to honour `NO_COLOR`, `FORCE_COLOR` and whether output is a
/// terminal.
let ESC = "\u{1b}"
let CSI = "\u{1b}["
// ---- colors and styles ----
/// A foreground or background color. `Default` is the terminal's own color; `Idx` is the
/// 256-color palette (0-255); `Rgb` is 24-bit true color (0-255 each).
pub enum Color {
Default,
Black,
Red,
Green,
Yellow,
Blue,
Magenta,
Cyan,
White,
BrightBlack,
BrightRed,
BrightGreen,
BrightYellow,
BrightBlue,
BrightMagenta,
BrightCyan,
BrightWhite,
Idx(n: int),
Rgb(r: int, g: int, b: int),
}
/// A set of text attributes. Build one from `style()` with the chainable setters:
/// `term.style().bold().fg(term.Red)`.
pub struct Style {
fg: Color,
bg: Color,
bold: bool,
dim: bool,
italic: bool,
underline: bool,
inverse: bool,
strike: bool,
}
/// No attributes: `paint(s, style()) == s`.
pub fn style(): Style = Style {
fg: Default,
bg: Default,
bold: false,
dim: false,
italic: false,
underline: false,
inverse: false,
strike: false,
}
pub fn fg(st: Style, c: Color): Style = Style { fg: c, ..st }
pub fn bg(st: Style, c: Color): Style = Style { bg: c, ..st }
pub fn bold(st: Style): Style = Style { bold: true, ..st }
pub fn dim(st: Style): Style = Style { dim: true, ..st }
pub fn italic(st: Style): Style = Style { italic: true, ..st }
pub fn underline(st: Style): Style = Style { underline: true, ..st }
pub fn inverse(st: Style): Style = Style { inverse: true, ..st }
pub fn strike(st: Style): Style = Style { strike: true, ..st }
fn base(c: Color): int? = match c {
Black => some(0)
Red => some(1)
Green => some(2)
Yellow => some(3)
Blue => some(4)
Magenta => some(5)
Cyan => some(6)
White => some(7)
BrightBlack => some(60)
BrightRed => some(61)
BrightGreen => some(62)
BrightYellow => some(63)
BrightBlue => some(64)
BrightMagenta => some(65)
BrightCyan => some(66)
BrightWhite => some(67)
_ => none
}
fn byte(n: int): int = if n < 0 { 0 } else if n > 255 { 255 } else { n }
// The SGR parameters for color `c`, where `at` is 30 (foreground) or 40 (background).
fn color_params(c: Color, at: int): [str] = match c {
Default => []
Idx(n) => ["{at + 8}", "5", "{byte(n)}"]
Rgb(r, g, b) => ["{at + 8}", "2", "{byte(r)}", "{byte(g)}", "{byte(b)}"]
_ => ["{at + base(c)!}"]
}
/// The escape sequence that turns `st` on ("" for `style()`).
pub fn codes(st: Style): str {
var ps: [str] = []
if st.bold { ps.push("1") }
if st.dim { ps.push("2") }
if st.italic { ps.push("3") }
if st.underline { ps.push("4") }
if st.inverse { ps.push("7") }
if st.strike { ps.push("9") }
ps = ps + color_params(st.fg, 30) + color_params(st.bg, 40)
if ps.len() == 0 { "" } else { CSI + ps.join(";") + "m" }
}
/// Resets every attribute.
pub let RESET = "\u{1b}[0m"
/// `s` in style `st`, followed by a reset. Resets inside `s` (from nested `paint` calls) turn
/// `st` back on, so `paint("a " + red("b") + " c", style().bold())` keeps " c" bold.
pub fn paint(s: str, st: Style): str {
let on = codes(st)
if on == "" || s == "" { return s }
// a reset already at the end needs no re-enable before ours
let inner = if s.ends_with(RESET) { s[0..s.len() - RESET.len()] } else { s }
on + inner.replace(RESET, RESET + on) + RESET
}
/// `s` in color `c`.
pub fn fg(s: str, c: Color): str = paint(s, style().fg(c))
/// `s` on background `c`.
pub fn bg(s: str, c: Color): str = paint(s, style().bg(c))
pub fn bold(s: str): str = paint(s, style().bold())
pub fn dim(s: str): str = paint(s, style().dim())
pub fn italic(s: str): str = paint(s, style().italic())
pub fn underline(s: str): str = paint(s, style().underline())
pub fn inverse(s: str): str = paint(s, style().inverse())
pub fn strike(s: str): str = paint(s, style().strike())
pub fn black(s: str): str = fg(s, Black)
pub fn red(s: str): str = fg(s, Red)
pub fn green(s: str): str = fg(s, Green)
pub fn yellow(s: str): str = fg(s, Yellow)
pub fn blue(s: str): str = fg(s, Blue)
pub fn magenta(s: str): str = fg(s, Magenta)
pub fn cyan(s: str): str = fg(s, Cyan)
pub fn white(s: str): str = fg(s, White)
pub fn gray(s: str): str = fg(s, BrightBlack)
pub enum ColorErr { Unknown(name: str) }
pub fn message(e: ColorErr): str = match e {
Unknown(n) =>
"unknown color `{n}` (want a name like `red` or `bright-blue`, `#rrggbb`, `#rgb` or 0-255)"
}
/// A color from its name (`red`, `bright-blue`, `bright_blue`, `gray`/`grey`, `default`, case
/// ignored), a hex string (`#ff8800`, `#f80`) or a 256-palette index (`"208"`).
pub fn color(name: str): Color!ColorErr {
let n = name.trim().lower().replace("_", "-").replace(" ", "-")
match n {
"default" => Default
"black" => Black
"red" => Red
"green" => Green
"yellow" => Yellow
"blue" => Blue
"magenta" => Magenta
"cyan" => Cyan
"white" => White
"gray" => BrightBlack
"grey" => BrightBlack
"bright-black" => BrightBlack
"bright-red" => BrightRed
"bright-green" => BrightGreen
"bright-yellow" => BrightYellow
"bright-blue" => BrightBlue
"bright-magenta" => BrightMagenta
"bright-cyan" => BrightCyan
"bright-white" => BrightWhite
"#" + hex => from_hex(hex) else fail(Unknown(name))
_ => {
let i = int.parse(n) else fail(Unknown(name))
if i < 0 || i > 255 { fail(Unknown(name)) }
Idx(i)
}
}
}
fn hex_digit(c: char): int? = if c >= '0' && c <= '9' {
some(int(c) - int('0'))
} else if c >= 'a' && c <= 'f' {
some(int(c) - int('a') + 10)
} else {
none
}
fn from_hex(h: str): Color? {
var ds: [int] = []
for c in h.chars() { ds.push(hex_digit(c)?) }
match ds.len() {
3 => some(Rgb(ds[0] * 17, ds[1] * 17, ds[2] * 17))
6 => some(Rgb(ds[0] * 16 + ds[1], ds[2] * 16 + ds[3], ds[4] * 16 + ds[5]))
_ => none
}
}
// ---- stripping and measuring ----
/// `s` without ANSI escape sequences: CSI (`ESC [ ... final`, colors and cursor moves), OSC
/// (`ESC ] ... BEL` or `ESC ] ... ESC \`, titles and hyperlinks) and two-char `ESC x`.
pub fn strip(s: str): str {
if !s.contains(ESC) { return s }
let cs = s.chars()
var out: [char] = []
var i = 0
while i < cs.len() {
let c = cs[i]
if c != '\u{1b}' {
out.push(c)
i += 1
continue
}
i += 1
if i >= cs.len() { break }
let k = cs[i]
i += 1
if k == '[' {
// parameter and intermediate bytes, then one final byte in @..~
while i < cs.len() && !(cs[i] >= '@' && cs[i] <= '~') { i += 1 }
i += 1
} else if k == ']' {
while i < cs.len() {
if cs[i] == '\u{7}' {
i += 1
break
}
if cs[i] == '\u{1b}' && i + 1 < cs.len() && cs[i + 1] == '\\' {
i += 2
break
}
i += 1
}
}
}
str(out)
}
/// Terminal columns `s` takes once escapes are removed (CJK and emoji count 2).
pub fn width(s: str): int = text.width(strip(s))
fn spaces(n: int): str = if n > 0 { " ".repeat(n) } else { "" }
/// Pads `s` with spaces on the right to `w` columns, ignoring escapes.
pub fn pad_right(s: str, w: int): str = s + spaces(w - width(s))
/// Pads `s` with spaces on the left to `w` columns, ignoring escapes.
pub fn pad_left(s: str, w: int): str = spaces(w - width(s)) + s
/// Centers `s` in `w` columns (an odd extra space goes on the right), ignoring escapes.
pub fn center(s: str, w: int): str {
let extra = w - width(s)
if extra <= 0 { return s }
spaces(extra / 2) + s + spaces(extra - extra / 2)
}
// ---- output ----
/// Whether colored output should go to stdout: false when `NO_COLOR` is set and non-empty,
/// true when `FORCE_COLOR` is set and isn't "0", else true when stdout is a terminal and `TERM`
/// isn't `dumb`. (https://no-color.org)
pub fn enabled(): bool uses env = enabled(1)
/// As `enabled()`, for file descriptor `fd` (1 stdout, 2 stderr).
pub fn enabled(fd: int): bool uses env {
if (env.get("NO_COLOR") else "") != "" { return false }
match env.get("FORCE_COLOR") {
some(v) => return v != "0"
none => {}
}
env.is_terminal(fd) && env.get("TERM") != some("dumb")
}
/// Prints `s`, with its escapes stripped when color is off for stdout (see `enabled`).
pub fn println(s: str) uses env = print(if enabled(1) { s } else { strip(s) })
/// Prints `s` to stderr, with its escapes stripped when color is off for stderr.
pub fn eprintln(s: str) uses env = eprint(if enabled(2) { s } else { strip(s) })
/// The terminal's width in columns, else `$COLUMNS`, else 80.
pub fn columns(): int uses env = env.columns() else 80
// ---- cursor and screen ----
/// Moves the cursor to the start of the line and clears it: print this before redrawing a
/// progress line.
pub let CLEAR_LINE = "\r\u{1b}[2K"
/// Clears the screen and moves the cursor to the top left.
pub let CLEAR_SCREEN = "\u{1b}[2J\u{1b}[H"
pub let HIDE_CURSOR = "\u{1b}[?25l"
pub let SHOW_CURSOR = "\u{1b}[?25h"
/// Moves the cursor up `n` lines ("" for `n <= 0`).
pub fn up(n: int): str = if n > 0 { CSI + "{n}A" } else { "" }
/// Moves the cursor down `n` lines.
pub fn down(n: int): str = if n > 0 { CSI + "{n}B" } else { "" }
/// Moves the cursor right `n` columns.
pub fn right(n: int): str = if n > 0 { CSI + "{n}C" } else { "" }
/// Moves the cursor left `n` columns.
pub fn left(n: int): str = if n > 0 { CSI + "{n}D" } else { "" }
/// Moves the cursor to `row`, `col` (1-based).
pub fn goto(row: int, col: int): str = CSI + "{row};{col}H"
/// Sets the terminal window's title.
pub fn title(s: str): str = ESC + "]0;" + s + "\u{7}"
/// A clickable hyperlink (OSC 8). Terminals without support show just `label`.
pub fn link(label: str, url: str): str =
ESC + "]8;;" + url + ESC + "\\" + label + ESC + "]8;;" + ESC + "\\"
// ---- progress ----
let EIGHTHS = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"]
/// A progress bar `w` columns wide for `done` of `total`, drawn with eighth-blocks:
/// `bar(1, 3, 10) == "███▎ "`. `done` is clamped to 0..total; a `total` of 0 is full.
pub fn bar(done: int, total: int, w: int): str {
if w <= 0 { return "" }
let eighths = if total <= 0 { w * 8 } else { w * 8 * clamp(done, 0, total) / total }
let full = eighths / 8
let part = EIGHTHS[eighths % 8]
let used = full + if part == "" { 0 } else { 1 }
"█".repeat(full) + part + spaces(w - used)
}
fn clamp(x: int, lo: int, hi: int): int = if x < lo { lo } else if x > hi { hi } else { x }
/// The whole percentage of `done` out of `total`, 0-100 (100 when `total` is 0).
pub fn percent(done: int, total: int): int = if total <= 0 {
100
} else {
100 * clamp(done, 0, total) / total
}
/// A one-line progress display: `label [bar] 42% (21/50)`, `w` columns wide in all (the bar
/// takes what the rest leaves, at least 10). Start it with `CLEAR_LINE` to redraw in place.
pub fn progress(label: str, done: int, total: int, w: int): str {
let tail = " {percent(done, total):>3}% ({clamp(done, 0, total)}/{total})"
let head = if label == "" { "" } else { label + " " }
let bw = w - width(head) - width(tail) - 2
let bw2 = if bw < 10 { 10 } else { bw }
head + "[" + bar(done, total, bw2) + "]" + tail
}
let SPIN = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
/// Frame `i` of a braille spinner (any `i`, it wraps).
pub fn spinner(i: int): str = SPIN[((i % SPIN.len()) + SPIN.len()) % SPIN.len()]
// ---- tables ----
pub enum Align { Left, Right, Center }
/// How a table is drawn. `Rounded` and `Sharp` use box-drawing lines, `Ascii` uses `+-|`,
/// `Plain` separates columns with two spaces and underlines the header with nothing, and
/// `Markdown` gives a GitHub-flavored markdown table.
pub enum Border { Rounded, Sharp, Ascii, Plain, Markdown }
/// A table to render. Cells may contain escapes (they don't count toward widths) and line
/// breaks (a cell spans several lines). Rows shorter than the header are padded with empty
/// cells. `align` gives each column's alignment; missing entries are `Left`.
pub struct Table { header: [str], rows: [[str]], align: [Align], border: Border }
/// A `Rounded`, left-aligned table. An empty `header` draws no header row.
pub fn table(header: [str], rows: [[str]]): Table =
Table { header, rows, align: [], border: Rounded }
pub fn align(t: Table, a: [Align]): Table = Table { align: a, ..t }
pub fn border(t: Table, b: Border): Table = Table { border: b, ..t }
/// So `"{t}"` and `print(t)` render the table.
pub fn show(t: Table): str = render(t)
struct Box {
tl: str,
tm: str,
tr: str,
ml: str,
mm: str,
mr: str,
bl: str,
bm: str,
br: str,
h: str,
v: str,
}
fn box_of(b: Border): Box = match b {
Rounded => Box {
tl: "╭",
tm: "┬",
tr: "╮",
ml: "├",
mm: "┼",
mr: "┤",
bl: "╰",
bm: "┴",
br: "╯",
h: "─",
v: "│",
}
Sharp => Box {
tl: "┌",
tm: "┬",
tr: "┐",
ml: "├",
mm: "┼",
mr: "┤",
bl: "└",
bm: "┴",
br: "┘",
h: "─",
v: "│",
}
_ => Box {
tl: "+",
tm: "+",
tr: "+",
ml: "+",
mm: "+",
mr: "+",
bl: "+",
bm: "+",
br: "+",
h: "-",
v: "|",
}
}
fn align_at(t: Table, i: int): Align = t.align.get(i) else Left
fn fit(s: str, w: int, a: Align): str = match a {
Left => pad_right(s, w)
Right => pad_left(s, w)
Center => center(s, w)
}
// Each logical row as physical lines: a list of lines, each a list of cells.
fn row_lines(cells: [str], n: int): [[str]] {
var parts: [[str]] = []
var h = 1
for i in 0..n {
let c = cells.get(i) else ""
let ls = if c == "" { [""] } else { c.split("\n") }
if ls.len() > h { h = ls.len() }
parts.push(ls)
}
var out: [[str]] = []
for j in 0..h { out.push(parts.map(ls => ls.get(j) else "")) }
out
}
/// Draws the table as lines joined by `\n` (no trailing newline).
pub fn render(t: Table): str {
var n = t.header.len()
for r in t.rows { if r.len() > n { n = r.len() } }
if n == 0 { return "" }
let head = if t.header.len() == 0 { [] } else { row_lines(t.header, n) }
let body = t.rows.map(r => row_lines(r, n))
var ws: [int] = []
for i in 0..n { ws.push(if t.border == Markdown { 3 } else { 1 }) }
for line in head + body.flat_map(x => x) {
for i, c in line { if width(c) > ws[i] { ws[i] = width(c) } }
}
let fmt = (line: [str]) => line.enum().map((i, c) => fit(c, ws[i], align_at(t, i)))
var out: [str] = []
match t.border {
Plain => {
for line in head { out.push(fmt(line).join(" ") |> rtrim) }
for r in body { for line in r { out.push(fmt(line).join(" ") |> rtrim) } }
}
Markdown => {
let hd = if head.len() == 0 { [ws.map(w => "")] } else { head }
for line in hd { out.push("| " + fmt(line).join(" | ") + " |") }
out.push("|" + ws.enum().map((i, w) => md_rule(w, align_at(t, i))).join("|") + "|")
for r in body {
for line in r { out.push("| " + fmt(line).map(md_escape).join(" | ") + " |") }
}
}
_ => {
let b = box_of(t.border)
let rule = (l: str, m: str, r: str) => l + ws.map(w => b.h.repeat(w + 2)).join(m) + r
let row = (line: [str]) => b.v + " " + fmt(line).join(" " + b.v + " ") + " " + b.v
out.push(rule(b.tl, b.tm, b.tr))
for line in head { out.push(row(line)) }
if head.len() > 0 && body.len() > 0 { out.push(rule(b.ml, b.mm, b.mr)) }
for r in body { for line in r { out.push(row(line)) } }
out.push(rule(b.bl, b.bm, b.br))
}
}
out.join("\n")
}
fn md_rule(w: int, a: Align): str = match a {
Left => " " + "-".repeat(w) + " "
Right => " " + "-".repeat(w - 1) + ": "
Center => " :" + "-".repeat(w - 2) + ": "
}
fn rtrim(s: str): str {
var cs = s.chars()
while cs.len() > 0 && cs[cs.len() - 1] == ' ' { cs.pop() }
str(cs)
}
fn md_escape(s: str): str = s.replace("|", "\\|")
// ---- tests ----
test "codes and paint" {
assert codes(style()) == ""
assert codes(style().bold().fg(Red)) == "\u{1b}[1;31m"
assert codes(style().fg(BrightBlue).bg(Idx(208))) == "\u{1b}[94;48;5;208m"
assert codes(style().fg(Rgb(255, 128, 0))) == "\u{1b}[38;2;255;128;0m"
assert codes(style().fg(Rgb(300, -1, 7))) == "\u{1b}[38;2;255;0;7m"
assert red("x") == "\u{1b}[31mx\u{1b}[0m"
assert paint("", style().bold()) == ""
assert bold(green("ok")) == "\u{1b}[1m\u{1b}[32mok\u{1b}[0m"
assert paint("x", style()) == "x"
// a nested reset turns the outer style back on
assert bold("a " + red("b") + " c") == "\u{1b}[1ma \u{1b}[31mb\u{1b}[0m\u{1b}[1m c\u{1b}[0m"
}
test "color names" {
assert color("red")? == Red
assert color(" Bright_Blue ")? == BrightBlue
assert color("grey")? == BrightBlack
assert color("#ff8800")? == Rgb(255, 136, 0)
assert color("#F80")? == Rgb(255, 136, 0)
assert color("208")? == Idx(208)
assert color("256") is err(Unknown(_))
assert color("#12345") is err(Unknown(_))
assert color("chartreuse") is err(Unknown("chartreuse"))
match color("x") {
err(e) => assert message(e).starts_with("unknown color `x`")
ok(_) => fail("parsed x")
}
}
test "strip and width" {
assert strip("plain") == "plain"
assert strip(bold(red("hi")) + "!") == "hi!"
assert strip(link("docs", "https://x.dev")) == "docs"
assert strip(title("t") + "a") == "a"
assert strip(CLEAR_LINE + up(2) + "z" + HIDE_CURSOR) == "\rz"
assert strip("a\u{1b}") == "a"
assert width(green("日本")) == 4
assert pad_right(red("ab"), 4) == red("ab") + " "
assert pad_left("ab", 4) == " ab"
assert center("ab", 5) == " ab "
assert center("abcdef", 3) == "abcdef"
}
test "bars" {
assert bar(0, 10, 4) == " "
assert bar(10, 10, 4) == "████"
assert bar(1, 3, 10) == "███▎ "
assert bar(5, 0, 3) == "███"
assert bar(-5, 10, 3) == " "
assert bar(99, 10, 3) == "███"
assert width(bar(7, 13, 17)) == 17
assert percent(1, 3) == 33
assert progress("dl", 5, 10, 40) == "dl [" + bar(5, 10, 23) + "] 50% (5/10)"
assert width(progress("dl", 5, 10, 40)) == 40
assert spinner(0) == "⠋"
assert spinner(11) == "⠙"
assert spinner(-1) == "⠏"
}
test "tables" {
let t = table(["name", "n"], [["auk", "1"], ["goose", "12"]]).align([Left, Right])
assert render(t) + "\n" == """
╭───────┬────╮
│ name │ n │
├───────┼────┤
│ auk │ 1 │
│ goose │ 12 │
╰───────┴────╯
"""
assert "{t.border(Ascii)}\n" == """
+-------+----+
| name | n |
+-------+----+
| auk | 1 |
| goose | 12 |
+-------+----+
"""
assert render(t.border(Plain)) == "name n\nauk 1\ngoose 12"
assert render(t.border(Markdown).align([Center, Right])) + "\n" == """
| name | n |
| :---: | --: |
| auk | 1 |
| goose | 12 |
"""
}
test "table edge cases" {
assert render(table([], [])) == ""
// colored cells and wide chars measure by columns; short rows pad; cells can span lines
let t = table(["k", "v"], [[red("日本"), "a\nbb"], ["x"]]).border(Sharp)
assert strip(render(t)) + "\n" == """
┌──────┬────┐
│ k │ v │
├──────┼────┤
│ 日本 │ a │
│ │ bb │
│ x │ │
└──────┴────┘
"""
assert render(table([], [["a", "b"]]).border(Ascii)) == "+---+---+\n| a | b |\n+---+---+"
assert render(table(["a"], [["x|y"]]).border(Markdown)) == "| a |\n| --- |\n| x\\|y |"
}
test "cursor" {
assert up(0) == ""
assert up(3) == "\u{1b}[3A"
assert goto(2, 5) == "\u{1b}[2;5H"
assert link("a", "u") == "\u{1b}]8;;u\u{1b}\\a\u{1b}]8;;\u{1b}\\"
}