cl-charms is an interface to
libcurses in Common Lisp. It provides both a raw, low-level interface to
libcurses via CFFI, and a more higher-level lispier interface.
It is intended to succeed
cl-ncurses, which used the less portable UFFI instead of CFFI for foreign bindings. Indeed,
cl-charms includes portions of code from
cl-ncurses, and is largely a direct translation of the latter's UFFI definitions to CFFI.
Currently, the low-level interface (the package
charms/ll) is probably feature-equivalent to
cl-ncurses and compatible with client code. In the future, however,
cl-charms may break compatibility with
cl-charms has been developed by its original author, Abhishek Reddy (firstname.lastname@example.org), since beginning of October 2010 for quite some time, then abandoned for unknown reason. After that, in 2014, Mark Fedurin (email@example.com) took responsibility for keeping the library in working state. Robert Smith (firstname.lastname@example.org) began to fix up the CFFI bindings and provide a friendlier interface.
The software is released under an MIT-style license. See the file
COPYING for details.
The imitator dooms himself to hopeless mediocrity. The inventor did it because it was natural to him, and so in him it has a charm. In the imitator something else is natural, and he bereaves himself of his own beauty, to come short of another man's. -- R.W. Emerson on originality.
Versioning roughly follows the scheme described in Semantic Versioning. Only "releases" will be versioned.
Since we are still pre-
1.0.0, the minor version will indicate API breakage. Despite being pre-
1.0.0, what exists in the low-level interface as of now is quite usable for ASCII usage. We consider this "beta" quality. The high-level functionality is considered "alpha" quality.
cl-charms has been tested to work to a reasonable extent (e.g., example code runs) on the following platforms:
- SBCL 1.1.8--1.2.9 on Gentoo Linux (3.13.6-hardened-r3--3.15.6-hardened) x86-64
- SBCL 22.214.171.124-4704124 on OS X 10.10 (Yosemite) x86-64
- SBCL 1.1.14.debian on Ubuntu 14.04.2 LTS (trusty) x86
- SBCL 1.2.11 on Windows 8.1 amd64
- CCL 1.9-r15769M on Gentoo Linux (3.13.6-hardened-r3) x86-64
- CCL 1.9-r15759 (64-bit) on OS X 10.10 (Yosemite) x86-64
- LispWorks 6.1.1 (64-bit) on OS X 10.10 (Yosemite) x86-64
- Lispworks 7.0.0 (32-bit) on OS X 10.10 (Yosemite) x86-64
It may work on other implementations and system but there's no guarantee. More testing is really appreciated.
cl-charms ought to function on other implementations of Common Lisp and
libcurses on various distributions of UNIX and UNIX-like systems. See the section on Bugs and Contributing below for how to help test and realize this.
cl-charms is supposed to be only bindings along with a separate, no-frills interface atop: nothing more, nothing less. For full-featured TUI see: https://bitbucket.org/naryl/cl-tui
cl-charms works on Windows with some limitations. Currently colours are not supported and some other features like bold might not work correctly. In order to use
cl-charms on Windows, you'll need PDCurses library that is available at http://pdcurses.sourceforge.net/. If you want to use GDI instead of console http://www.projectpluto.com/win32a.htm would be a good option.
While the original PDCurses project offers prebuilt binaries, using project pluto requires you to compile your own binaries.
Usage is as simple as placing the
pdcurses.dll (optionally renaming it
libcurses.dll) either in
PATH or in the directory where you're running your
cl-charms program. Project pluto will require additional dependencies, namely
If you're Quicklisp user, then simple
would suffice, as
cl-charms is in Quicklisp.
If you're not, then install Quicklisp and follow to the previous paragraph.
The low-level library is contained within the package
charms/ll. This is mostly a one-to-one equivalent to standard curses functions.
The high-level library is contained within the package
Examples and Tutorials
There are currently two examples included with the source code, all of which you can find in the examples directory.
You might also want to check out the following applications written using
- CHARMLIFE, a viewer for Conway's Game of Life, exponentially accelerated with the HASHLIFE algorithm (video, source)
- The game "Snake" (video, source)
- Steve Losh's Lisp Game Jam entry silt2 (blog post)
Daniel Kochmanski has written a nice tutorial about CL-CHARMS here.
A minimal, simple timer/stopwatch program.
* (ql:quickload :cl-charms-timer) * (charms-timer:main)
A simple ASCII art drawing program.
* (ql:quickload :cl-charms-paint) * (charms-paint:main)
As a minimum, it would be appreciated if the library was compiled and loaded on various Lisp systems on a variety of operating systems.
Note about SLIME
libcurses library handles terminal, and emacs is not a terminal it can handle. So if you run lisp from SLIME (inside emacs),
libcurses functions won't work properly.
If you want to use SLIME, a possible way (to e.g. run the timer example) is:
- run lisp from terminal
(ql:quickload '(:swank) :silent t);; from terminal
(swank:create-server :port 5555 :dont-close t);; from terminal, too
(loop (sleep 1));; from terminal, prevents read-line in console REPL
- go to emacs and M-x slime-connect RET localhost RET 5555 RET
(ql:quickload :cl-charms-timer);; from emacs repl
(charms-timer:main);; from emacs repl
Now you should see timer running on terminal.
Step 1. ~ 3. can be done as a one-liner:
- for SBCL:
sbcl --eval "(ql:quickload '(:swank) :silent t)" --eval "(swank:create-server :port 5555 :dont-close t)"
- for CCL:
ccl -e "(ql:quickload '(:swank) :silent t)" -e "(swank:create-server :port 5555 :dont-close t)";; maybe ccl64 instead of ccl
- for Roswell:
ros run -e "(ql:quickload '(:swank) :silent t)" -e "(swank:create-server :port 5555 :dont-close t)"
Bugs and Contributing
You can use GitHub project's (which is located here: https://github.com/HiTECNOLOGYs/cl-charms) issues tracker or wiki to contribute bug reports/patches/etc. or just send an email to one of the maintainers.
Major areas of work to be done:
- Add bindings for all the functions from ncurses
- Do more testing on different OS and architectures
- Try it with non-libncurses libraries.
- Test cases and sample applications.
- Finally write documentation
- Abhishek Reddy <email@example.com>, et al., Robert Smith
- Mark Fedurin <firstname.lastname@example.org>, Robert Smith <email@example.com>
- MIT License (See COPYING)