Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ansi - terminal styling

Import with import "ansi.j" as ansi;. Wraps a string in ANSI SGR escape codes for colour, background colour, text style, and 24-bit truecolor - and strips them back off. Pure Jennifer (no Go), so it runs on either binary.

Styling is TTY-aware: it suppresses itself when stdout is not a terminal (redirected to a file or a pipe), so the wrapped text stays clean either way. The NO_COLOR / FORCE_COLOR environment convention overrides the gate.

use io;
import "ansi.j" as ansi;

io.printf("%s\n", ansi.bold(ansi.red("error:")) + " something broke");
io.printf("%s\n", ansi.green("ok") + " / " + ansi.yellow("warn"));
io.printf("%s\n", ansi.rgb("truecolor orange", 255, 128, 0));
io.printf("%s\n", ansi.underline(ansi.cyan("nested + underlined")));

Runnable: examples/modules/ansi_demo.j.

Surface

CallReturnsNotes
ansi.color(s, name)stringWrap s in the named foreground colour. Unknown name throws.
ansi.bgColor(s, name)stringWrap s in the named background colour.
ansi.style(s, name)stringWrap s in a text style: bold / dim / italic / underline / reverse.
ansi.rgb(s, r, g, b)string24-bit truecolor foreground; each channel 0-255.
ansi.strip(s)stringRemove every SGR escape - the inverse of the wrappers.

Wrapping composes and nests (ansi.bold(ansi.red(s))); each wrapper emits its own code and a reset, so an inner reset never truncates an outer style.

Colour and style names

  • Foreground / background (color / bgColor): black, red, green, yellow, blue, magenta, cyan, white. color also accepts the bright gray (alias grey).
  • Styles (style): bold, dim, italic, underline, reverse.

An unrecognized name is a thrown Error (kind: "value"), catchable with try / catch.

Shortcuts

Each common colour and style has a one-argument shortcut - ansi.NAME(s) is exactly ansi.color(s, "NAME") (or ansi.style for a style name):

  • Colours: black, red, green, yellow, blue, magenta, cyan, white, gray.
  • Styles: bold, dim, italic, underline, reverse.

When styling is emitted

ansi decides per call (it is stateless - there is no toggle to store):

  1. NO_COLOR set (to anything) - off, always.
  2. else FORCE_COLOR set - on, always.
  3. else on when os.isTerminal("stdout") is true; off when it is false.
  4. If the host cannot tell whether stdout is a terminal, defaults on.

strip ignores this gate - it removes escapes unconditionally, so it cleans up already-styled text (or a captured subprocess’s output) regardless of the current terminal state.

def styled as string init ansi.bold(ansi.blue("styled"));
io.printf("stripped: [%s]\n", ansi.strip($styled));   # stripped: [styled]

See also

  • os.md - os.isTerminal, the TTY gate, and os.getEnv for the NO_COLOR / FORCE_COLOR reads.
  • regex.md - strip uses regex.replace to drop escape sequences.
  • modules/index.md - the module catalog and import rules.