croatoan

croatoan copied to clipboard

#+TITLE: croatoan

• Introduction

croatoan is a set of bindings to the ncurses terminal library for Common Lisp.

It is inspired by, but not derived from, cl-ncurses and cl-charms.

The API is not yet stable, but the already finished parts are not expected to change much.

It is developed and tested on Ubuntu 20.04 x86_64 and SBCL 2.1.10.

The only supported ncurses version is 6.x --with-abi-version=6. The previous version 5.9 mostly works, but is not actively supported.

If your distribution still ships ncurses --with-abi-version=5, for full compatibility (wide characters, 256 colors and extended mouse support), you will have to manually build ncurses 6.x.

• Goals

Its main goal is to provide a higher-level, lispy/CLOSy interface, whereas the existing bindings clone the cryptic C API.

As of now, the library is in an early, but hopefully usable stage. Ncurses is old and huge and it will take a while to cover completely.

A second goal is to reimplement the extension libraries forms, menu and dialog in Lisp instead of wrapping the C libraries.

A third, distant goal is to provide direct bindings for ANSI escape sequences, so that basic terminal control functions can be used from Lisp on systems without terminfo and ncurses.

• Usage

The library is available in Quicklisp and can be installed with

#+BEGIN_SRC sh (ql:quickload "croatoan") #+END_SRC

• Systems and packages

|-----------------------------+------------------+-------------+----------------| | Library | System | Package | Short nickname | |-----------------------------+------------------+-------------+----------------| | Higl-level CLOS API | croatoan | croatoan | crt | | Low-level ncurses bindings | croatoan-ncurses | ncurses | | | ANSI X3.64 escape sequences | ansi-escape | ansi-escape | esc | |-----------------------------+------------------+-------------+----------------|

• Documentation

The documentation is currently provided by the docstrings and the commented examples.

• SLIME/Thread support

Since ncurses is not thread-safe, all IO has to occur in the main thread of the REPL running in a terminal.

This makes it difficult to interact with ncurses from the Emacs SLIME REPL which runs in its own thread.

A workaround is to pass all ncurses IO to the main thread via a thread-safe queue. Basic support for this has been implemented.

A tutorial on interacting with ncurses from swank/slime is available in docs/slime.md

• Contributing

You are welcome to contribute and any form of help would be greatly appreciated.

• Contact

Please direct any questions about ncurses, croatoan or other terminal-related Lisp topics, libraries and applications to the following mailing list:

• https://mailman.common-lisp.net/listinfo/croatoan-devel