define-dspec-class Macro

Summary

Defines a dspec class.

Package

dspec

Signature

define-dspec-class name superspace documentation &key pretty-name undefiner canonicalize prettify definedp object-dspec defined-parts aggregate-class

Arguments

Description

The macro define-dspec-class defines a dspec class, providing handlers for definitions in that dspec class.

define-dspec-class defines name as a dspec class, inheriting from the dspec class superspace. superspace should be nil to define a new top-level dspec class.

documentation should be a string documenting the dspec class. For example "My Objects".

After evaluating a define-dspec-class form, name can be used by defining forms to record locations of definitions of that dspec class name by calling record-definition.

All of the remaining arguments described below can be omitted if not needed. The most important arguments for the LispWorks IDE are definedp and undefiner.

If undefiner is supplied, its value must be a function of one argument. When LispWorks wants to remove a definition, it will call the function with a canonical dspec of class name. undefiner should return a form that removes the current definition of that dspec. For example, the undefining form for package dspecs might be delete-package. If undefiner is omitted, then definitions of this class cannot be undefined.

If canonicalize is supplied, its value must be a function of one argument. The function will be called by canonicalize-dspec for a dspec of the given class. The value returned by the canonicalize function must be a fully canonical dspec of the given class. A typical use for the canonicalize function would be to remove extra options from the dspec which are not required to make the dspec unique. The canonicalize function should return nil for malformed dspecs and should take care not to signal an error. The default canonicalize function returns the dspec if it has the form:

(name symbol)

If prettify is supplied, its value must be a function of one argument. When LispWorks wants to print a dspec, for example in an error message, it will call the prettify function for the class of the dspec. The argument will be the canonical dspec and the function should return a dspec which is considered "prettier" for a user to see. The default prettify function returns the dspec unchanged.

If definedp is supplied, its value must be function of one argument. When LispWorks wants to discover if a given dspec is defined, it calls the function with the dspec-primary-name of the dspec. A call to definedp should return true if the primary name is defined in this dspec class and nil otherwise. The default definedp function always returns nil.

If object-dspec is supplied, its value must be a function of one argument. When LispWorks wants to find the dspec that created a given object (for example a package object created by a defpackage form), it calls every dspec class's object-dspec function. object-dspec should return a dspec for the object if that object was defined by the dspec class or nil otherwise. For example, object-dspec for package dspecs might be:

#'(lambda (obj)
    (and (packagep obj) 
         `(package ,(package-name obj))))

object-dspec is used by the menu commandFind Source in the LispWorks IDE Inspector tool to find where the current object was defined.

If defined-parts is supplied, its value must be a function of one argument. When LispWorks wants to find all the definitions that are parts of a given aggregate dspec class, it finds all the dspec classes that aggregate with the given class and calls their defined-parts functions with the dspec-primary-name. defined-parts should return a list of dspecs which are defined parts of the primary name in the class name. If defined-parts is supplied, aggregate-class must also be supplied.

If aggregate-class is supplied and non-nil, its value must be a symbol naming a dspec class that is the aggregate class of the parts defined by name dspecs. For example, the aggregate class of method is defgeneric because methods are the defined parts of a particular generic function. If aggregate-class is supplied, then defined-parts must also be supplied. If aggregate-class is nil then name is not a part class.

To make cl:documentation work for your dspec class, add a suitable method as described for documentation.

Examples

See 7.3.1 Dspec classes.

See also

canonicalize-dspec
def
dspec-primary-name
record-definition