Common Lisp the Language, 2nd Edition

Next: Declaring Global Variables Up: Top-Level Forms Previous: Top-Level Forms

## 5.3.1. Defining Named Functions

The `defun` special form is the usual means of defining named functions.

[Macro]
`defun` `name` `lambda-list` `[[` `{declaration}*` `|` `doc-string` `]]` `{form}*`

Evaluating a `defun` form causes the symbol name to be a global name for the function specified by the lambda-expression

    (lambda lambda-list {declaration | doc-string}* {form}*)

defined in the lexical environment in which the `defun` form was executed. Because `defun` forms normally appear at top level, this is normally the null lexical environment.

X3J13 voted in March 1989 (DEFINING-MACROS-NON-TOP-LEVEL) to clarify that, while defining forms normally appear at top level, it is meaningful to place them in non-top-level contexts; `defun` must define the function within the enclosing lexical environment, not within the null lexical environment.

X3J13 voted in March 1989 (FUNCTION-NAME) to extend `defun` to accept any function-name (a symbol or a list whose car is `setf` - see section 7.1) as a name. Thus one may write

    (defun (setf cadr) ...)

to define a `setf` expansion function for `cadr` (although it may be much more convenient to use `defsetf` or `define-modify-macro`).

If the optional documentation string doc-string is present, then it is attached to the name as a documentation string of type `function`; see `documentation`. If doc-string is not followed by a declaration, it may be present only if at least one form is also specified, as it is otherwise taken to be a form. It is an error if more than one doc-string is present.

The forms constitute the body of the defined function; they are executed as an implicit `progn`.

The body of the defined function is implicitly enclosed in a `block` construct whose name is the same as the name of the function. Therefore `return-from` may be used to exit from the function.

Other implementation-dependent bookkeeping actions may be taken as well by `defun`. The name is returned as the value of the `defun` form. For example:

    (defun discriminant (a b c)
      (declare (number a b c))
      "Compute the discriminant for a quadratic equation.
       Given a, b, and c, the value b^2-4*a*c is calculated.
       The quadratic equation a*x^2+b*x+c=0 has real, multiple,
       or complex roots depending on whether this calculated
       value is positive, zero, or negative, respectively."
      (- (* b b) (* 4 a c)))
       => discriminant
       and now (discriminant 1 2/3 -2) => 76/9

The documentation string in this example neglects to mention that the coefficients `a`, `b`, and `c` must be real for the discrimination criterion to hold. Here is an improved version:

      "Compute the discriminant for a quadratic equation.
       Given a, b, and c, the value b^2-4*a*c is calculated.
       If the coefficients a, b, and c are all real (that is,
       not complex), then the quadratic equation a*x^2+b*x+c=0
       has real, multiple, or complex roots depending on
       whether this calculated value is positive, zero, or
       negative, respectively."

It is permissible to use `defun` to redefine a function, to install a corrected version of an incorrect definition, for example. It is permissible to redefine a macro as a function. It is an error to attempt to redefine the name of a special form (see table 5-1) as a function.

Next: Declaring Global Variables Up: Top-Level Forms Previous: Top-Level Forms