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

name

A symbol naming the dspec class

superspace

A symbol naming the superspace

documentation

A string describing the dspec class

undefiner

A function that generates the undefining form for the class

canonicalize

A function to canonicalize a dspec if it belongs to the class

prettify

A function to return a prettier form of a dspec of the class

definedp

A function to decide if a dspec of the class currently has a definition

object-dspec

A function to return the dspec from an object if it was defined by the class

defined-parts

A function to return all the currently defined parts in the class for a given a primary-name

aggregate-class

The aggregate dspec class for a part dspec

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 given, 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 . The function should returns 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 given, 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 matches the form

(dspec-class symbol )

If prettify is given, 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 given, 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. The definedp function 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 given, 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 the object-dspec functions in all dspec classes. The function should return a dspec for the object if that object was defined by the dspec class or nil otherwise. For example, the object-dspec function for package dspecs might be:

#'(lambda (obj)

    (and (packagep obj) 

         `(package ,(package-name obj))))

The object-dspec function is used by the "Find Source" menu option in the Inspector in the LispWorks IDE to find where the current object was defined.

If defined-parts is given, 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 calls the defined-parts functions with the dspec-primary-name of the dspec in each class that aggregates with it. The function should return a list of dspecs which are defined parts of the primary name in the class name . If this keyword is given, aggregate-class must also be given.

If aggregate-class is given, 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 this keyword is given, the defined-parts must also be given.

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

Example

See the section "Dspec classes" in the LispWorks User Guide .

See also

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