Skip to content
KN-86 Deckline

cl-termbox2

What it is

Section titled “What it is”

cl-termbox2 is a Common Lisp binding layer over termbox2, the minimal single-header C terminal-I/O library. The API surface is direct: tb-init, tb-print, tb-printf, tb-present, tb-clear, tb-poll-event, tb-peek-event, tb-shutdown. Constants like +tb-cyan+, +tb-black+ are exposed as Lisp keywords. The repo ships a small snake-game demo as the canonical “this works end-to-end” example.

For KN-86 this is the single most architecturally significant entry in this batch because it answers a concrete question: if KN-86 commits to an embedded Lisp-like scripting layer (per mal.md / build-your-own-lisp.md), how does that Lisp drive a real terminal? cl-termbox2 is the answer-by-example: the Lisp calls into C bindings around a small, dependency-free cell-based terminal library, and the result is a real, working TUI.

Key takeaways for KN-86

Section titled “Key takeaways for KN-86”
  • It’s the bridge. The Batch-4 “embedded Lisp” recommendation is empty without a story for how that Lisp reaches the screen. cl-termbox2 demonstrates the pattern end-to-end: a stable C-ABI cell renderer + a Lisp binding layer + Lisp code that drives the rendering loop. KN-86 already has the C-ABI render path (the nOSh runtime); what cl-termbox2 confirms is that KEC Lisp (ADR-0001) on Fe VM (ADR-0004) calling NoshAPI (ADR-0005) is a known-working architectural shape, just instantiated with different specific libraries. KN-86’s choice of Fe over Common Lisp is a deliberate one (memory discipline; arena GC); the structural lesson transfers regardless.
  • The Lisp API surface as a NoshAPI sanity check. tb-init / tb-print / tb-present / tb-clear / tb-poll-event is essentially the minimum useful TUI API. KN-86 NoshAPI is already much richer than this (54 primitives per ADR-0005), but the cl-termbox2 surface is a useful lower bound — anything KN-86 can’t do at this level of abstraction should probably get an FFI primitive of its own.
  • The snake demo is the canonical reference example. ~100 lines of Lisp that initializes, polls input, updates state, renders cells, presents. Worth keeping in mind as the minimum viable cart-equivalent when shaping NoshAPI cart-authoring docs (docs/software/cartridges/authoring/): a snake cart in KEC Lisp at comparable scale is the right “hello world” for the launch SDK.
  • Choice of language matters less than the pattern. Common Lisp is a different ecosystem from Fe (rxi’s tiny tree-walking Lisp); but the pattern — small embedded Lisp / cell renderer / FFI between them — is the same. cl-termbox2 + termbox2 in Common Lisp is the same shape as Fe + NoshAPI + nOSh in KN-86’s world.

Image

Section titled “Image”

No image downloaded.

Notes

Section titled “Notes”
  • Cross-link termbox2.md for the underlying C library and mal.md / build-your-own-lisp.md for the Lisp-implementation-as-reference companions. cl-termbox2 is the integration example across the boundary; mal and BuildYourOwnLisp are how to build the Lisp side.
  • Strong direct cite for ADR-0001 and ADR-0005. Worth adding to the prior-art section of both: “cl-termbox2 is an existing example of a small Lisp binding layer over a C-ABI cell-based terminal renderer — the architectural shape NoshAPI commits to, instantiated with different specific libraries.”
  • Out-of-scope reminder. KN-86 does not embed Common Lisp. The lesson is structural, not tool-choice.