Go to the first, previous, next, last section, table of contents.

# Program Structure

This section describes features of the CL package which have to do with programs as a whole: advanced argument lists for functions, and the `eval-when` construct.

- Argument Lists: `&key', `&aux', `defun*', `defmacro*'.
- Time of Evaluation: The `eval-when' construct.
- Function Aliases: The `defalias' function.

@secno=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.

Special Form: 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 section Blocks and Exits.

Special Form: defsubst* name arglist body...
  This is just like `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 in Emacs 19; `defsubst*` uses a different method (compiler macros) which works in all version of Emacs, and also generates somewhat more efficient inline expansions. In particular, `defsubst*` arranges for the processing of keyword arguments, default values, etc., to be done at compile-time whenever possible.

Special Form: 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. 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.

Special Form: 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 `defsetf` and `flet`) defined in this package that include arglists in their syntax allow full Common Lisp argument lists.

Note that it is not necessary to use `defun*` in order to have access to most CL features in your function. These features are always present; `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,

    (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.

If a keyword symbol is explicitly specified in the argument list as shown in the above diagram, then that keyword will be used instead of just the variable name prefixed with a colon. You can specify a keyword symbol which does not begin with a colon at all, but such symbols will not be self-quoting; you will have to quote them explicitly with an apostrophe in the function call.

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:

    (defun* find-thing (thing &rest rest &key need &allow-other-keys)
      (or (apply '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 `member*` function. `allow-other-keys` is used to keep both `find-thing` and `member*` from complaining about each others' keywords in the arguments.

In Common Lisp, keywords are recognized by the Lisp parser itself and treated as special entities. In Emacs, keywords are just symbols whose names begin with colons, which `defun*` has arranged to set equal to themselves so that they will essentially be self-quoting.

As a (significant) performance optimization, this package implements the scan for keyword arguments by calling `memq` to search for keywords in a "rest" argument. Technically speaking, this is incorrect, since `memq` looks at the odd-numbered values as well as the even-numbered keywords. The net effect is that if you happen to pass a keyword symbol as the value of another keyword argument, where that keyword symbol happens to equal the name of a valid keyword argument of the same function, then the keyword parser will become confused. This minor bug can only affect you if you use keyword symbols as general-purpose data in your program; this practice is strongly discouraged in Emacs Lisp.

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:

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

    (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 `defun*` and other argument lists as well. In destructuring, any argument variable (var in the above diagram) 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:

    (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 section Declarations), error checking for wrong number of arguments and invalid keyword arguments is disabled. By default, argument lists are rigorously checked.

## 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.

Special Form: 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 `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 `eval-when`s, 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 `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 `eval-when`s are nested; consult Steele (second edition) for the gruesome details (and some gruesome examples).

  Some simple examples:

      ;; Top-level forms in foo.el:
      (eval-when (compile)           (setq foo1 'bar))
      (eval-when (load)              (setq foo2 'bar))
      (eval-when (compile load)      (setq foo3 'bar))
      (eval-when (eval)              (setq foo4 'bar))
      (eval-when (eval compile)      (setq foo5 'bar))
      (eval-when (eval load)         (setq foo6 'bar))
      (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 `eval-when`s 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 `setq`s.

  Note that `(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 `(eval-when (compile load eval) ...)`.

Emacs 19 includes two special forms related to `eval-when`. One of these, `eval-when-compile`, is not quite equivalent to any `eval-when` construct and is described below. This package defines a version of `eval-when-compile` for the benefit of Emacs 18 users.

The other form, `(eval-and-compile ...)`, is exactly equivalent to ``(eval-when (compile load eval) ...)'` and so is not itself defined by this package.

Special Form: 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.

Special Form: 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, `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 `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: "
                (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 Jun 23 18:33:43 1993"
                ", and loaded on: "
                --temp--))

## Function Aliases

This section describes a feature from GNU Emacs 19 which this package makes available in other versions of Emacs.

Function: defalias symbol function
  This function sets symbol's function cell to function. It is equivalent to `fset`, except that in GNU Emacs 19 it also records the setting in `load-history` so that it can be undone by a later `unload-feature`.

  In other versions of Emacs, `defalias` is a synonym for `fset`.

Go to the first, previous, next, last section, table of contents.