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/rjungemann/turmeric-spices"
          :ref    "ansi-v0.1.3"
          :subdir "spices/ansi"}
}

(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)

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

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