Common Lisp the Language, 2nd Edition


next up previous contents index
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.

change_begin
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).
change_end

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

change_begin
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."

change_end

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 up previous contents index
Next: Declaring Global Variables Up: Top-Level Forms Previous: Top-Level Forms


AI.Repository@cs.cmu.edu