Common Lisp the Language, 2nd Edition

28.1.6.1. Introduction to Generic Functions

A generic function object contains a set of methods, a lambda-list, a method combination type, and other information.

Like an ordinary Lisp function, a generic function takes arguments, performs a series of operations, and perhaps returns useful values. An ordinary function has a single body of code that is always executed when the function is called. A generic function has a set of bodies of code of which a subset is selected for execution. The selected bodies of code and the manner of their combination are determined by the classes or identities of one or more of the arguments to the generic function and by its method combination type.

Ordinary functions and generic functions are called with identical function-call syntax.

Generic functions are true functions that can be passed as arguments, returned as values, used as the first argument to funcall and apply, and otherwise used in all the ways an ordinary function may be used.

A name can be given to an ordinary function in one of two ways: a global name can be given to a function using the defun construct; a local name can be given using the flet or labels special forms. A generic function can be given a global name using the defmethod or defgeneric construct. A generic function can be given a local name using the generic-flet, generic-labels, or with-added-methods special forms. The name of a generic function, like the name of an ordinary function, can be either a symbol or a two-element list whose first element is setf and whose second element is a symbol. This is true for both local and global names.

The generic-flet special form creates new local generic functions using the set of methods specified by the method definitions in the generic-flet form. The scoping of generic function names within a generic-flet form is the same as for flet.

The generic-labels special form creates a set of new mutually recursive local generic functions using the set of methods specified by the method definitions in the generic-labels form. The scoping of generic function names within a generic-labels form is the same as for labels.

The with-added-methods special form creates new local generic functions by adding the set of methods specified by the method definitions with a given name in the with-added-methods form to copies of the methods of the lexically visible generic function of the same name. If there is a lexically visible ordinary function of the same name as one of the specified generic functions, that function becomes the method function of the default method for the new generic function of that name.

The generic-function macro creates an anonymous generic function with the set of methods specified by the method definitions that appear in the generic-function form.

When a defgeneric form is evaluated, one of three actions is taken:

• If a generic function of the given name already exists, the existing generic function object is modified. Methods specified by the current defgeneric form are added, and any methods in the existing generic function that were defined by a previous defgeneric form are removed. Methods added by the current defgeneric form might replace methods defined by defmethod or defclass. No other methods in the generic function are affected or replaced.

• If the given name names a non-generic function, a macro, or a special form, an error is signaled.

• Otherwise a generic function is created with the methods specified by the method definitions in the defgeneric form.

Some forms specify the options of a generic function, such as the type of method combination it uses or its argument precedence order. They will be referred to as ``forms that specify generic function options.'' These forms are defgeneric, generic-function, generic-flet, generic-labels, and with-added-methods.

Some forms define methods for a generic function. They will be referred to as ``method-defining forms.'' These forms are defgeneric, defmethod, generic-function, generic-flet, generic-labels, with-added-methods, and defclass. Note that all the method-defining forms except defclass and defmethod are also forms that specify generic function options.