tur-ansi

Lightweight ncurses alternative: ANSI terminal control, raw-mode key input, color, style, box drawing, and inline images (Kitty/iTerm2/sixel).

Overview

tur-ansi is a Tier 1 spice (pure Turmeric + inline-C, no cmake deps). It covers the full surface of VT100/ANSI escape sequences you need to build interactive terminal UIs without pulling in ncurses or a comparable library.

The spice is split into focused modules so you only import what you use:

Install

:spices {
  "ansi" {:url    "https://github.com/turmeric-lang/turmeric-spices"
          :ref    "ansi-v0.1.3"
          :subdir "spices/ansi"}
}

Quick start

Colored output

(import ansi/color :refer [fg24 bg24 color-reset])
(import ansi/style :refer [style-bold style-reset])

(style-bold)
(fg24 255 200 80)
(bg24 20 20 40)
(println "hello, tur-ansi")
(style-reset)
(color-reset)

#lang sweet-exp
import ansi/color :refer [fg24 bg24 color-reset]
import ansi/style :refer [style-bold style-reset]

style-bold()
fg24(255 200 80)
bg24(20 20 40)
println("hello, tur-ansi")
style-reset()
color-reset()

Raw-mode key input

(import ansi/term :refer [term-enable-raw term-disable-raw term-read-key])
(import ansi/keys :refer [key=?])

(term-enable-raw)
(let [k (term-read-key)]
  (if (= (key=? k "<C-c>") 1)
    (println "quit!")
    (println k)))
(term-disable-raw)

#lang sweet-exp
import ansi/term :refer [term-enable-raw term-disable-raw term-read-key]
import ansi/keys :refer [key=?]

term-enable-raw()
let [k term-read-key()]
  if =(key=?(k "<C-c>") 1)
    println("quit!")
    println(k)
term-disable-raw()

Box drawing

(import ansi/screen :refer [screen-clear])
(import ansi/box    :refer [box-fill box-draw box-title])

(screen-clear)
(box-fill  2 2 10 40 32)          ;; clear interior with spaces
(box-draw  2 2 10 40 2)           ;; style 2 = round corners
(box-title 2 2 40 " my panel ")

#lang sweet-exp
import ansi/screen :refer [screen-clear]
import ansi/box    :refer [box-fill box-draw box-title]

screen-clear()
box-fill(2 2 10 40 32)
box-draw(2 2 10 40 2)
box-title(2 2 40 " my panel ")

Module reference

ansi/term

Terminal-wide setup and input. All other modules just emit escape sequences to stdout; ansi/term owns the terminal state.

Key names follow the Neovim/Helix convention: printable chars are themselves ("a", "A", " "); non-printing keys are bracketed ("<Enter>", "<Up>", "<C-a>", "<Resize>", "<EOF>").

The environment variable TUR_ANSI_TEST_KEYS bypasses select() and replays newline-delimited key names from its value, enabling scripted tests without a real tty.

ansi/color

SGR color sequences. Works in cooked or raw mode. The caller is responsible for gating on (term-no-color?) when respecting the $NO_COLOR convention.

Named index constants (return :int for use with fg4/bg4): color-black, color-red, color-green, color-yellow, color-blue, color-magenta, color-cyan, color-white, color-bright-black, color-bright-red, color-bright-green, color-bright-yellow, color-bright-blue, color-bright-magenta, color-bright-cyan, color-bright-white.

(fg4 (color-bright-red))   ;; same as (fg4 9)

Color typeclass (depth-typed fg / bg)

The depth-specific emitters above branch only on color depth, which the caller already knows statically. The Color typeclass lifts depth into the type of the color value, collapsing the six emitters to two methods, fg and bg, dispatched on the value's type. Box a color with color4 / color8 / rgb, then call fg / bg:

(fg (color4 (color-red)))   ;; same bytes as (fg4 (color-red))
(fg (color8 208))           ;; same bytes as (fg8 208)
(bg (rgb 255 128 0))        ;; same bytes as (bg24 255 128 0)

Because depth is now a type, a routine parametric in a single (Color a) can't be handed a color of the wrong depth -- e.g. one that only commits to 4-bit output won't silently accept a truecolor value.

ansi/style

SGR attribute toggles. style-reset clears all attributes AND colors; use color-reset when you only want to restore the default palette.

ansi/cursor

VT100 cursor positioning. Works in cooked or raw mode.

ansi/screen

Screen and line clearing, alternate buffer, scrolling.

Always pair alt-screen-enter with alt-screen-leave at shutdown to preserve the user's scrollback history.

ansi/keys

Key-name strings, byte parsing, and modifier predicates.

Key name format: printable characters are passed through verbatim; others use angle-bracket notation with optional modifier prefixes in order C-, M-, S-. Examples: "a", "<Enter>", "<Up>", "<C-a>", "<S-Tab>", "<C-M-S-Right>". Unknown byte sequences are returned as "<raw:HH...>" so all input remains printable.

key-name->bytes is the inverse and is mainly useful for writing scripted tests via TUR_ANSI_TEST_KEYS.

ansi/box

Unicode box-drawing characters and high-level rectangle helpers. Three border styles are available:

Individual glyph accessors (return :cstr): box-tl-single, box-tr-single, box-bl-single, box-br-single, box-h-single, box-v-single, box-tl-double, box-tr-double, box-bl-double, box-br-double, box-h-double, box-v-double, box-tl-round, box-tr-round, box-bl-round, box-br-round.

Typical draw order: box-fill first (so the fill does not overwrite the border), then box-draw, then box-title.

ansi/image

Inline image display using the protocol best suited to the running terminal.

Protocol codes match (term-image-protocol): 0=none/placeholder, 1=Kitty, 2=iTerm2, 3=sixel.

image-display-rgba uses a 6x6x6 color-cube quantizer (216 colors) and emits run-length-encoded sixel bands. The caller must decode any compressed image format (e.g. PNG via tur-png) into a flat RGBA byte buffer before calling. Sixel support in image-display and image-display-protocol is deferred to v0.2; those paths fall back to the placeholder for proto=3.

Examples

The examples/ directory has runnable demos:

tur run examples/hello-color.tur
tur run examples/keys-dump.tur       # exit: Ctrl-C, Ctrl-D, or Esc Esc
tur run examples/box-demo.tur
IMAGE_DEMO_PATH=logo.png tur run examples/image-demo.tur

Testing

just test

Tests use TUR_ANSI_TEST_KEYS to feed scripted key sequences without a real tty, so the key-reading and key-name test suites run safely in CI.

See also

• Guide
• API reference
• Source: https://github.com/turmeric-lang/turmeric-spices/tree/main/spices/ansi