defgeneric [Macro]

defgeneric function-name gf-lambda-list [[!option | {!method-description}{*]]}
=> new-generic

option ::=(:argument-precedence-order {parameter-name}^+) | (declare {gf-declaration}^+) | (:documentation gf-documentation) | (:method-combination method-combination {method-combination-argument}{*) |} (:generic-function-class generic-function-class) | (:method-class method-class)

method-description ::=(:method {method-qualifier}{* specialized-lambda-list {[[{declaration}{*} | documentation]]} {form}{*})}

Arguments and Values::

function-name---a function name.

generic-function-class---a non-nil symbol naming a class.

gf-declaration---an optimize declaration specifier; other declaration specifiers are not permitted.

gf-documentation---a string; not evaluated.

gf-lambda-list---a generic function lambda list.

method-class---a non-nil symbol naming a class.

method-combination-argument---an object.

method-combination-name---a symbol naming a method combination type.

method-qualifiers, specialized-lambda-list, declarations, documentation, forms---as per defmethod.

new-generic---the generic function object.

parameter-name---a symbol that names a required parameter in the lambda-list. (If the :argument-precedence-order option is specified, each required parameter in the lambda-list must be used exactly once as a parameter-name.)

Description::

The macro defgeneric is used to define a generic function or to specify options and declarations that pertain to a generic function as a whole.

If function-name is a list it must be of the form (setf symbol). If (fboundp function-name) is false, a new generic function is created.

If (fdefinition function-name) is a generic function, that

generic function is modified. If function-name names an ordinary function, a macro, or a special operator, an error is signaled.

The effect of the defgeneric macro is as if the following three steps were performed: first, methods defined by previous defgeneric forms are removed;

[Reviewer Note by Barmar: Shouldn't this (second) be first?] second, ensure-generic-function is called; and finally, methods specified by the current defgeneric form are added to the generic function.

Each method-description defines a method on the generic function. The lambda list of each method must be congruent with the lambda list specified by the gf-lambda-list option. If no method descriptions are specified and a generic function of the same name does not already exist, a generic function with no methods is created.

The gf-lambda-list argument of defgeneric specifies the shape of lambda lists for the methods on this generic function. All methods on the resulting generic function must have lambda lists that are congruent with this shape. If a defgeneric form is evaluated and some methods for that generic function have lambda lists that are not congruent with that given in the defgeneric form, an error is signaled. For further details on method congruence, see section Congruent Lambda-lists for all Methods of a Generic Function.

The generic function passes to the method all the argument values passed to it, and only those; default values are not supported. Note that optional and keyword arguments in method definitions, however, can have default initial value forms and can use supplied-p parameters.

The following options are provided.

Except as otherwise noted,

a given option may occur only once.

*

The :argument-precedence-order option is used to specify the order in which the required arguments in a call to the generic function are tested for specificity when selecting a particular method. Each required argument, as specified in the gf-lambda-list argument, must be included exactly once as a parameter-name so that the full and unambiguous precedence order is supplied. If this condition is not met, an error is signaled. [Reviewer Note by Barmar: What is the default order?]

*

The declare option is used to specify declarations that pertain to the generic function. An optimize declaration specifier is allowed. It specifies whether method selection should be optimized for speed or space, but it has no effect on methods. To control how a method is optimized, an optimize declaration must be placed directly in the defmethod form or method description. The optimization qualities speed and space are the only qualities this standard requires, but an implementation can extend the object system to recognize other qualities. A simple implementation that has only one method selection technique and ignores optimize declaration specifiers is valid. The special, ftype, function, inline, notinline, and declaration declarations are not permitted. Individual implementations can extend the declare option to support additional declarations. [Editorial Note by KMP: Does "additional" mean including special, ftype, etc.? Or only other things that are not mentioned here?] If an implementation notices a declaration specifier that it does not support and that has not been proclaimed as a non-standard declaration identifier name in a declaration proclamation, it should issue a warning. [Editorial Note by KMP: The wording of this previous sentence, particularly the word "and" suggests to me that you can `proclaim declaration' of an unsupported declaration (e.g., ftype) in order to suppress the warning. That seems wrong. Perhaps it instead means to say "does not support or is both undefined and not proclaimed declaration."] The declare option may be specified more than once. The effect is the same as if the lists of declaration specifiers had been appended together into a single list and specified as a single declare option.

*

The :documentation argument is a documentation string to be attached to the generic function object, and to be attached with kind function to the function-name.

*

The :generic-function-class option may be used to specify that the generic function is to have a different class than the default provided by the system (the class standard-generic-function). The class-name argument is the name of a class that can be the class of a generic function. If function-name specifies an existing generic function that has a different value for the :generic-function-class argument and the new generic function class is compatible with the old, change-class is called to change the class of the generic function; otherwise an error is signaled.

*

The :method-class option is used to specify that all methods on this generic function are to have a different class from the default provided by the system (the class standard-method). The class-name argument is the name of a class that is capable of being the class of a method. [Reviewer Note by Barmar: Is change-class called on existing methods?]

*

The :method-combination option is followed by a symbol that names a type of method combination. The arguments (if any) that follow that symbol depend on the type of method combination. Note that the standard method combination type does not support any arguments. However, all types of method combination defined by the short form of define-method-combination accept an optional argument named order, defaulting to :most-specific-first, where a value of :most-specific-last reverses the order of the primary methods without affecting the order of the auxiliary methods.

The method-description arguments define methods that will be associated with the generic function. The method-qualifier and specialized-lambda-list arguments in a method description are the same as for defmethod.

The form arguments specify the method body. The body of the method is enclosed in an implicit block. If function-name is a symbol, this block bears the same name as the generic function. If function-name is a list of the form (setf symbol), the name of the block is symbol.

Implementations can extend defgeneric to include other options. It is required that an implementation signal an error if it observes an option that is not implemented locally.

defgeneric is not required to perform any compile-time side effects. In particular, the methods are not installed for invocation during compilation. An implementation may choose to store information about the generic function for the purposes of compile-time error-checking (such as checking the number of arguments on calls, or noting that a definition for the function name has been seen).

Examples::

Exceptional Situations::

If function-name names an ordinary function, a macro, or a special operator, an error of type program-error is signaled.

Each required argument, as specified in the gf-lambda-list argument, must be included exactly once as a parameter-name, or an error of type program-error is signaled.

The lambda list of each method specified by a method-description must be congruent with the lambda list specified by the gf-lambda-list option, or an error of type error is signaled.

If a defgeneric form is evaluated and some methods for that generic function have lambda lists that are not congruent with that given in the defgeneric form, an error of type error is signaled.

A given option may occur only once, or an error of type program-error is signaled.

[Reviewer Note by Barmar: This says that an error is signaled if you specify the same generic function class as it already has!] If function-name specifies an existing generic function that has a different value for the :generic-function-class argument and the new generic function class is compatible with the old, change-class is called to change the class of the generic function; otherwise an error of type error is signaled.

Implementations can extend defgeneric to include other options. It is required that an implementation signal an error of type program-error if it observes an option that is not implemented locally.

See Also::

section defmethod [Macro] , @xref{documentation; (setf documentation)} , section ensure-generic-function [Function] ,

generic-function,

section Congruent Lambda-lists for all Methods of a Generic Function

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