1.1 Usage

Lisp code that uses features from the CL package should include at the beginning:

(require 'cl)

It is safe to arrange to load CL at all times, e.g., in your ‘.emacs’ file. But it’s a good idea, for portability, to (require 'cl) in your code even if you do this.

1.2 Organization

The Common Lisp package is organized into four files:

‘cl.el’

This is the “main” file, which contains basic functions and information about the package. This file is relatively compact—about 700 lines.

‘cl-extra.el’

This file contains the larger, more complex or unusual functions. It is kept separate so that packages which only want to use Common Lisp fundamentals like the cadr function won’t need to pay the overhead of loading the more advanced functions.

‘cl-seq.el’

This file contains most of the advanced functions for operating on sequences or lists, such as delete-if and assoc*.

‘cl-macs.el’

This file contains the features of the packages which are macros instead of functions. Macros expand when the caller is compiled, not when it is run, so the macros generally only need to be present when the byte-compiler is running (or when the macros are used in uncompiled code such as a ‘.emacs’ file). Most of the macros of this package are isolated in ‘cl-macs.el’ so that they won’t take up memory unless you are compiling.

The file ‘cl.el’ includes all necessary autoload commands for the functions and macros in the other three files. All you have to do is (require 'cl), and ‘cl.el’ will take care of pulling in the other files when they are needed.

1.3 Installation

Installation of the CL package is simple: Just put the byte-compiled files ‘cl.elc’, ‘cl-extra.elc’, ‘cl-seq.elc’, ‘cl-macs.elc’, and ‘cl-compat.elc’ into a directory on your load-path.

There are no special requirements to compile this package: The files do not have to be loaded before they are compiled, nor do they need to be compiled in any particular order.

You may choose to put the files into your main ‘lisp/’ directory, replacing the original ‘cl.el’ file there. Or, you could put them into a directory that comes before ‘lisp/’ on your load-path so that the old ‘cl.el’ is effectively hidden.

Also, format the ‘cl.texinfo’ file and put the resulting Info files in the ‘info/’ directory or another suitable place.

You may instead wish to leave this package’s components all in their own directory, and then add this directory to your load-path and (Emacs 19 only) Info-directory-list. Add the directory to the front of the list so the old CL package and its documentation are hidden.

1.4 Naming Conventions

Except where noted, all functions defined by this package have the same names and calling conventions as their Common Lisp counterparts.

Following is a complete list of functions whose names were changed from Common Lisp, usually to avoid conflicts with Emacs. In each case, a ‘*’ has been appended to the Common Lisp name to obtain the Emacs name:

defun*        defsubst*     defmacro*     function*
member*       assoc*        rassoc*       remove*
delete*       mapcar*       sort*         floor*
ceiling*      truncate*     round*        mod*
rem*          random*

Internal function and variable names in the package are prefixed by cl-. Here is a complete list of functions not prefixed by cl- which were not taken from Common Lisp:

member        delete        remove        remq
rassoc        floatp-safe   lexical-let   lexical-let*
callf         callf2        letf          letf*
defsubst*     defalias      add-hook      eval-when-compile

(Most of these are Emacs 19 features provided to Emacs 18 users, or introduced, like remq, for reasons of symmetry with similar features.)

The following simple functions and macros are defined in ‘cl.el’; they do not cause other components like ‘cl-extra’ to be loaded.

eql           floatp-safe   abs           endp
evenp         oddp          plusp         minusp
last          butlast       nbutlast      caar .. cddddr
list*         ldiff         rest          first .. tenth
member [1]    copy-list     subst         mapcar* [2]
adjoin [3]    acons         pairlis       when
unless        pop [4]       push [4]      pushnew [3,4]
incf [4]      decf [4]      proclaim      declaim
add-hook

[1] This is the Emacs 19-compatible function, not member*.

[2] Only for one sequence argument or two list arguments.

[3] Only if :test is eq, equal, or unspecified, and :key is not used.

[4] Only when place is a plain variable name.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.