Skip to main content

5.4 Processing Of The User Interface Macros

Processing of the user interface macros

Processing of the user interface macros​

A list in which the first element is one of the symbols defclass, defmethod, defgeneric, define-method-combination, generic-function, generic-flet or generic-labels, and which has proper syntax for that macro is called a user interface macro form. This document provides an extended specification of the defclass, defmethod and defgeneric macros.

The user interface macros defclass, defgeneric and defmethod can be used not only to define metaobjects that are instances of the corresponding standard metaobject class, but also to define metaobjects that are instances of appropriate portable metaobject classes. To make it possible for portable metaobject classes to properly process the information appearing in the macro form, this document provides a limited specification of the processing of these macro forms.

User interface macro forms can be evaluated or compiled and later executed. The effect of evaluating or executing a user interface macro form is specified in terms of calls to specified functions and generic functions which provide the actual behavior of the macro. The arguments received by these functions and generic functions are derived in a specified way from the macro form.

Converting a user interface macro form into the arguments to the appropriate functions and generic functions has two major aspects: the conversion of the macro argument syntax into a form more suitable for later processing, and the processing of macro arguments which are forms to be evaluated (including method bodies).

In the syntax of the defclass macro, the initform and default-initarg-initial-value-form arguments are forms which will be evaluated one or more times after the macro form is evaluated or executed. Special processing must be done on these arguments to ensure that the lexical scope of the forms is captured properly. This is done by building a function of zero arguments which, when called, returns the result of evaluating the form in the proper lexical environment.

In the syntax of the defmethod macro the form* argument is a list of forms that comprise the body of the method definition. This list of forms must be processed specially to capture the lexical scope of the macro form. In addition, the lexical functions available only in the body of methods must be introduced. To allow this and any other special processing (such as slot access optimization), a specializable protocol is used for processing the body of methods. This is discussed in the section ``Processing Method Bodies.''

5.4.1 Compile File Processing Of The User Interface Macros​

Compile-file processing of the user interface macros

Compile-file processing of the user interface macros​

It is common practice for Common Lisp compilers, while processing a file or set of files, to maintain information about the definitions that have been compiled so far. Among other things, this makes it possible to ensure that a global macro definition (defmacro form) which appears in a file will affect uses of the macro later in that file. This information about the state of the compilation is called the compile-file environment.

When compiling files containing CLOS definitions, it is useful to maintain certain additional information in the compile-file environment. This can make it possible to issue various kinds of warnings (e.g., lambda list congruence) and to do various performance optimizations that would not otherwise be possible.

At this time, there is such significant variance in the way existing Common Lisp implementations handle compile-file environments that it would be premature to specify this mechanism. Consequently, this document specifies only the behavior of evaluating or executing user interface macro forms. What functions and generic functions are called during compile-file processing of a user interface macro form is not specified. Implementations are free to define and document their own behavior. Users may need to check implementation-specific behavior before attempting to compile certain portable programs.

5.4.2 The Defclass Macro​

The defclass macro

The defclass macro​

The evaluation or execution of a defclass form results in a call to the ensure-class function. The arguments received by ensure-class are derived from the defclass form in a defined way. The exact macro-expansion of the defclass form is not defined, only the relationship between the arguments to the defclass macro and the arguments received by the ensure-class function. Examples of typical defclass forms and sample expansions are shown in the Figures below.

(defclass plane (moving-object graphics-object) ((altitude :initform 0 :accessor plane-altitude) (speed)) (:default-initargs :engine jet))

(ensure-class 'plane ':direct-superclasses '(moving-object graphics-object) ':direct-slots (list (list ':name 'altitude ':initform '0 ':initfunction #'(lambda () 0) ':readers '(plane-altitude) ':writers '((setf plane-altitude))) (list ':name 'speed)) ':direct-default-initargs (list (list ':engine 'jet #'(lambda () jet))))

A defclass form with standard slot and class options and an expansion of it that would result in the proper call to ensure-class.

(defclass sst (plane) ((mach mag-step 2 locator sst-mach locator mach-location :reader mach-speed :reader mach)) (:metaclass faster-class) (another-option foo bar))

(ensure-class 'sst ':direct-superclasses '(plane) ':direct-slots (list (list ':name 'mach ':readers '(mach-speed mach) 'mag-step '2 'locator '(sst-mach mach-location))) ':metaclass 'faster-class 'another-option '(foo bar))

A defclass form with non-standard class and slot options, and an expansion of it which results in the proper call to ensure-class. Note that the order of the slot options has not affected the order of the properties in the canonicalized slot specification, but has affected the order of the elements in the lists which are the values of those properties.

The name argument to defclass becomes the value of the first argument to ensure-class. This is the only positional argument accepted by ensure-class; all other arguments are keyword arguments.

The direct-superclasses argument to defclass becomes the value of the :direct-super-classes keyword argument to ensure-class.

The direct slots argument to defclass becomes the value of the :direct-slots keyword argument to ensure-class. Special processing of this value is done to regularize the form of each slot specification and to properly capture the lexical scope of the initialization forms. This is done by converting each slot specification to a property list called a canonicalized slot specification. The resulting list of canonicalized slot specifications is the value of the :direct-slots keyword argument.

Canonicalized slot specifications are later used as the keyword arguments to a generic function which will, in turn, pass them to make-instance for use as a set of initialization arguments. Each canonicalized slot specification is formed from the corresponding slot specification as follows:

  • The name of the slot is the value of the :name property. This property appears in every canonicalized slot specification.

  • When the :initform slot option is present in the slot specification, then both the :initform and :initfunction properties are present in the canonicalized slot specification. The value of the :initform property is the initialization form. The value of the :initfunction property is a function of zero arguments which, when called, returns the result of evaluating the initialization form in its proper lexical environment.

    If the :initform slot option is not present in the slot specification, then either the :initfunction property will not appear, or its value will be false. In such cases, the value of the :initform property, or whether it appears, is unspecified.

  • The value of the :initargs property is a list of the values of each :initarg slot option. If there are no :initarg slot options, then either the :initargs property will not appear or its value will be the empty list.

  • The value of the :readers property is a list of the values of each :reader and :accessor slot option. If there are no :reader or :accessor slot options, then either the :readers property will not appear or its value will be the empty list.

  • The value of the :writers property is a list of the values specified by each :writer and :accessor slot option. The value specified by a :writer slot option is just the value of the slot option. The value specified by an :accessor slot option is a two element list: the first element is the symbol setf, the second element is the value of the slot option. If there are no :writer or :accessor slot options, then either the :writers property will not appear or its value will be the empty list.

  • The value of the :documentation property is the value of the :documentation slot option. If there is no :documentation slot option, then either the :documentation property will not appear or its value will be false.

  • All other slot options appear as the values of properties with the same name as the slot option. Note that this includes not only the remaining standard slot options (:allocation and :type), but also any other options and values appearing in the slot specification. If one of these slot options appears more than once, the value of the property will be a list of the specified values.

  • An implementation is free to add additional properties to the canonicalized slot specification provided these are not symbols accessible in the common-lisp-user package, or exported by any package defined in the ANSI Common Lisp standard.

Returning to the correspondence between arguments to the defclass macro and the arguments received by the ensure-class function:

The default initargs class option, if it is present in the defclass form, becomes the value of the :direct-default-initargs keyword argument to ensure-class. Special processing of this value is done to properly capture the lexical scope of the default value forms. This is done by converting each default initarg in the class option into a canonicalized default initarg. The resulting list of canonicalized default initargs is the value of the :direct-default-initargs keyword argument to ensure-class.

A canonicalized default initarg is a list of three elements. The first element is the name; the second is the actual form itself; and the third is a function of zero arguments which, when called, returns the result of evaluating the default value form in its proper lexical environment.

The metaclass class option, if it is present in the defclass form, becomes the value of the :metaclass keyword argument to ensure-class.

The documentation class option, if it is present in the defclass form, becomes the value of the :documentation keyword argument to ensure-class.

Any other class options become the value of keyword arguments with the same name. The value of the keyword argument is the tail of the class option. An error is signaled if any class option appears more than once in the defclass form.

In the call to ensure-class, every element of its arguments appears in the same left-to-right order as the corresponding element of the defclass form, except that the order of the properties of canonicalized slot specifications is unspecified. The values of properties in canonicalized slot specifications do follow this ordering requirement. Other ordering relationships in the keyword arguments to ensure-class are unspecified.

The result of the call to ensure-class is returned as the result of evaluating or executing the defclass form.

5.4.3 The Defmethod Macro​

The defmethod macro

The defmethod macro​

The evaluation or execution of a defmethod form requires first that the body of the method be converted to a method function. This process is described in the next section. The result of this process is a method function and a set of additional initialization arguments to be used when creating the new method. Given these two values, the evaluation or execution of a defmethod form proceeds in three steps. The first step ensures the existence of a generic function with the specified name. This is done by calling the function ensure-generic-function. The first argument in this call is the generic function name specified in the defmethod form. The second step is the creation of the new method metaobject by calling make-instance. The class of the new method metaobject is determined by calling generic-function-method-class on the result of the call to ensure-generic-function from the first step. The initialization arguments received by the call to make-instance are as follows:

  • The value of the qualifiers initialization argument is a list of the qualifiers which appeared in the defmethod form. No special processing is done on these values. The order of the elements of this list is the same as in the defmethod form.
  • The value of the lambda-list initialization argument is the unspecialized lambda list from the defmethod form.
  • The value of the specializers initialization argument is a list of the specializers for the method. For specializers which are classes, the specializer is the class metaobject itself. In the case of eql specializers, it will be an eql-specializer metaobject obtained by calling intern-eql-specializer on the result of evaluating the eql specializer form in the lexical environment of the defmethod form.
  • The value of the function initialization argument is the method function.
  • The value of the declarations initialization argument is a list of the declarations from the defmethod form. If there are no declarations in the macro form, this initialization argument either doesn't appear, or appears with a value of the empty list.
  • The value of the documentation initialization argument is the documentation string from the defmethod form. If there is no documentation string in the macro form this initialization argument either doesn't appear, or appears with a value of false.
  • Any other initialization argument produced in conjunction with the method function are also included.
  • The implementation is free to include additional initialization arguments provided these are not symbols accessible in the common-lisp-user package, or exported by any package defined in the ANSI Common Lisp standard.

In the third step, add-method is called to add the newly created method to the set of methods associated with the generic function metaobject. The result of the call to add-method is returned as the result of evaluating or executing the defmethod form. An example showing a typical defmethod form and a sample expansion is shown in this figure. The processing of the method body for this method is shown in this figure.

5.4.4 Processing Method Bodies​

Processing method bodies

Processing method bodies​

Before a method can be created, the list of forms comprising the method body must be converted to a method function. This conversion is a two step process.

Note:

The body of methods can also appear in the :initial-methods option of defgeneric forms. Initial methods are not considered by any of the protocols specified in this document.

The first step occurs during macro-expansion of the macro form. In this step, the method lambda list, declarations and body are converted to a lambda expression called a method lambda. This conversion is based on information associated with the generic function definition in effect at the time the macro form is expanded.

The generic function definition is obtained by calling ensure-generic-function with a first argument of the generic function name specified in the macro form. The :lambda-list keyword argument is not passed in this call.

Given the generic function, production of the method lambda proceeds by calling make-method-lambda. The first argument in this call is the generic function obtained as described above. The second argument is the result of calling class-prototype on the result of calling generic-function-method-class on the generic function. The third argument is a lambda expression formed from the method lambda list, declarations and body. The fourth argument is the macro-expansion environment of the macro form; this is the value of the &environment argument to the defmethod macro.

The generic function make-method-lambda returns two values. The first is the method lambda itself. The second is a list of initialization arguments and values. These are included in the initialization arguments when the method is created.

In the second step, the method lambda is converted to a function which properly captures the lexical scope of the macro form. This is done by having the method lambda appear in the macro-expansion as the argument of the function special form. During the subsequent evaluation of the macro-expansion, the result of the function special form is the methodfunction.

5.4.5 The Defgeneric Macro​

The defgeneric macro

The defgeneric macro​

The evaluation or execution of a defgeneric form results in a call to the ensure-generic-function function. The arguments received by ensure-generic-function are derived from the defgeneric form in a defined way. As with defclass and defmethod, the exact macro-expansion of the defgeneric form is not defined, only the relationship between the arguments to the macro and the arguments received by ensure-generic-function.

  • The function-name argument to defgeneric becomes the first argument to ensure-generic-function. This is the only positional argument accepted by ensure-generic-function; all other arguments are keyword arguments.

  • The lambda-list argument to defgeneric becomes the value of the :lambda-list keyword argument to ensure-generic-function.

  • For each of the options :argument-precedence-order, :documentation, :generic-function-class and :method-class, the value of the option becomes the value of the keyword argument with the same name. If the option does not appear in the macro form, the keyword argument does not appear in the resulting call to ensure-generic-function.

  • For the option declare, the list of declarations becomes the value of the :declarations keyword argument. If the declare option does not appear in the macro form, the :declarations keyword argument does not appear in the call to ensure-generic-function.

  • The handling of the :method-combination option is not specified.

The result of the call to ensure-generic-function is returned as the result of evaluating or executing the defgeneric form.