GNU Emacs Common Lisp Emulation ¶

1.1 Usage ¶

This package is distributed with Emacs, so there is no need to install any additional files in order to start using it. Lisp code that uses features from this package should simply include at the beginning:

(require 'cl-lib)

You may wish to add such a statement to your init file, if you make frequent use of features from this package.

Code that only uses macros from this package can enclose the above in eval-when-compile. Internally, this library is divided into several files, see Organization. Your code should only ever load the main cl-lib file, which will load the others as needed.

1.2 Organization ¶

The Common Lisp package is organized into four main files:

cl-lib.el

This is the main file, which contains basic functions and information about the package. This file is relatively compact.

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 cl-incf 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 cl-delete-if and cl-assoc.

cl-macs.el

This file contains the features that 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). 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-lib.el includes all necessary autoload commands for the functions and macros in the other three files. All you have to do is (require 'cl-lib), and cl-lib.el will take care of pulling in the other files when they are needed.

There is another file, cl.el, which was the main entry point to this package prior to Emacs 24.3. Nowadays, it is replaced by cl-lib.el. The two provide the same features (in most cases), but use different function names (in fact, cl.el mainly just defines aliases to the cl-lib.el definitions). Where cl-lib.el defines a function called, for example, cl-incf, cl.el uses the same name but without the ‘cl-’ prefix, e.g., incf in this example. There are a few exceptions to this. First, functions such as cl-defun where the unprefixed version was already used for a standard Emacs Lisp function. In such cases, the cl.el version adds a ‘*’ suffix, e.g., defun*. Second, there are some obsolete features that are only implemented in cl.el, not in cl-lib.el, because they are replaced by other standard Emacs Lisp features. Finally, in a very few cases the old cl.el versions do not behave in exactly the same way as the cl-lib.el versions. See Obsolete Features.

The old file cl.el, as well as the even older cl-compat.el, are deprecated and will be removed in a future version of Emacs. Any existing code that uses them should be updated to use cl-lib.el instead.

1.3 Naming Conventions ¶

Except where noted, all functions defined by this package have the same calling conventions as their Common Lisp counterparts, and names that are those of Common Lisp plus a ‘cl-’ prefix.

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

cl-callf           cl-callf2          cl-defsubst
cl-letf            cl-letf*

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

cl-evenp           cl-oddp            cl-minusp
cl-plusp           cl-endp            cl-subst
cl-copy-list       cl-list*           cl-ldiff
cl-rest            cl-decf [1]        cl-incf [1]
cl-acons           cl-adjoin [2]      cl-pairlis
cl-pushnew [1,2]   cl-declaim         cl-proclaim
cl-caaar...cl-cddddr                  cl-first...cl-tenth
cl-mapcar [3]

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

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

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

2.1 Argument Lists ¶

Emacs Lisp’s notation for argument lists of functions is a subset of the Common Lisp notation. As well as the familiar &optional and &rest markers, Common Lisp allows you to specify default values for optional arguments, and it provides the additional markers &key and &aux.

Since argument parsing is built-in to Emacs, there is no way for this package to implement Common Lisp argument lists seamlessly. Instead, this package defines alternates for several Lisp forms which you must use if you need Common Lisp argument lists.

Macro: cl-defun name arglist body… ¶

This form is identical to the regular defun form, except that arglist is allowed to be a full Common Lisp argument list. Also, the function body is enclosed in an implicit block called name; see Blocks and Exits.

Macro: cl-iter-defun name arglist body… ¶

This form is identical to the regular iter-defun form, except that arglist is allowed to be a full Common Lisp argument list. Also, the function body is enclosed in an implicit block called name; see Blocks and Exits.

Macro: cl-defsubst name arglist body… ¶

This is just like cl-defun, except that the function that is defined is automatically proclaimed inline, i.e., calls to it may be expanded into in-line code by the byte compiler. This is analogous to the defsubst form; cl-defsubst uses a different method (compiler macros) which works in all versions of Emacs, and also generates somewhat more efficient inline expansions. In particular, cl-defsubst arranges for the processing of keyword arguments, default values, etc., to be done at compile-time whenever possible.

Macro: cl-defmacro name arglist body… ¶

This is identical to the regular defmacro form, except that arglist is allowed to be a full Common Lisp argument list. The &environment keyword is supported as described in Steele’s book Common Lisp, the Language. The &whole keyword is supported only within destructured lists (see below); top-level &whole cannot be implemented with the current Emacs Lisp interpreter. The macro expander body is enclosed in an implicit block called name.

Macro: cl-function symbol-or-lambda ¶

This is identical to the regular function form, except that if the argument is a lambda form then that form may use a full Common Lisp argument list.

Also, all forms (such as cl-flet and cl-labels) defined in this package that include arglists in their syntax allow full Common Lisp argument lists.

Note that it is not necessary to use cl-defun in order to have access to most CL features in your function. These features are always present; cl-defun’s only difference from defun is its more flexible argument lists and its implicit block.

The full form of a Common Lisp argument list is

(var...
 &optional (var initform svar)...
 &rest var
 &key ((keyword var) initform svar)...
 &aux (var initform)...)

Each of the five argument list sections is optional. The svar, initform, and keyword parts are optional; if they are omitted, then ‘(var)’ may be written simply ‘var’.

The first section consists of zero or more required arguments. These arguments must always be specified in a call to the function; there is no difference between Emacs Lisp and Common Lisp as far as required arguments are concerned.

The second section consists of optional arguments. These arguments may be specified in the function call; if they are not, initform specifies the default value used for the argument. (No initform means to use nil as the default.) The initform is evaluated with the bindings for the preceding arguments already established; (a &optional (b (1+ a))) matches one or two arguments, with the second argument defaulting to one plus the first argument. If the svar is specified, it is an auxiliary variable which is bound to t if the optional argument was specified, or to nil if the argument was omitted. If you don’t use an svar, then there will be no way for your function to tell whether it was called with no argument, or with the default value passed explicitly as an argument.

The third section consists of a single rest argument. If more arguments were passed to the function than are accounted for by the required and optional arguments, those extra arguments are collected into a list and bound to the “rest” argument variable. Common Lisp’s &rest is equivalent to that of Emacs Lisp. Common Lisp accepts &body as a synonym for &rest in macro contexts; this package accepts it all the time.

The fourth section consists of keyword arguments. These are optional arguments which are specified by name rather than positionally in the argument list. For example,

(cl-defun foo (a &optional b &key c d (e 17)))

defines a function which may be called with one, two, or more arguments. The first two arguments are bound to a and b in the usual way. The remaining arguments must be pairs of the form :c, :d, or :e followed by the value to be bound to the corresponding argument variable. (Symbols whose names begin with a colon are called keywords, and they are self-quoting in the same way as nil and t.)

For example, the call (foo 1 2 :d 3 :c 4) sets the five arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword appears more than once in the function call, the first occurrence takes precedence over the later ones. Note that it is not possible to specify keyword arguments without specifying the optional argument b as well, since (foo 1 :c 2) would bind b to the keyword :c, then signal an error because 2 is not a valid keyword.

You can also explicitly specify the keyword argument; it need not be simply the variable name prefixed with a colon. For example,

(cl-defun bar (&key (a 1) ((baz b) 4)))

specifies a keyword :a that sets the variable a with default value 1, as well as a keyword baz that sets the variable b with default value 4. In this case, because baz is not self-quoting, you must quote it explicitly in the function call, like this:

(bar :a 10 'baz 42)

Ordinarily, it is an error to pass an unrecognized keyword to a function, e.g., (foo 1 2 :c 3 :goober 4). You can ask Lisp to ignore unrecognized keywords, either by adding the marker &allow-other-keys after the keyword section of the argument list, or by specifying an :allow-other-keys argument in the call whose value is non-nil. If the function uses both &rest and &key at the same time, the “rest” argument is bound to the keyword list as it appears in the call. For example:

(cl-defun find-thing (thing thing-list &rest rest &key need &allow-other-keys)
  (or (apply 'cl-member thing thing-list :allow-other-keys t rest)
      (if need (error "Thing not found"))))

This function takes a :need keyword argument, but also accepts other keyword arguments which are passed on to the cl-member function. allow-other-keys is used to keep both find-thing and cl-member from complaining about each others’ keywords in the arguments.

The fifth section of the argument list consists of auxiliary variables. These are not really arguments at all, but simply variables which are bound to nil or to the specified initforms during execution of the function. There is no difference between the following two functions, except for a matter of stylistic taste:

(cl-defun foo (a b &aux (c (+ a b)) d)
  body)

(cl-defun foo (a b)
  (let ((c (+ a b)) d)
    body))

Argument lists support destructuring. In Common Lisp, destructuring is only allowed with defmacro; this package allows it with cl-defun and other argument lists as well. In destructuring, any argument variable (var in the above example) can be replaced by a list of variables, or more generally, a recursive argument list. The corresponding argument value must be a list whose elements match this recursive argument list. For example:

(cl-defmacro dolist ((var listform &optional resultform)
                   &rest body)
  ...)

This says that the first argument of dolist must be a list of two or three items; if there are other arguments as well as this list, they are stored in body. All features allowed in regular argument lists are allowed in these recursive argument lists. In addition, the clause ‘&whole var’ is allowed at the front of a recursive argument list. It binds var to the whole list being matched; thus (&whole all a b) matches a list of two things, with a bound to the first thing, b bound to the second thing, and all bound to the list itself. (Common Lisp allows &whole in top-level defmacro argument lists as well, but Emacs Lisp does not support this usage.)

One last feature of destructuring is that the argument list may be dotted, so that the argument list (a b . c) is functionally equivalent to (a b &rest c).

If the optimization quality safety is set to 0 (see Declarations), error checking for wrong number of arguments and invalid keyword arguments is disabled. By default, argument lists are rigorously checked.

2.2 Time of Evaluation ¶

Normally, the byte-compiler does not actually execute the forms in a file it compiles. For example, if a file contains (setq foo t), the act of compiling it will not actually set foo to t. This is true even if the setq was a top-level form (i.e., not enclosed in a defun or other form). Sometimes, though, you would like to have certain top-level forms evaluated at compile-time. For example, the compiler effectively evaluates defmacro forms at compile-time so that later parts of the file can refer to the macros that are defined.

Macro: cl-eval-when (situations…) forms… ¶

This form controls when the body forms are evaluated. The situations list may contain any set of the symbols compile, load, and eval (or their long-winded ANSI equivalents, :compile-toplevel, :load-toplevel, and :execute).

The cl-eval-when form is handled differently depending on whether or not it is being compiled as a top-level form. Specifically, it gets special treatment if it is being compiled by a command such as byte-compile-file which compiles files or buffers of code, and it appears either literally at the top level of the file or inside a top-level progn.

For compiled top-level cl-eval-whens, the body forms are executed at compile-time if compile is in the situations list, and the forms are written out to the file (to be executed at load-time) if load is in the situations list.

For non-compiled-top-level forms, only the eval situation is relevant. (This includes forms executed by the interpreter, forms compiled with byte-compile rather than byte-compile-file, and non-top-level forms.) The cl-eval-when acts like a progn if eval is specified, and like nil (ignoring the body forms) if not.

The rules become more subtle when cl-eval-whens are nested; consult Steele (second edition) for the gruesome details (and some gruesome examples).

Some simple examples:

;; Top-level forms in foo.el:
(cl-eval-when (compile)           (setq foo1 'bar))
(cl-eval-when (load)              (setq foo2 'bar))
(cl-eval-when (compile load)      (setq foo3 'bar))
(cl-eval-when (eval)              (setq foo4 'bar))
(cl-eval-when (eval compile)      (setq foo5 'bar))
(cl-eval-when (eval load)         (setq foo6 'bar))
(cl-eval-when (eval compile load) (setq foo7 'bar))

When foo.el is compiled, these variables will be set during the compilation itself:

foo1  foo3  foo5  foo7      ; 'compile'

When foo.elc is loaded, these variables will be set:

foo2  foo3  foo6  foo7      ; 'load'

And if foo.el is loaded uncompiled, these variables will be set:

foo4  foo5  foo6  foo7      ; 'eval'

If these seven cl-eval-whens had been, say, inside a defun, then the first three would have been equivalent to nil and the last four would have been equivalent to the corresponding setqs.

Note that (cl-eval-when (load eval) …) is equivalent to (progn …) in all contexts. The compiler treats certain top-level forms, like defmacro (sort-of) and require, as if they were wrapped in (cl-eval-when (compile load eval) …).

Emacs includes two special forms related to cl-eval-when. See Eval During Compile in GNU Emacs Lisp Reference Manual. One of these, eval-when-compile, is not quite equivalent to any cl-eval-when construct and is described below.

The other form, (eval-and-compile …), is exactly equivalent to ‘(cl-eval-when (compile load eval) …)’.

Macro: eval-when-compile forms… ¶

The forms are evaluated at compile-time; at execution time, this form acts like a quoted constant of the resulting value. Used at top-level, eval-when-compile is just like ‘eval-when (compile eval)’. In other contexts, eval-when-compile allows code to be evaluated once at compile-time for efficiency or other reasons.

This form is similar to the ‘#.’ syntax of true Common Lisp.

Macro: cl-load-time-value form ¶

The form is evaluated at load-time; at execution time, this form acts like a quoted constant of the resulting value.

Early Common Lisp had a ‘#,’ syntax that was similar to this, but ANSI Common Lisp replaced it with load-time-value and gave it more well-defined semantics.

In a compiled file, cl-load-time-value arranges for form to be evaluated when the .elc file is loaded and then used as if it were a quoted constant. In code compiled by byte-compile rather than byte-compile-file, the effect is identical to eval-when-compile. In uncompiled code, both eval-when-compile and cl-load-time-value act exactly like progn.

(defun report ()
  (insert "This function was executed on: "
          (current-time-string)
          ", compiled on: "
          (eval-when-compile (current-time-string))
          ;; or '#.(current-time-string) in real Common Lisp
          ", and loaded on: "
          (cl-load-time-value (current-time-string))))

Byte-compiled, the above defun will result in the following code (or its compiled equivalent, of course) in the .elc file:

(setq --temp-- (current-time-string))
(defun report ()
  (insert "This function was executed on: "
          (current-time-string)
          ", compiled on: "
          '"Wed Oct 31 16:32:28 2012"
          ", and loaded on: "
          --temp--))

3.1 Type Predicates ¶

Function: cl-typep object type ¶

Check if object is of type type, where type is a (quoted) type name of the sort used by Common Lisp. For example, (cl-typep foo 'integer) is equivalent to (integerp foo).

The type argument to the above function is either a symbol or a list beginning with a symbol.

• If the type name is a symbol, Emacs appends ‘-p’ to the symbol name to form the name of a predicate function for testing the type. (Built-in predicates whose names end in ‘p’ rather than ‘-p’ are used when appropriate.)
• The type symbol t stands for the union of all types. (cl-typep object t) is always true. Likewise, the type symbol nil stands for nothing at all, and (cl-typep object nil) is always false.
• The type symbol null represents the symbol nil. Thus (cl-typep object 'null) is equivalent to (null object).
• The type symbol atom represents all objects that are not cons cells. Thus (cl-typep object 'atom) is equivalent to (atom object).
• The type symbol real is a synonym for number, and fixnum is a synonym for integer.
• The type symbols character and string-char match integers in the range from 0 to 255.
• The type list (integer low high) represents all integers between low and high, inclusive. Either bound may be a list of a single integer to specify an exclusive limit, or a * to specify no limit. The type (integer * *) is thus equivalent to integer.
• Likewise, lists beginning with float, real, or number represent numbers of that type falling in a particular range.
• Lists beginning with and, or, and not form combinations of types. For example, (or integer (float 0 *)) represents all objects that are integers or non-negative floats.
• Lists beginning with member or cl-member represent objects eql to any of the following values. For example, (member 1 2 3 4) is equivalent to (integer 1 4), and (member nil) is equivalent to null.
• Lists of the form (satisfies predicate) represent all objects for which predicate returns true when called with that object as an argument.

The following function and macro (not technically predicates) are related to cl-typep.

Function: cl-coerce object type ¶

This function attempts to convert object to the specified type. If object is already of that type as determined by cl-typep, it is simply returned. Otherwise, certain types of conversions will be made: If type is any sequence type (string, list, etc.) then object will be converted to that type if possible. If type is character, then strings of length one and symbols with one-character names can be coerced. If type is float, then integers can be coerced in versions of Emacs that support floats. In all other circumstances, cl-coerce signals an error.

Macro: cl-deftype name arglist forms… ¶

This macro defines a new type called name. It is similar to defmacro in many ways; when name is encountered as a type name, the body forms are evaluated and should return a type specifier that is equivalent to the type. The arglist is a Common Lisp argument list of the sort accepted by cl-defmacro. The type specifier ‘(name args…)’ is expanded by calling the expander with those arguments; the type symbol ‘name’ is expanded by calling the expander with no arguments. The arglist is processed the same as for cl-defmacro except that optional arguments without explicit defaults use * instead of nil as the “default” default. Some examples:

(cl-deftype null () '(satisfies null))    ; predefined
(cl-deftype list () '(or null cons))      ; predefined
(cl-deftype unsigned-byte (&optional bits)
  (list 'integer 0 (if (eq bits '*) bits (1- (ash 1 bits)))))
(unsigned-byte 8)  ≡  (integer 0 255)
(unsigned-byte)  ≡  (integer 0 *)
unsigned-byte  ≡  (integer 0 *)

The last example shows how the Common Lisp unsigned-byte type specifier could be implemented if desired; this package does not implement unsigned-byte by default.

The cl-typecase (see Conditionals) and cl-check-type (see Assertions and Errors) macros also use type names. The cl-map, cl-concatenate, and cl-merge functions take type-name arguments to specify the type of sequence to return. See Sequences.

3.2 Equality Predicates ¶

This package defines the Common Lisp predicate cl-equalp.

Function: cl-equalp a b ¶

This function is a more flexible version of equal. In particular, it compares strings case-insensitively, and it compares numbers without regard to type (so that (cl-equalp 3 3.0) is true). Vectors and conses are compared recursively. All other objects are compared as if by equal.

This function differs from Common Lisp equalp in several respects. First, Common Lisp’s equalp also compares characters case-insensitively, which would be impractical in this package since Emacs does not distinguish between integers and characters. In keeping with the idea that strings are less vector-like in Emacs Lisp, this package’s cl-equalp also will not compare strings against vectors of integers.

Also note that the Common Lisp functions member and assoc use eql to compare elements, whereas Emacs Lisp follows the MacLisp tradition and uses equal for these two functions. The functions cl-member and cl-assoc use eql, as in Common Lisp. The standard Emacs Lisp functions memq and assq use eq, and the standard memql uses eql.

4.1 Assignment ¶

The cl-psetq form is just like setq, except that multiple assignments are done in parallel rather than sequentially.

Macro: cl-psetq [symbol form]… ¶

This special form (actually a macro) is used to assign to several variables simultaneously. Given only one symbol and form, it has the same effect as setq. Given several symbol and form pairs, it evaluates all the forms in advance and then stores the corresponding variables afterwards.

(setq x 2 y 3)
(setq x (+ x y)  y (* x y))
x
     ⇒ 5
y                     ; y was computed after x was set.
     ⇒ 15
(setq x 2 y 3)
(cl-psetq x (+ x y)  y (* x y))
x
     ⇒ 5
y                     ; y was computed before x was set.
     ⇒ 6

The simplest use of cl-psetq is (cl-psetq x y y x), which exchanges the values of two variables. (The cl-rotatef form provides an even more convenient way to swap two variables; see Modify Macros.)

cl-psetq always returns nil.

4.2 Generalized Variables ¶

A generalized variable or place form is one of the many places in Lisp memory where values can be stored. The simplest place form is a regular Lisp variable. But the CARs and CDRs of lists, elements of arrays, properties of symbols, and many other locations are also places where Lisp values are stored. For basic information, see Generalized Variables in GNU Emacs Lisp Reference Manual. This package provides several additional features related to generalized variables.

• Setf Extensions
• Modify Macros

(setf (aref vec (cl-incf i)) i)

(defmacro wrong-order (x y) (list 'aref y x))

4.3 Variable Bindings ¶

These Lisp forms make bindings to variables and function names, analogous to Lisp’s built-in let form.

See Modify Macros, for the cl-letf and cl-letf* forms which are also related to variable bindings.

• Dynamic Bindings
• Function Bindings
• Macro Bindings

4.4 Conditionals ¶

These conditional forms augment Emacs Lisp’s simple if, and, or, and cond forms.

Macro: cl-case keyform clause… ¶

This macro evaluates keyform, then compares it with the key values listed in the various clauses. Whichever clause matches the key is executed; comparison is done by eql. If no clause matches, the cl-case form returns nil. The clauses are of the form

(keylist body-forms...)

where keylist is a list of key values. If there is exactly one value, and it is not a cons cell or the symbol nil or t, then it can be used by itself as a keylist without being enclosed in a list. All key values in the cl-case form must be distinct. The final clauses may use t in place of a keylist to indicate a default clause that should be taken if none of the other clauses match. (The symbol otherwise is also recognized in place of t. To make a clause that matches the actual symbol t, nil, or otherwise, enclose the symbol in a list.)

For example, this expression reads a keystroke, then does one of four things depending on whether it is an ‘a’, a ‘b’, a RET or C-j, or anything else.

(cl-case (read-char)
  (?a (do-a-thing))
  (?b (do-b-thing))
  ((?\r ?\n) (do-ret-thing))
  (t (do-other-thing)))

Macro: cl-ecase keyform clause… ¶

This macro is just like cl-case, except that if the key does not match any of the clauses, an error is signaled rather than simply returning nil.

Macro: cl-typecase keyform clause… ¶

This macro is a version of cl-case that checks for types rather than values. Each clause is of the form ‘(type body…)’. See Type Predicates, for a description of type specifiers. For example,

(cl-typecase x
  (integer (munch-integer x))
  (float (munch-float x))
  (string (munch-integer (string-to-number x)))
  (t (munch-anything x)))

The type specifier t matches any type of object; the word otherwise is also allowed. To make one clause match any of several types, use an (or …) type specifier.

Macro: cl-etypecase keyform clause… ¶

This macro is just like cl-typecase, except that if the key does not match any of the clauses, an error is signaled rather than simply returning nil.

4.5 Blocks and Exits ¶

Common Lisp blocks provide a non-local exit mechanism very similar to catch and throw, with lexical scoping. This package actually implements cl-block in terms of catch; however, the lexical scoping allows the byte-compiler to omit the costly catch step if the body of the block does not actually cl-return-from the block.

Macro: cl-block name forms… ¶

The forms are evaluated as if by a progn. However, if any of the forms execute (cl-return-from name), they will jump out and return directly from the cl-block form. The cl-block returns the result of the last form unless a cl-return-from occurs.

The cl-block/cl-return-from mechanism is quite similar to the catch/throw mechanism. The main differences are that block names are unevaluated symbols, rather than forms (such as quoted symbols) that evaluate to a tag at run-time; and also that blocks are always lexically scoped. In a dynamically scoped catch, functions called from the catch body can also throw to the catch. This is not an option for cl-block, where the cl-return-from referring to a block name must appear physically within the forms that make up the body of the block. They may not appear within other called functions, although they may appear within macro expansions or lambdas in the body. Block names and catch names form independent name-spaces.

In true Common Lisp, defun and defmacro surround the function or expander bodies with implicit blocks with the same name as the function or macro. This does not occur in Emacs Lisp, but this package provides cl-defun and cl-defmacro forms, which do create the implicit block.

The Common Lisp looping constructs defined by this package, such as cl-loop and cl-dolist, also create implicit blocks just as in Common Lisp.

Because they are implemented in terms of Emacs Lisp’s catch and throw, blocks have the same overhead as actual catch constructs (roughly two function calls). However, the byte compiler will optimize away the catch if the block does not in fact contain any cl-return or cl-return-from calls that jump to it. This means that cl-do loops and cl-defun functions that don’t use cl-return don’t pay the overhead to support it.

Macro: cl-return-from name [result] ¶

This macro returns from the block named name, which must be an (unevaluated) symbol. If a result form is specified, it is evaluated to produce the result returned from the block. Otherwise, nil is returned.

Macro: cl-return [result] ¶

This macro is exactly like (cl-return-from nil result). Common Lisp loops like cl-do and cl-dolist implicitly enclose themselves in nil blocks.

Macro: cl-tagbody &rest labels-or-statements ¶

This macro executes statements while allowing for control transfer to user-defined labels. Each element of labels-or-statements can be either a label (an integer or a symbol), or a cons-cell (a statement). This distinction is made before macroexpansion. Statements are executed in sequence, discarding any return value. Any statement can transfer control at any time to the statements that follow one of the labels with the special form (go label). Labels have lexical scope and dynamic extent.

4.6 Iteration ¶

The macros described here provide more sophisticated, high-level looping constructs to complement Emacs Lisp’s basic loop forms (see Iteration in GNU Emacs Lisp Reference Manual).

Macro: cl-loop forms… ¶

This package supports both the simple, old-style meaning of loop and the extremely powerful and flexible feature known as the Loop Facility or Loop Macro. This more advanced facility is discussed in the following section; see Loop Facility. The simple form of loop is described here.

If cl-loop is followed by zero or more Lisp expressions, then (cl-loop exprs…) simply creates an infinite loop executing the expressions over and over. The loop is enclosed in an implicit nil block. Thus,

(cl-loop (foo)  (if (no-more) (return 72))  (bar))

is exactly equivalent to

(cl-block nil (while t (foo)  (if (no-more) (return 72))  (bar)))

If any of the expressions are plain symbols, the loop is instead interpreted as a Loop Macro specification as described later. (This is not a restriction in practice, since a plain symbol in the above notation would simply access and throw away the value of a variable.)

Macro: cl-do (spec…) (end-test [result…]) forms… ¶

This macro creates a general iterative loop. Each spec is of the form

(var [init [step]])

The loop works as follows: First, each var is bound to the associated init value as if by a let form. Then, in each iteration of the loop, the end-test is evaluated; if true, the loop is finished. Otherwise, the body forms are evaluated, then each var is set to the associated step expression (as if by a cl-psetq form) and the next iteration begins. Once the end-test becomes true, the result forms are evaluated (with the vars still bound to their values) to produce the result returned by cl-do.

The entire cl-do loop is enclosed in an implicit nil block, so that you can use (cl-return) to break out of the loop at any time.

If there are no result forms, the loop returns nil. If a given var has no step form, it is bound to its init value but not otherwise modified during the cl-do loop (unless the code explicitly modifies it); this case is just a shorthand for putting a (let ((var init)) …) around the loop. If init is also omitted it defaults to nil, and in this case a plain ‘var’ can be used in place of ‘(var)’, again following the analogy with let.

This example (from Steele) illustrates a loop that applies the function f to successive pairs of values from the lists foo and bar; it is equivalent to the call (cl-mapcar 'f foo bar). Note that this loop has no body forms at all, performing all its work as side effects of the rest of the loop.

(cl-do ((x foo (cdr x))
        (y bar (cdr y))
        (z nil (cons (f (car x) (car y)) z)))
     ((or (null x) (null y))
      (nreverse z)))

Macro: cl-do* (spec…) (end-test [result…]) forms… ¶

This is to cl-do what let* is to let. In particular, the initial values are bound as if by let* rather than let, and the steps are assigned as if by setq rather than cl-psetq.

Here is another way to write the above loop:

(cl-do* ((xp foo (cdr xp))
         (yp bar (cdr yp))
         (x (car xp) (car xp))
         (y (car yp) (car yp))
         z)
  ((or (null xp) (null yp))
   (nreverse z))
  (push (f x y) z))

Macro: cl-dolist (var list [result]) forms… ¶

This is exactly like the standard Emacs Lisp macro dolist, but surrounds the loop with an implicit nil block.

Macro: cl-dotimes (var count [result]) forms… ¶

This is exactly like the standard Emacs Lisp macro dotimes, but surrounds the loop with an implicit nil block. The body is executed with var bound to the integers from zero (inclusive) to count (exclusive), in turn. Then the result form is evaluated with var bound to the total number of iterations that were done (i.e., (max 0 count)) to get the return value for the loop form. Use of result is deprecated.

Macro: cl-do-symbols (var [obarray [result]]) forms… ¶

This loop iterates over all interned symbols. If obarray is specified and is not nil, it loops over all symbols in that obarray. For each symbol, the body forms are evaluated with var bound to that symbol. The symbols are visited in an unspecified order. Afterward the result form, if any, is evaluated (with var bound to nil) to get the return value. The loop is surrounded by an implicit nil block.

Macro: cl-do-all-symbols (var [result]) forms… ¶

This is identical to cl-do-symbols except that the obarray argument is omitted; it always iterates over the default obarray.

See Mapping over Sequences, for some more functions for iterating over vectors or lists.

4.7 Loop Facility ¶

A common complaint with Lisp’s traditional looping constructs was that they were either too simple and limited, such as dotimes or while, or too unreadable and obscure, like Common Lisp’s do loop.

To remedy this, Common Lisp added a construct called the “Loop Facility” or “loop macro”, with an easy-to-use but very powerful and expressive syntax.

• Loop Basics
• Loop Examples
• For Clauses
• Iteration Clauses
• Accumulation Clauses
• Other Clauses

(cl-loop for buf in (buffer-list)
         collect (buffer-file-name buf))

(cl-loop repeat 20 do (insert "Yowsa\n"))

(cl-loop until (eobp) do (munch-line) (forward-line 1))

(cl-loop do (munch-line) until (eobp) do (forward-line 1))

(cl-loop for x from 1 to 100
         for y = (* x x)
         until (>= y 729)
         finally return (list x (= y 729)))

(setq i 'happy)
(cl-loop for i from 1 to 10 do (do-something-with i))
i
     ⇒ happy

(cl-loop for x below 5 for y = nil then x collect (list x y))
        ⇒ ((0 nil) (1 1) (2 2) (3 3) (4 4))
(cl-loop for x below 5 and y = nil then x collect (list x y))
        ⇒ ((0 nil) (1 0) (2 1) (3 2) (4 3))

(cl-loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
        ⇒ (5 9 13)

(cl-loop for (key . value) in '((a . 1) (b . 2))
         collect value)
        ⇒ (1 2)

(cl-loop for name in '(fred sue alice joe june)
         for kids in '((bob ken) () () (kris sunshine) ())
         collect name
         append kids)
        ⇒ (fred bob ken sue alice joe kris sunshine june)

4.8 Multiple Values ¶

Common Lisp functions can return zero or more results. Emacs Lisp functions, by contrast, always return exactly one result. This package makes no attempt to emulate Common Lisp multiple return values; Emacs versions of Common Lisp functions that return more than one value either return just the first value (as in cl-compiler-macroexpand) or return a list of values. This package does define placeholders for the Common Lisp functions that work with multiple values, but in Emacs Lisp these functions simply operate on lists instead. The cl-values form, for example, is a synonym for list in Emacs.

Macro: cl-multiple-value-bind (var…) values-form forms… ¶

This form evaluates values-form, which must return a list of values. It then binds the vars to these respective values, as if by let, and then executes the body forms. If there are more vars than values, the extra vars are bound to nil. If there are fewer vars than values, the excess values are ignored.

Macro: cl-multiple-value-setq (var…) form ¶

This form evaluates form, which must return a list of values. It then sets the vars to these respective values, as if by setq. Extra vars or values are treated the same as in cl-multiple-value-bind.

Since a perfect emulation is not feasible in Emacs Lisp, this package opts to keep it as simple and predictable as possible.

4.9 Macro-Writing Macros ¶

This package includes two classic Common Lisp macro-writing macros to help render complex macrology easier to read.

Macro: cl-with-gensyms names… body ¶

This macro expands to code that executes body with each of the variables in names bound to a fresh uninterned symbol, or gensym, in Common Lisp parlance. For macros requiring more than one gensym, use of cl-with-gensyms shortens the code and renders one’s intentions clearer. Compare:

(defmacro my-macro (foo)
  (let ((bar (gensym "bar"))
        (baz (gensym "baz"))
        (quux (gensym "quux")))
    `(let ((,bar (+ ...)))
       ...)))

(defmacro my-macro (foo)
  (cl-with-gensyms (bar baz quux)
    `(let ((,bar (+ ...)))
       ...)))

Macro: cl-once-only ((variable form)…) body ¶

This macro is primarily to help the macro programmer ensure that forms supplied by the user of the macro are evaluated just once by its expansion even though the result of evaluating the form is to occur more than once. Less often, this macro is used to ensure that forms supplied by the macro programmer are evaluated just once.

Each variable may be used to refer to the result of evaluating form in body. cl-once-only binds each variable to a fresh uninterned symbol during the evaluation of body. Then, cl-once-only wraps the final expansion in code to evaluate each form and bind the result to the corresponding uninterned symbol. Thus, when the macro writer substitutes the value for variable into the expansion they are effectively referring to the result of evaluating form, rather than form itself. Another way to put this is that each variable is bound to an expression for the (singular) result of evaluating form.

The most common case is where variable is one of the arguments to the macro being written, so (variable variable) may be abbreviated to just variable.

For example, consider this macro:

(defmacro my-list (x y &rest forms)
  (let ((x-result (gensym))
        (y-result (gensym)))
    `(let ((,x-result ,x)
           (,y-result ,y))
       (list ,x-result ,y-result ,x-result ,y-result
             (progn ,@forms))))

In a call like (my-list (pop foo) …) the intermediate binding to x-result ensures that the pop is not done twice. But as a result the code is rather complex: the reader must keep track of how x-result really just means the first parameter of the call to the macro, and the required use of multiple gensyms to avoid variable capture by (progn ,@forms) obscures things further. cl-once-only takes care of these details:

(defmacro my-list (x y &rest forms)
  (cl-once-only (x y)
    `(list ,x ,y ,x ,y
           (progn ,@forms))))

7.1 Property Lists ¶

These functions augment the standard Emacs Lisp functions get and put for operating on properties attached to symbols. There are also functions for working with property lists as first-class data structures not attached to particular symbols.

Function: cl-get symbol property &optional default ¶

This function is like get, except that if the property is not found, the default argument provides the return value. (The Emacs Lisp get function always uses nil as the default; this package’s cl-get is equivalent to Common Lisp’s get.)

The cl-get function is setf-able; when used in this fashion, the default argument is allowed but ignored.

Function: cl-remprop symbol property ¶

This function removes the entry for property from the property list of symbol. It returns a true value if the property was indeed found and removed, or nil if there was no such property. (This function was probably omitted from Emacs originally because, since get did not allow a default, it was very difficult to distinguish between a missing property and a property whose value was nil; thus, setting a property to nil was close enough to cl-remprop for most purposes.)

Function: cl-getf place property &optional default ¶

This function scans the list place as if it were a property list, i.e., a list of alternating property names and values. If an even-numbered element of place is found which is eq to property, the following odd-numbered element is returned. Otherwise, default is returned (or nil if no default is given).

In particular,

(get sym prop)  ≡  (cl-getf (symbol-plist sym) prop)

It is valid to use cl-getf as a setf place, in which case its place argument must itself be a valid setf place. The default argument, if any, is ignored in this context. The effect is to change (via setcar) the value cell in the list that corresponds to property, or to cons a new property-value pair onto the list if the property is not yet present.

(put sym prop val) ≡ (setf (cl-getf (symbol-plist sym) prop) val)

The get and cl-get functions are also setf-able. The fact that default is ignored can sometimes be useful:

(cl-incf (cl-get 'foo 'usage-count 0))

Here, symbol foo’s usage-count property is incremented if it exists, or set to 1 (an incremented 0) otherwise.

When not used as a setf form, cl-getf is just a regular function and its place argument can actually be any Lisp expression.

Macro: cl-remf place property ¶

This macro removes the property-value pair for property from the property list stored at place, which is any setf-able place expression. It returns true if the property was found. Note that if property happens to be first on the list, this will effectively do a (setf place (cddr place)), whereas if it occurs later, this simply uses setcdr to splice out the property and value cells.

7.2 Creating Symbols ¶

These functions create unique symbols, typically for use as temporary variables.

Function: cl-gensym &optional x ¶

This function creates a new, uninterned symbol (using make-symbol) with a unique name. (The name of an uninterned symbol is relevant only if the symbol is printed.) By default, the name is generated from an increasing sequence of numbers, ‘G1000’, ‘G1001’, ‘G1002’, etc. If the optional argument x is a string, that string is used as a prefix instead of ‘G’. Uninterned symbols are used in macro expansions for temporary variables, to ensure that their names will not conflict with “real” variables in the user’s code.

(Internally, the variable cl--gensym-counter holds the counter used to generate names. It is initialized with zero and incremented after each use.)

Function: cl-gentemp &optional x ¶

This function is like cl-gensym, except that it produces a new interned symbol. If the symbol that is generated already exists, the function keeps incrementing the counter and trying again until a new symbol is generated.

This package automatically creates all keywords that are called for by &key argument specifiers, and discourages the use of keywords as data unrelated to keyword arguments, so the related function defkeyword (to create self-quoting keyword symbols) is not provided.

8.1 Predicates on Numbers ¶

These functions return t if the specified condition is true of the numerical argument, or nil otherwise.

Function: cl-plusp number ¶

This predicate tests whether number is positive. It is an error if the argument is not a number.

Function: cl-minusp number ¶

This predicate tests whether number is negative. It is an error if the argument is not a number.

Function: cl-oddp integer ¶

This predicate tests whether integer is odd. It is an error if the argument is not an integer.

Function: cl-evenp integer ¶

This predicate tests whether integer is even. It is an error if the argument is not an integer.

Function: cl-digit-char-p char radix ¶

Test if char is a digit in the specified radix (default is 10). If it is, return the numerical value of digit char in radix.

8.2 Numerical Functions ¶

These functions perform various arithmetic operations on numbers.

Function: cl-gcd &rest integers ¶

This function returns the Greatest Common Divisor of the arguments. For one argument, it returns the absolute value of that argument. For zero arguments, it returns zero.

Function: cl-lcm &rest integers ¶

This function returns the Least Common Multiple of the arguments. For one argument, it returns the absolute value of that argument. For zero arguments, it returns one.

Function: cl-isqrt integer ¶

This function computes the “integer square root” of its integer argument, i.e., the greatest integer less than or equal to the true square root of the argument.

Function: cl-floor number &optional divisor ¶

With one argument, cl-floor returns a list of two numbers: The argument rounded down (toward minus infinity) to an integer, and the “remainder” which would have to be added back to the first return value to yield the argument again. If the argument is an integer x, the result is always the list (x 0). If the argument is a floating-point number, the first result is a Lisp integer and the second is a Lisp float between 0 (inclusive) and 1 (exclusive).

With two arguments, cl-floor divides number by divisor, and returns the floor of the quotient and the corresponding remainder as a list of two numbers. If (cl-floor x y) returns (q r), then q*y + r = x, with r between 0 (inclusive) and r (exclusive). Also, note that (cl-floor x) is exactly equivalent to (cl-floor x 1).

This function is entirely compatible with Common Lisp’s floor function, except that it returns the two results in a list since Emacs Lisp does not support multiple-valued functions.

Function: cl-ceiling number &optional divisor ¶

This function implements the Common Lisp ceiling function, which is analogous to floor except that it rounds the argument or quotient of the arguments up toward plus infinity. The remainder will be between 0 and minus r.

Function: cl-truncate number &optional divisor ¶

This function implements the Common Lisp truncate function, which is analogous to floor except that it rounds the argument or quotient of the arguments toward zero. Thus it is equivalent to cl-floor if the argument or quotient is positive, or to cl-ceiling otherwise. The remainder has the same sign as number.

Function: cl-round number &optional divisor ¶

This function implements the Common Lisp round function, which is analogous to floor except that it rounds the argument or quotient of the arguments to the nearest integer. In the case of a tie (the argument or quotient is exactly halfway between two integers), it rounds to the even integer.

Function: cl-mod number divisor ¶

This function returns the same value as the second return value of cl-floor.

Function: cl-rem number divisor ¶

This function returns the same value as the second return value of cl-truncate.

Function: cl-parse-integer string &key start end radix junk-allowed ¶

This function implements the Common Lisp parse-integer function. It parses an integer in the specified radix from the substring of string between start and end. Any leading and trailing whitespace chars are ignored. The function signals an error if the substring between start and end cannot be parsed as an integer, unless junk-allowed is non-nil.

8.3 Random Numbers ¶

This package also provides an implementation of the Common Lisp random number generator. It uses its own additive-congruential algorithm, which is much more likely to give statistically clean random numbers than the simple generators supplied by many operating systems.

Function: cl-random number &optional state ¶

This function returns a random nonnegative number less than number, and of the same type (either integer or floating-point). The state argument should be a random-state object that holds the state of the random number generator. The function modifies this state object as a side effect. If state is omitted, it defaults to the internal variable cl--random-state, which contains a pre-initialized default random-state object. (Since any number of programs in the Emacs process may be accessing cl--random-state in interleaved fashion, the sequence generated from this will be irreproducible for all intents and purposes.)

Function: cl-make-random-state &optional state ¶

This function creates or copies a random-state object. If state is omitted or nil, it returns a new copy of cl--random-state. This is a copy in the sense that future sequences of calls to (cl-random n) and (cl-random n s) (where s is the new random-state object) will return identical sequences of random numbers.

If state is a random-state object, this function returns a copy of that object. If state is t, this function returns a new random-state object seeded from the date and time. As an extension to Common Lisp, state may also be an integer in which case the new object is seeded from that integer; each different integer seed will result in a completely different sequence of random numbers.

It is valid to print a random-state object to a buffer or file and later read it back with read. If a program wishes to use a sequence of pseudo-random numbers which can be reproduced later for debugging, it can call (cl-make-random-state t) to get a new sequence, then print this sequence to a file. When the program is later rerun, it can read the original run’s random-state from the file.

Function: cl-random-state-p object ¶

This predicate returns t if object is a random-state object, or nil otherwise.

8.4 Implementation Parameters ¶

This package defines several useful constants having to do with floating-point numbers.

It determines their values by exercising the computer’s floating-point arithmetic in various ways. Because this operation might be slow, the code for initializing them is kept in a separate function that must be called before the parameters can be used.

Function: cl-float-limits ¶

This function makes sure that the Common Lisp floating-point parameters like cl-most-positive-float have been initialized. Until it is called, these parameters have unspecified values. If the parameters have already been initialized, the function returns immediately.

Since true Common Lisp supports up to four different kinds of floating-point numbers, it has families of constants like most-positive-single-float, most-positive-double-float, most-positive-long-float, and so on. This package uses just one set of constants because Emacs has only one kind of floating-point number, namely the IEEE binary64 floating-point format. See Float Basics in GNU Emacs Lisp Reference Manual.

Variable: cl-most-positive-float ¶

This constant equals the largest finite value a Lisp float can hold. For IEEE binary64 format, this equals (- (expt 2 1024) (expt 2 971)), which equals 1.7976931348623157e+308.

Variable: cl-most-negative-float ¶

This constant equals the most negative finite value a Lisp float can hold. For IEEE binary64 format, this equals (- cl-most-positive-float).

Variable: cl-least-positive-normalized-float ¶

This constant equals the smallest positive Lisp float that is normalized, i.e., that has full precision. For IEEE binary64 format, this equals (expt 2 -1022), which equals 2.2250738585072014e-308.

Variable: cl-least-positive-float ¶

This constant equals the smallest Lisp float value greater than zero. For IEEE binary64 format, this equals 5e-324 (which equals (expt 2 -1074)) if subnormal numbers are supported, and cl-least-positive-normalized-float otherwise.

Variable: cl-least-negative-float ¶

This constant is the negative counterpart of cl-least-positive-float.

Variable: cl-least-negative-normalized-float ¶

This constant is the negative counterpart of cl-least-positive-normalized-float.

Variable: cl-float-epsilon ¶

This constant is the smallest positive Lisp float that can be added to 1.0 to produce a distinct value. Adding a smaller number to 1.0 will yield 1.0 again due to roundoff. For IEEE binary64 format, this equals (expt 2 -52), which equals 2.220446049250313e-16.

Variable: cl-float-negative-epsilon ¶

This is the smallest positive value that can be subtracted from 1.0 to produce a distinct value. For IEEE binary64 format, this equals (expt 2 -53), which equals 1.1102230246251565e-16.

9.1 Sequence Basics ¶

Many of the sequence functions take keyword arguments; see Argument Lists. All keyword arguments are optional and, if specified, may appear in any order.

The :key argument should be passed either nil, or a function of one argument. This key function is used as a filter through which the elements of the sequence are seen; for example, (cl-find x y :key 'car) is similar to (cl-assoc x y). It searches for an element of the list whose CAR equals x, rather than for an element which equals x itself. If :key is omitted or nil, the filter is effectively the identity function.

The :test and :test-not arguments should be either nil, or functions of two arguments. The test function is used to compare two sequence elements, or to compare a search value with sequence elements. (The two values are passed to the test function in the same order as the original sequence function arguments from which they are derived, or, if they both come from the same sequence, in the same order as they appear in that sequence.) The :test argument specifies a function which must return true (non-nil) to indicate a match; instead, you may use :test-not to give a function which returns false to indicate a match. The default test function is eql.

Many functions that take item and :test or :test-not arguments also come in -if and -if-not varieties, where a predicate function is passed instead of item, and sequence elements match if the predicate returns true on them (or false in the case of -if-not). For example:

(cl-remove 0 seq :test '=)  ≡  (cl-remove-if 'zerop seq)

to remove all zeros from sequence seq.

Some operations can work on a subsequence of the argument sequence; these function take :start and :end arguments, which default to zero and the length of the sequence, respectively. Only elements between start (inclusive) and end (exclusive) are affected by the operation. The end argument may be passed nil to signify the length of the sequence; otherwise, both start and end must be integers, with 0 <= start <= end <= (length seq). If the function takes two sequence arguments, the limits are defined by keywords :start1 and :end1 for the first, and :start2 and :end2 for the second.

A few functions accept a :from-end argument, which, if non-nil, causes the operation to go from right-to-left through the sequence instead of left-to-right, and a :count argument, which specifies an integer maximum number of elements to be removed or otherwise processed.

The sequence functions make no guarantees about the order in which the :test, :test-not, and :key functions are called on various elements. Therefore, it is a bad idea to depend on side effects of these functions. For example, :from-end may cause the sequence to be scanned actually in reverse, or it may be scanned forwards but computing a result “as if” it were scanned backwards. (Some functions, like cl-mapcar and cl-every, do specify exactly the order in which the function is called so side effects are perfectly acceptable in those cases.)

Strings may contain “text properties” as well as character data. Except as noted, it is undefined whether or not text properties are preserved by sequence functions. For example, (cl-remove ?A str) may or may not preserve the properties of the characters copied from str into the result.

9.2 Mapping over Sequences ¶

These functions “map” the function you specify over the elements of lists or arrays. They are all variations on the theme of the built-in function mapcar.

Function: cl-mapcar function seq &rest more-seqs ¶

This function calls function on successive parallel sets of elements from its argument sequences. Given a single seq argument it is equivalent to mapcar; given n sequences, it calls the function with the first elements of each of the sequences as the n arguments to yield the first element of the result list, then with the second elements, and so on. The mapping stops as soon as the shortest sequence runs out. The argument sequences may be any mixture of lists, strings, and vectors; the return sequence is always a list.

Common Lisp’s mapcar accepts multiple arguments but works only on lists; Emacs Lisp’s mapcar accepts a single sequence argument. This package’s cl-mapcar works as a compatible superset of both.

Function: cl-map result-type function seq &rest more-seqs ¶

This function maps function over the argument sequences, just like cl-mapcar, but it returns a sequence of type result-type rather than a list. result-type must be one of the following symbols: vector, string, list (in which case the effect is the same as for cl-mapcar), or nil (in which case the results are thrown away and cl-map returns nil).

Function: cl-maplist function list &rest more-lists ¶

This function calls function on each of its argument lists, then on the CDRs of those lists, and so on, until the shortest list runs out. The results are returned in the form of a list. Thus, cl-maplist is like cl-mapcar except that it passes in the list pointers themselves rather than the CARs of the advancing pointers.

Function: cl-mapc function seq &rest more-seqs ¶

This function is like cl-mapcar, except that the values returned by function are ignored and thrown away rather than being collected into a list. The return value of cl-mapc is seq, the first sequence. This function is more general than the Emacs primitive mapc. (Note that this function is called cl-mapc even in cl.el, rather than mapc* as you might expect.)

Function: cl-mapl function list &rest more-lists ¶

This function is like cl-maplist, except that it throws away the values returned by function.

Function: cl-mapcan function seq &rest more-seqs ¶

This function is like cl-mapcar, except that it concatenates the return values (which must be lists) using nconc, rather than simply collecting them into a list.

Function: cl-mapcon function list &rest more-lists ¶

This function is like cl-maplist, except that it concatenates the return values using nconc.

Function: cl-some predicate seq &rest more-seqs ¶

This function calls predicate on each element of seq in turn; if predicate returns a non-nil value, cl-some returns that value, otherwise it returns nil. Given several sequence arguments, it steps through the sequences in parallel until the shortest one runs out, just as in cl-mapcar. You can rely on the left-to-right order in which the elements are visited, and on the fact that mapping stops immediately as soon as predicate returns non-nil.

Function: cl-every predicate seq &rest more-seqs ¶

This function calls predicate on each element of the sequence(s) in turn; it returns nil as soon as predicate returns nil for any element, or t if the predicate was true for all elements.

Function: cl-notany predicate seq &rest more-seqs ¶

This function calls predicate on each element of the sequence(s) in turn; it returns nil as soon as predicate returns a non-nil value for any element, or t if the predicate was nil for all elements.

Function: cl-notevery predicate seq &rest more-seqs ¶

This function calls predicate on each element of the sequence(s) in turn; it returns a non-nil value as soon as predicate returns nil for any element, or nil if the predicate was true for all elements.

Function: cl-reduce function seq &key :from-end :start :end :initial-value :key ¶

This function returns the result of calling function on the first and second elements of seq, then calling function with that result and the third element of seq, then with that result and the fourth element of seq, etc.

Here is an example. Suppose function is * and seq is the list (2 3 4 5). The first two elements of the list are combined with (* 2 3) = 6; this is combined with the next element, (* 6 4) = 24, and that is combined with the final element: (* 24 5) = 120. Note that the * function happens to be self-reducing, so that (* 2 3 4 5) has the same effect as an explicit call to cl-reduce.

If :from-end is true, the reduction is right-associative instead of left-associative:

(cl-reduce '- '(1 2 3 4))
        ≡ (- (- (- 1 2) 3) 4) ⇒ -8
(cl-reduce '- '(1 2 3 4) :from-end t)
        ≡ (- 1 (- 2 (- 3 4))) ⇒ -2

If :key is specified, it is a function of one argument, which is called on each of the sequence elements in turn.

If :initial-value is specified, it is effectively added to the front (or rear in the case of :from-end) of the sequence. The :key function is not applied to the initial value.

If the sequence, including the initial value, has exactly one element then that element is returned without ever calling function. If the sequence is empty (and there is no initial value), then function is called with no arguments to obtain the return value.

All of these mapping operations can be expressed conveniently in terms of the cl-loop macro. In compiled code, cl-loop will be faster since it generates the loop as in-line code with no function calls.

9.3 Sequence Functions ¶

This section describes a number of Common Lisp functions for operating on sequences.

Function: cl-subseq sequence start &optional end ¶

This function returns a given subsequence of the argument sequence, which may be a list, string, or vector. The indices start and end must be in range, and start must be no greater than end. If end is omitted, it defaults to the length of the sequence. The return value is always a copy; it does not share structure with sequence.

As an extension to Common Lisp, start and/or end may be negative, in which case they represent a distance back from the end of the sequence. This is for compatibility with Emacs’s substring function. Note that cl-subseq is the only sequence function that allows negative start and end.

You can use setf on a cl-subseq form to replace a specified range of elements with elements from another sequence. The replacement is done as if by cl-replace, described below.

Function: cl-concatenate result-type &rest seqs ¶

This function concatenates the argument sequences together to form a result sequence of type result-type, one of the symbols vector, string, or list. The arguments are always copied, even in cases such as (cl-concatenate 'list '(1 2 3)) where the result is identical to an argument.

Function: cl-fill seq item &key :start :end ¶

This function fills the elements of the sequence (or the specified part of the sequence) with the value item.

Function: cl-replace seq1 seq2 &key :start1 :end1 :start2 :end2 ¶

This function copies part of seq2 into part of seq1. The sequence seq1 is not stretched or resized; the amount of data copied is simply the shorter of the source and destination (sub)sequences. The function returns seq1.

If seq1 and seq2 are eq, then the replacement will work correctly even if the regions indicated by the start and end arguments overlap. However, if seq1 and seq2 are lists that share storage but are not eq, and the start and end arguments specify overlapping regions, the effect is undefined.

Function: cl-remove item seq &key :test :test-not :key :count :start :end :from-end ¶

This returns a copy of seq with all elements matching item removed. The result may share storage with or be eq to seq in some circumstances, but the original seq will not be modified. The :test, :test-not, and :key arguments define the matching test that is used; by default, elements eql to item are removed. The :count argument specifies the maximum number of matching elements that can be removed (only the leftmost count matches are removed). The :start and :end arguments specify a region in seq in which elements will be removed; elements outside that region are not matched or removed. The :from-end argument, if true, says that elements should be deleted from the end of the sequence rather than the beginning (this matters only if count was also specified).

Function: cl-delete item seq &key :test :test-not :key :count :start :end :from-end ¶

This deletes all elements of seq that match item. It is a destructive operation. Since Emacs Lisp does not support stretchable strings or vectors, this is the same as cl-remove for those sequence types. On lists, cl-remove will copy the list if necessary to preserve the original list, whereas cl-delete will splice out parts of the argument list. Compare append and nconc, which are analogous non-destructive and destructive list operations in Emacs Lisp.

The predicate-oriented functions cl-remove-if, cl-remove-if-not, cl-delete-if, and cl-delete-if-not are defined similarly.

Function: cl-remove-duplicates seq &key :test :test-not :key :start :end :from-end ¶

This function returns a copy of seq with duplicate elements removed. Specifically, if two elements from the sequence match according to the :test, :test-not, and :key arguments, only the rightmost one is retained. If :from-end is true, the leftmost one is retained instead. If :start or :end is specified, only elements within that subsequence are examined or removed.

Function: cl-delete-duplicates seq &key :test :test-not :key :start :end :from-end ¶

This function deletes duplicate elements from seq. It is a destructive version of cl-remove-duplicates.

Function: cl-substitute new old seq &key :test :test-not :key :count :start :end :from-end ¶

This function returns a copy of seq, with all elements matching old replaced with new. The :count, :start, :end, and :from-end arguments may be used to limit the number of substitutions made.

Function: cl-nsubstitute new old seq &key :test :test-not :key :count :start :end :from-end ¶

This is a destructive version of cl-substitute; it performs the substitution using setcar or aset rather than by returning a changed copy of the sequence.

The functions cl-substitute-if, cl-substitute-if-not, cl-nsubstitute-if, and cl-nsubstitute-if-not are defined similarly. For these, a predicate is given in place of the old argument.

9.4 Searching Sequences ¶

These functions search for elements or subsequences in a sequence. (See also cl-member and cl-assoc; see Lists.)

Function: cl-find item seq &key :test :test-not :key :start :end :from-end ¶

This function searches seq for an element matching item. If it finds a match, it returns the matching element. Otherwise, it returns nil. It returns the leftmost match, unless :from-end is true, in which case it returns the rightmost match. The :start and :end arguments may be used to limit the range of elements that are searched.

Function: cl-position item seq &key :test :test-not :key :start :end :from-end ¶

This function is like cl-find, except that it returns the integer position in the sequence of the matching item rather than the item itself. The position is relative to the start of the sequence as a whole, even if :start is non-zero. The function returns nil if no matching element was found.

Function: cl-count item seq &key :test :test-not :key :start :end ¶

This function returns the number of elements of seq which match item. The result is always a nonnegative integer.

The cl-find-if, cl-find-if-not, cl-position-if, cl-position-if-not, cl-count-if, and cl-count-if-not functions are defined similarly.

Function: cl-mismatch seq1 seq2 &key :test :test-not :key :start1 :end1 :start2 :end2 :from-end ¶

This function compares the specified parts of seq1 and seq2. If they are the same length and the corresponding elements match (according to :test, :test-not, and :key), the function returns nil. If there is a mismatch, the function returns the index (relative to seq1) of the first mismatching element. This will be the leftmost pair of elements that do not match, or the position at which the shorter of the two otherwise-matching sequences runs out.

If :from-end is true, then the elements are compared from right to left starting at (1- end1) and (1- end2). If the sequences differ, then one plus the index of the rightmost difference (relative to seq1) is returned.

An interesting example is (cl-mismatch str1 str2 :key 'upcase), which compares two strings case-insensitively.

Function: cl-search seq1 seq2 &key :test :test-not :key :from-end :start1 :end1 :start2 :end2 ¶

This function searches seq2 for a subsequence that matches seq1 (or part of it specified by :start1 and :end1). Only matches that fall entirely within the region defined by :start2 and :end2 will be considered. The return value is the index of the leftmost element of the leftmost match, relative to the start of seq2, or nil if no matches were found. If :from-end is true, the function finds the rightmost matching subsequence.

9.5 Sorting Sequences ¶

Function: cl-sort seq predicate &key :key ¶

This function sorts seq into increasing order as determined by using predicate to compare pairs of elements. predicate should return true (non-nil) if and only if its first argument is less than (not equal to) its second argument. For example, < and string-lessp are suitable predicate functions for sorting numbers and strings, respectively; > would sort numbers into decreasing rather than increasing order.

This function differs from Emacs’s built-in sort in that it can operate on any type of sequence, not just lists. Also, it accepts a :key argument, which is used to preprocess data fed to the predicate function. For example,

(setq data (cl-sort data 'string-lessp :key 'downcase))

sorts data, a sequence of strings, into increasing alphabetical order without regard to case. A :key function of car would be useful for sorting association lists. It should only be a simple accessor though, since it’s used heavily in the current implementation.

The cl-sort function is destructive; it sorts lists by actually rearranging the CDR pointers in suitable fashion.

Function: cl-stable-sort seq predicate &key :key ¶

This function sorts seq stably, meaning two elements which are equal in terms of predicate are guaranteed not to be rearranged out of their original order by the sort.

In practice, cl-sort and cl-stable-sort are equivalent in Emacs Lisp because the underlying sort function is stable by default. However, this package reserves the right to use non-stable methods for cl-sort in the future.

Function: cl-merge type seq1 seq2 predicate &key :key ¶

This function merges two sequences seq1 and seq2 by interleaving their elements. The result sequence, of type type (in the sense of cl-concatenate), has length equal to the sum of the lengths of the two input sequences. The sequences may be modified destructively. Order of elements within seq1 and seq2 is preserved in the interleaving; elements of the two sequences are compared by predicate (in the sense of sort) and the lesser element goes first in the result. When elements are equal, those from seq1 precede those from seq2 in the result. Thus, if seq1 and seq2 are both sorted according to predicate, then the result will be a merged sequence which is (stably) sorted according to predicate.

10.1 List Functions ¶

This section describes a number of simple operations on lists, i.e., chains of cons cells.

Function: cl-first x ¶

This function is a synonym for (car x). Likewise, the functions cl-second, cl-third, …, through cl-tenth return the given element of the list x.

Function: cl-rest x ¶

This function is a synonym for (cdr x).

Function: cl-endp x ¶

This function acts like null, but signals an error if x is neither a nil nor a cons cell.

Function: cl-list-length x ¶

This function returns the length of list x, exactly like (length x), except that if x is a circular list (where the CDR-chain forms a loop rather than terminating with nil), this function returns nil. (The regular length function would get stuck if given a circular list. See also the safe-length function.)

Function: cl-list* arg &rest others ¶

This function constructs a list of its arguments. The final argument becomes the CDR of the last cell constructed. Thus, (cl-list* a b c) is equivalent to (cons a (cons b c)), and (cl-list* a b nil) is equivalent to (list a b).

Function: cl-ldiff list sublist ¶

If sublist is a sublist of list, i.e., is eq to one of the cons cells of list, then this function returns a copy of the part of list up to but not including sublist. For example, (cl-ldiff x (cddr x)) returns the first two elements of the list x. The result is a copy; the original list is not modified. If sublist is not a sublist of list, a copy of the entire list is returned.

Function: cl-copy-list list ¶

This function returns a copy of the list list. It copies dotted lists like (1 2 . 3) correctly.

Function: cl-tree-equal x y &key :test :test-not :key ¶

This function compares two trees of cons cells. If x and y are both cons cells, their CARs and CDRs are compared recursively. If neither x nor y is a cons cell, they are compared by eql, or according to the specified test. The :key function, if specified, is applied to the elements of both trees. See Sequences.

10.2 Substitution of Expressions ¶

These functions substitute elements throughout a tree of cons cells. (See Sequence Functions, for the cl-substitute function, which works on just the top-level elements of a list.)

Function: cl-subst new old tree &key :test :test-not :key ¶

This function substitutes occurrences of old with new in tree, a tree of cons cells. It returns a substituted tree, which will be a copy except that it may share storage with the argument tree in parts where no substitutions occurred. The original tree is not modified. This function recurses on, and compares against old, both CARs and CDRs of the component cons cells. If old is itself a cons cell, then matching cells in the tree are substituted as usual without recursively substituting in that cell. Comparisons with old are done according to the specified test (eql by default). The :key function is applied to the elements of the tree but not to old.

Function: cl-nsubst new old tree &key :test :test-not :key ¶

This function is like cl-subst, except that it works by destructive modification (by setcar or setcdr) rather than copying.

The cl-subst-if, cl-subst-if-not, cl-nsubst-if, and cl-nsubst-if-not functions are defined similarly.

Function: cl-sublis alist tree &key :test :test-not :key ¶

This function is like cl-subst, except that it takes an association list alist of old-new pairs. Each element of the tree (after applying the :key function, if any), is compared with the CARs of alist; if it matches, it is replaced by the corresponding CDR.

Function: cl-nsublis alist tree &key :test :test-not :key ¶

This is a destructive version of cl-sublis.

10.3 Lists as Sets ¶

These functions perform operations on lists that represent sets of elements. All these functions (unless otherwise specified) default to using eql as the test function, but that can be modified by the :test parameter.

Function: cl-member item list &key :test :test-not :key ¶

This function searches list for an element matching item. If a match is found, it returns the cons cell whose CAR was the matching element. Otherwise, it returns nil. Elements are compared by eql by default; you can use the :test, :test-not, and :key arguments to modify this behavior. See Sequences.

The standard Emacs lisp function member uses equal for comparisons; it is equivalent to (cl-member item list :test 'equal).

The cl-member-if and cl-member-if-not functions analogously search for elements that satisfy a given predicate.

Function: cl-tailp sublist list ¶

This function returns t if sublist is a sublist of list, i.e., if sublist is eql to list or to any of its CDRs.

Function: cl-adjoin item list &key :test :test-not :key ¶

This function conses item onto the front of list, like (cons item list), but only if item is not already present on the list (as determined by cl-member). If a :key argument is specified, it is applied to item as well as to the elements of list during the search, on the reasoning that item is “about” to become part of the list.

Function: cl-union list1 list2 &key :test :test-not :key ¶

This function combines two lists that represent sets of items, returning a list that represents the union of those two sets. The resulting list contains all items that appear in list1 or list2, and no others. If an item appears in both list1 and list2 it is copied only once. If an item is duplicated in list1 or list2, it is undefined whether or not that duplication will survive in the result list. The order of elements in the result list is also undefined.

Function: cl-nunion list1 list2 &key :test :test-not :key ¶

This is a destructive version of cl-union; rather than copying, it tries to reuse the storage of the argument lists if possible.

Function: cl-intersection list1 list2 &key :test :test-not :key ¶

This function computes the intersection of the sets represented by list1 and list2. It returns the list of items that appear in both list1 and list2.

Function: cl-nintersection list1 list2 &key :test :test-not :key ¶

This is a destructive version of cl-intersection. It tries to reuse storage of list1 rather than copying. It does not reuse the storage of list2.

Function: cl-set-difference list1 list2 &key :test :test-not :key ¶

This function computes the “set difference” of list1 and list2, i.e., the set of elements that appear in list1 but not in list2.

Function: cl-nset-difference list1 list2 &key :test :test-not :key ¶

This is a destructive cl-set-difference, which will try to reuse list1 if possible.

Function: cl-set-exclusive-or list1 list2 &key :test :test-not :key ¶

This function computes the “set exclusive or” of list1 and list2, i.e., the set of elements that appear in exactly one of list1 and list2.

Function: cl-nset-exclusive-or list1 list2 &key :test :test-not :key ¶

This is a destructive cl-set-exclusive-or, which will try to reuse list1 and list2 if possible.

Function: cl-subsetp list1 list2 &key :test :test-not :key ¶

This function checks whether list1 represents a subset of list2, i.e., whether every element of list1 also appears in list2.

10.4 Association Lists ¶

An association list is a list representing a mapping from one set of values to another; any list whose elements are cons cells is an association list.

Function: cl-assoc item a-list &key :test :test-not :key ¶

This function searches the association list a-list for an element whose CAR matches (in the sense of :test, :test-not, and :key, or by comparison with eql) a given item. It returns the matching element, if any, otherwise nil. It ignores elements of a-list that are not cons cells. (This corresponds to the behavior of assq and assoc in Emacs Lisp; Common Lisp’s assoc ignores nils but considers any other non-cons elements of a-list to be an error.)

Function: cl-rassoc item a-list &key :test :test-not :key ¶

This function searches for an element whose CDR matches item. If a-list represents a mapping, this applies the inverse of the mapping to item.

The cl-assoc-if, cl-assoc-if-not, cl-rassoc-if, and cl-rassoc-if-not functions are defined similarly.

Two simple functions for constructing association lists are:

Function: cl-acons key value alist ¶

This is equivalent to (cons (cons key value) alist).

Function: cl-pairlis keys values &optional alist ¶

This is equivalent to (nconc (cl-mapcar 'cons keys values) alist).