The Common Lisp Cookbook – Common Lisp for the 21st century

CL21 is an experimental project redesigning Common Lisp. It makes some common things that were tedious to do much easier and brings some new welcome features:

  • more functional programming facilities,
  • more object oriented, generic functions.
  • new syntax (for regular expressions, hash-tables, string-interpolation,…),
  • symbols organized into several packages,
  • written in pure Common Lisp.


From :

Dear Common Lispers,

Common Lisp has the most expressive power of any modern language. It has first class functions with lexical closures, an object system with multiple-dispatch and a metaobject protocol, true macros, and more. It is ANSI standardized and has numerous high-performance implementations, many of which are free software.

In spite of this, it has not had much success (at least in Japan). Its community is very small compared to languages like Ruby and most young Lispers are hacking with Clojure.

Why? Common Lisp is much faster than them. Ruby has no macros and even Clojure doesn’t have reader macros. Why then?

Because these languges are well-designed and work for most people for most purposes. These languages are easy to use and the speed isn’t an issue.

Is Common Lisp sufficiently well-designed? I don’t think so. You use different functions to do the same thing to different data types (elt, aref, nth). You have long names for commonly used macros (destructuring-bind, multiple-value-bind). There is no consistency in argument order (getf and gethash). To put it simply, the language is time-consuming to learn.

Given this, how can programmers coming from other languages believe Common Lisp is the most expressive one?

Fortunately in Common Lisp we can improve the interface with abstractions such as functions, macros, and reader macros. If you believe our language is the most expressive and powerful language, then let’s justify that belief.

We should consider the future of the language, not only for ourselves but for the next generation.

Install and use

CL21 is in Quicklisp.

To get its latest version, do:

(ql-dist:install-dist "")
(ql:quickload :cl21)


(in-package :cl21-user)
(defpackage myapp (:use :cl21))
(in-package :myapp)


Please bear in mind that the following is only a summary of CL21 features. To be sure not to miss anything, you should read CL21’s wiki, its automated list of major changes from standard CL and better yet, its sources.

That said, go include CL21 in your new project and enjoy, it’s worth it !

Functional programming

Shorter lambda

lm is a macro for creating an anonymous function:

(lm (x) (typep x 'cons))
;=> #<FUNCTION (LAMBDA (X)) {1008F50DAB}>

(map (lm (x) (+ 2 x)) '(1 2 3))
;=> (3 4 5)

^ is a reader macro which will be expanded to lm.

^(typep % 'cons)
;=> #<FUNCTION (LAMBDA (%1 &REST #:G1156 &AUX ...)) {10092490CB}>

(map ^(+ 2 %) '(1 2 3))
;=> (3 4 5)

Unused arguments will be ignored automatically.

(map ^(random 10) (iota 10))
;=> (6 9 5 1 3 5 4 0 7 4)

%n designates the nth argument (1-based). % is a synonym for %1.

(sort '(6 9 5 1 3 5 4 0 7 4) ^(< %1 %2))
;=> (0 1 3 4 4 5 5 6 7 9)

function and compose

function is a special operator for getting a function value from a given form.

If a symbol is given, function returns a function value of it.

(function integerp)

If a form which starts with compose, and, or or not, function returns a composed function.

(function (compose - *))
<=> (compose (function -) (function *))

(function (and integerp evenp))
<=> (conjoin (function integerp) (function evenp))

(function (or oddp zerop))
<=> (disjoin (function oddp) (function zerop))

(function (not zerop))
<=> (complement (function zerop))

#' is a reader macro for function.

#'(compose - *)
#'(and integerp evenp)
#'(or oddp zerop)
#'(not zerop)
#'(and integerp (or oddp zerop))


CL21 gets new symbols: curry and rcurry. See also functions.

Lazy sequences

Lazy sequences in CL21 (src) use the new abstract classes (wiki).

(use-package :cl21.lazy)

(defun fib-seq ()
  (labels ((rec (a b)
             (lazy-sequence (cons a (rec b (+ a b))))))
    (rec 0 1)))

(take 20 (fib-seq))
;=> (0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 2584 4181)

(take 3 (drop-while (lambda (x) (< x 500)) (fib-seq)))
;=> (610 987 1597)

Immutable data structures

This actually is not included in CL21 but may be worth the addition in this section. For immutable data structures, see the Fset library (in Quicklisp).

Generic functions

There are several generic functions which have the same name to CL’s normal functions.

  • getf
  • equalp
  • emptyp
  • coerce
(defvar *hash* #H(:name "Eitaro Fukamachi" :living "Japan"))

(getf *hash* :name)
;=> "Eitaro Fukamachi"

(coerce *hash* 'plist)
;=> (:LIVING "Japan" :NAME "Eitaro Fukamachi")

You can define these methods for your own classes.

There are also new functions:

  • append
  • flatten
  • elt: Returns the element at position INDEX of SEQUENCE or signals a ABSTRACT-METHOD-UNIMPLMENETED error if the sequence method is not implemented for the class of SEQUENCE.
  • emptyp
  • equalp
  • split, split-if
  • drop, drop-while
  • take, take-while
  • join
  • length
  • keep, keep-if, nkeep, nkeep-if
  • partition, partition-if


In Common Lisp, functions which have a name starts with “map” are higher-order functions take a function and a sequence.

It is same to CL21, but in CL21, “map” functions always return a value. This aims to clarify the roles of “iteration” and “mapping”.

For that reason, CL21 doesn’t have CL’s mapc and mapl. maphash exists, but it returns a new hash table.

(maphash (lm (k v)
           (cons k (1+ v)))
         #H(:a 1 :b 2))
;=> #H(:B 3 :A 2)

map is similar to Common Lisp’s mapcar except it can take any kind of sequences, not only list.

(map #'- '(1 2 3 4))
;=> (-1 -2 -3 -4)

(map #'- #(1 2 3 4))
;=> #(-1 -2 -3 -4)

CL21 doesn’t have mapcar. Use map instead.

Filter is provided with keep, keep-if (instead of remove-if[-not]) and nkeep[-if].


Common Lisp has simple iteration facilities: dolist, dotimes and dolist.

In addition, CL21 provides another one: doeach.

doeach is similar to dolist, but it can be used with any kind of sequences and hash-table.

(doeach (x '("al" "bob" "joe"))
  (when (> (length x) 2)
    (princ #"${x}\n")))
;-> bob
;   joe

(doeach ((key value) #H('a 2 'b 3))
  (when (> value 2)
    (print key)))
;=> B

Destructuring binding form can be placed at the variable position.

(doeach ((x y) '((1 2) (2 3) (3 4)))
  (print (+ x y)))
;-> 3
;   5
;   7

CL21 also gets a while keyword.

New data types

New data types were added.

  • proper-list
  • plist
  • alist
  • octet
  • file-associated-stream
  • character-designator
  • function-designator
  • file-position-designator
  • list-designator
  • package-designator
  • stream-designator
  • string-designator

Most of these are imported from trivial-types.


A double quote character is a macro character which represents a string.

"Hello, World!"
;=> "Hello, World!"

A backslash followed by some characters will be treated special.

;=> "Hello
;   World!"

String interpolation

#" is similar to ", but it allows interpolation within strings.

If ${...} or @{...} is seen, it will be replaced by the result value of an expression (or the last expression) inside of it.

#"1 + 1 = ${(+ 1 1)}"
;=> "1 + 1 = 2"

Hash table

CL21 provides a notation for hash-tables.

#H(:name "Eitaro Fukamachi" :living "Japan")
;=> #H(:LIVING "Japan" :NAME "Eitaro Fukamachi")

Note this always creates a hash-table whose test function is EQUAL. If you want to create it with another test function, a function hash-table is also available.

(hash-table 'eq :name "Eitaro Fukamachi")
;=> #H(:NAME "Eitaro Fukamachi")
; instead of
; (defvar *hash* (make-hash-table))
; (setf (gethash :name *hash*) "Eitaro Fukamachi")

Accessing an element is also done with getf (instead of gethash):

(getf *hash* :name)

Looping over a hash-table:

(doeach ((key val) *hash*)
  (when (< (length key) 2)
    (princ #"${x}\n")))

Transform a hash-table into a plist:

(coerce *hash* 'plist)


#(...) is a notation for vectors. Unlike in Common Lisp, its elements will be evaluated and it creates an adjustable vector.

(let ((a 1)
      (b 2)
      (c 3))
  #(a b c))
;=> #(1 2 3)
(defvar *vec* #(0))

(push 1 *vec*)
;=> #(1 0)

(push-back 3 *vec*)
;=> #(1 0 3)

(pop *vec*)
;=> 1

Regular Expressions

This new regexp reader macro uses the new “Syntax” extension.


(#/^(\d{4})-(\d{2})-(\d{2})$/ "2014-01-23")

(re-replace #/a/ig "Eitaro Fukamachi" "α")

Running external programs (cl21.process)

With run-process:

(use-package :cl21.process)

(run-process '("ls" "-l" "/Users"))
;-> total 0
;   drwxrwxrwt    5 root         wheel   170 Nov  1 18:00 Shared
;   drwxr-xr-x+ 174 nitro_idiot  staff  5916 Mar  5 21:41 nitro_idiot
;=> #<PROCESS /bin/sh -c ls -l /Users (76468) EXITED 0>

or the #` reader macro:

#`ls -l /Users`
;=> "total 0
;   drwxrwxrwt    5 root         wheel   170 Nov  1 18:00 Shared
;   drwxr-xr-x+ 174 nitro_idiot  staff  5916 Mar  5 21:41 nitro_idiot
;   "
;   ""
;   0

Naming of constants

All constant variables were renamed to the name added “+” signs before and after.

;=> 3.141592653589793d0

;=> 65529

CL21 Standard Library

CL21 Standard Library is a set of libraries that are distributed with CL21. It is intended to offer a wide range of facilities.

We are working on increasing the number of it. Currently, the following packages are provided.

  • cl21.process
  • cl21.os
  • cl21.lazy
  • cl21.abbr