Common Lisp the Language, 2nd Edition
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.