Introduction
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-ncurses.
cl-charms has been developed by its original author, Abhishek Reddy
([email protected]), since beginning of October 2010 for quite
some time, then abandoned for unknown reason. After that, in 2014,
Mark Fedurin ([email protected]) took responsibility for keeping
the library in working state. Robert Smith ([email protected]) 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.
Version
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.
Portability
cl-charms has been tested to work to a reasonable extent (e.g.,
example code runs) on the following platforms:
- SBCL 2.3.2 on Debian 11 x86-64
- SBCL 2.3.2 on Ubuntu 22.04.2 LTS (jammy jellyfish) x86-64
- SBCL 1.1.8--1.2.9 on Gentoo Linux (3.13.6-hardened-r3--3.15.6-hardened) x86-64
- SBCL 1.2.3.15-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://github.com/naryl/cl-tui
Windows
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 libgcc_s_dw2-1.dll and SDL.dll.
Installation
If you're Quicklisp user, then simple
(ql:quickload :cl-charms)would suffice, as cl-charms is in Quicklisp.
If you're not, then install Quicklisp and follow to the previous paragraph.
Usage
The low-level library is contained within the package
cl-charms/low-level, nicknamed charms/ll. This is mostly a
one-to-one equivalent to standard curses functions.
The high-level library is contained within the package cl-charms,
nicknamed charms.
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 cl-charms:
- 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, itch, (blog post)
Daniel Kochmanski has written a nice tutorial about CL-CHARMS here.
Timer
A minimal, simple timer/stopwatch program.
* (ql:quickload :cl-charms-timer)
* (charms-timer:main)Paint
A simple ASCII art drawing program.
* (ql:quickload :cl-charms-paint)
* (charms-paint:main)Marquee
A program that horizontally scrolls text across the screen.
* (ql:quickload :cl-charms-marquee)
* (charms-marquee:main)Testing
As a minimum, it would be appreciated if the library was compiled and loaded on various Lisp systems on a variety of operating systems.
[TODO]
Note about SLIME
The 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