function specs

[David A. Moon <Moon at SCRC-TENEX at MIT-MC>]

Here is some brief background information on function specs in the Lisp machine.
See page 136 in the gray (or blue, depending on whether you are from the North
or the South) Lisp Machine manual for further information.

The basic idea is that it is useful to store functions in more places than
the definition cell of a symbol, and it is dumb to have to make up generated
symbols when doing this.  The most immediate examples are internal functions
lexically nested inside other functions, methods in class/flavor systems, and
unnamed dispatch functions stored on property lists.  It is very useful to
have a name for such functions so that you can edit them, trace them, get
told their name in the debugger, etc.  It's also very useful to make the whole
thing extensible so users can add their own places to stash functions.

The convention is that the name of any function whose name isn't a symbol
is a list whose first element is a keyword identifying the kind of function,
and whose remaining elements are "arguments" to that keyword.  The first element
doesn't have to be an actual keyword; if it makes sense for a function spec
type to be confined to some particular package, the first element can be
a symbol in that package.

The operations on a function spec are defined by the following functions.
The names are fairly self-evident, so check a Lisp machine manual for details.

(FDEFINE function-spec definition &OPTIONAL carefully-flag no-query-flag)
(FDEFINEDP function-spec) => T or NIL
(FDEFINITION function-spec) => a function
(FDEFINITION-LOCATION function-spec) => a locative pointer to a definition cell
(FUNDEFINE function-spec)
(FUNCTION-PARENT function-spec) => NIL or (VALUES name type) of a top-level
  defining form which generated this function, perhaps along with other things.
  It might be a DEFSTRUCT, for example.
(COMPILER-FDEFINEDP function-spec) => returns T if will be fdefinedp at run time
(FUNCTION-SPEC-GET functions-spec indicator) => NIL or property
(FUNCTION-SPEC-PUTPROP function-spec value indicator)

One defines a new function spec type by putting a property on its keyword
symbol.  The property is a function which follows a protocol (which I won't
elaborate here) to implement the functions described above.  There is a default
handler to ease implementation of new function spec types.

The function spec types defined in the Lisp environment from which I am sending
this message are as follows.  I'll list and describe them all just to give you an
idea of how this might be used.  Certainly most of these do not belong in
Common Lisp--the point is that they are extensions implementable through a
predefined general mechanism.  The order is alphabetical, not rational.

(:DEFUN-METHOD name) -- an internal function used by the flavor system in
the implementation of a function named <name>; the internal function is called
directly when certain error checking is known to be unnecessary.

(:HANDLER flavor message) -- the function invoked when a certain message
is sent to an object of a certain flavor.  This is different from :METHOD
because of method inheritance and method combination.  This function spec
mainly exists so you can trace it.

(:INTERNAL function-spec index [name]) -- a function nested inside another
function, named function-spec.  index is a number to keep them unique and
name is an optional name (it exists if LABELS rather than a plain LAMBDA
was used to define the function.)

(:LAMBDA-MACRO symbol) -- the function which expands forms like ((symbol ...)...)

(:LOCATION locative) -- a function stored in a particular cell

(:METHOD flavor [modifiers...] message) -- a method which supplies part of
the behavior for a certain message to objects built out of a certain flavor.

(:PROPERTY symbol property) -- a function stored on a property list

(:SELECT-METHOD function-spec message) -- an internal function generated
by DEFSELECT, nested inside a select-function named function-spec.

(:WITHIN within-function renamed-function) -- a function which masquerades
as another function within a third function.  TRACE uses this.