High-level Lisp CLOS bindings for the ncurses terminal library.

croatoan

#+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 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 [[file:doc/slime.md][doc/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


sb-posix

Terminal control functions based on ANSI escape sequences.

ansi-escape

Tests and examples for the ANSI escape sequences.

ansi-escape-test

bordeaux-threads

croatoan-ncurses

trivial-gray-streams

cffi

Low-level Lisp CFFI bindings for the ncurses terminal library.

Tests and examples for the croatoan CLOS API and the low-level ncurses CFFI bindings.

croatoan

Upstream URL

Author

License

ansi-escape

Version:

License:

Authors:

Dependencies:

ansi-escape-test

Version:

License:

Authors:

Dependencies:

croatoan

Version:

License:

Authors:

Dependencies:

croatoan-ncurses

Version:

License:

Authors:

Dependencies:

croatoan-test

Version:

License:

Authors:

Dependencies:

Dependencies (3)

Dependents (1)