REF PCL                                         Claire Budden  July 1990
									 Revised Julian Clinton  August 1990

	   COPYRIGHT University of Sussex 1990. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<    PORTABLE COMMON LOOPS    >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<


Portable Common Loops (PCL), May Day (REV 2).

Functions in the Programmer Interface

This section describes the functions, macros, special forms, and generic
functions provided by  Common Lisp Object  System Programmer  Interface.
The Programmer Interface  comprises the  functions and  macros that  are
sufficient for writing most object-oriented programs.

This section is reference material that requires a understanding of  the
basic concepts  of the  Common  Lisp Object  System. The  functions  are
arranged in alphabetical order for convenient reference.

The description  of  each function,  macro,  special form,  and  generic
function  includes  its  purpose,  its  syntax,  the  semantics  of  its
arguments and returned values, and aften an example and cross-references
to related functions.

The syntax description for a function, macro, or special form  describes
its  parameters.  The  description   of  a  generic  function   includes
descriptions of the methods that are defined on that generic function by
Common Lisp Object System.  A method signature is  used to describe  the
parameters and parameter specializers for each method.

The following is an example of the format for the syntax description  of
a generic function with the method signature for one primary method:

f x y &optional z &key  :k                            [generic function]
f (x class) (y t) &optional z &key :k                   [primary method]

This description indicates that the generic function f has two  required
parameters, x and y. In addition, there is an optional parameter z and a
keyword :k. The method signature indicates thast this method on  generic
function f has two required parameters, x, which must be an instance  of
the class class, and y, which can  be any object. In addition, there  is
an optional parameter z and a  keyword parameter :k. The signature  also
indicates that  this  method  on  f  is a  primary  method  and  has  no
qualifiers.

The syntax description for a generic function describes the  lambda-list
of the generic function itself, while the method signatures describe the
lambda-lists of the defined methods.

The generic functions descrtibed in  this book are all standard  generic
functions. They all use standard method combination.

It is useful to categorize the  functions and macros according to  their
role in this standard.

Tools Used For Simple Object-oriented Programming

These tools  allow  for  defining  new  classes,  methods,  and  generic
functions and for making instances. Some of the macros listed here  have
a corresponding function that performs the same task at a lower level of
abstraction.

call-next-method
change-class
defclass
defgeneric
defmethod
generic-flet
generic-function
generic-labels
initialize-instance
next-method-p
slot boundp
slot-value
with-accessors
with-added methods
with slots

Functions underlying the commononly used macros

add-methods
class-name
compute-applicable-methods
ensure-generic-function
find-class
find-method
function-keywords
make-instances-obsolete
no-applicable-method
no next method
reinitialize-instance
remove-method
shared-initialize
slot-exits-p
slot-makunbound
slot-missing
slot-unbound
update-instance-for-different-class
update-instance-for-redefined-class

Tools for declarative method combination

call-method
define-method-combination
invalid-method-error
method-combination-error
method-qualifiers

General Common Lisp Support tools

class-of
documentation
print-object
symbol-macrolet


add-method                                            [generic function]
	   generic-function method

add-method                                              [primary method]
	   (generic-function standard-generic-function)
	   (method method)

	   The generic  function  add-method  adds a  method  to  a  generic
	   function. It  destructively  modifies the  generic  function  and
	   returns the modified generic function as its result.

	   The generic-function argument is a generic function object.

	   The method argument is  a method object. The  lambda list of  the
	   method function must be congruent with lambda list of the generic
	   function, or an error is signaled.

	   The modified  generic function  is returned.  The result  of  add
	   method is eq to the generic-function argument.

	   If the given method agrees with an existing method of the generic
	   function on parameter specializers  and qualifiers, the  existing
	   method is replaced.

	   If the  method  object is  a  method object  of  another  generic
	   function, an error is signaled.


call-method                                                      [macro]
	   method next-method list

	   The macro call-method is used  in method combination. This  macro
	   hides the  implementation dependant  details of  how methods  are
	   called. It can be used only within an effective method form,  for
	   the name call-method is defined only within the lexical scope  of
	   such a form.


	   The macro call-method invokes the specified method, supplying  it
	   with arguments and with definitions for call next method and  for
	   next method-p. The arguments are the arguments that were supplied
	   to  the  effective  method  form  containing  the  invocation  of
	   call-method.  The  definitions   of  call-next-method  and   next
	   method-p rely on the list of  method objects given as the  second
	   argument to call method.

	   The call-next-method function available to the method that is the
	   first subform will call the first method in the list that is  the
	   second subform. The  call next-method funtion  available in  that
	   method, in turn, will call the second methods is exhausted.

	   The methods  argument is  a method  object; the  next-method-list
	   argument is a list of method objects.

	   A list whose first  element is the  make-method and whose  second
	   element is a Lisp form can be used instead of a method objects as
	   the first subform of call method  or as an element of the  second
	   subform of call-method.  Such a  list specifies  a method  object
	   whose method function has a body that is the given form.

	   The result of call method is the value or values returned by  the
	   method invocation.


call-next-method                                              [function]
	   &rest args

	   The function call-next-method  can be used  within the body  of a
	   method defined by a method-defining form to call the next method.

	   The function  call  next  method  returns  the  value  or  values
	   returned by the method it calls. If there is no next method,  the
	   generic function no-next-method is called.

	   The type of  method combination used  determines the next  method
	   accroding to the following rules:

	   If call next-method is used in an :around method, the next method
	   is the next most specific :around method, if one is applicable.

	   If there are no :around method, the next method is the next  most
	   specific :around method, if one is applicable.

	   If there are no :around methods at all or if call-next-method  is
	   called by the  least specific :around  method, other methods  are
	   called as follows:

	   - All  the :before  methods  are called,  in  most-specific-first
	   order. The function  call-next-method cannot be  used in  :before
	   methods.

	   - The most specific primary method is called. Inside the body  of
	   a primary method, call-next-method may be used to pass control to
	   the next most specific primary method.

	   - All the :after methods are called in most-specific-last  order.
	   The function call-next-method cannot be used in :after methods.

	   When call-next-method is called with no arguments, it passes  the
	   current method's original arguments  to the next method.  Neither
	   argument defaulting, nor using setq, nor rebinding variables with
	   the same names  as parameters  of the method  affects the  values
	   call-next-method passes to the method it calls.

	   When call-next-method  is  called  with  arguments  to  call-next
	   method, the  following rule  must be  satisified or  an error  is
	   signaled: The ordered set of methods applicable for a changed set
	   of arguments  for call-next-method  must be  be the  same as  the
	   ordered set of applicable methods  for the original arguments  to
	   the generic  function. Optimiztions  of  the error  checking  are
	   possible,  but   they   must   not   change   the   sematics   of
	   call-next-method.

	   If call-next-method is called  with arguments but omits  optional
	   arguments, the next method called defaults those arguments.

	   The  function  call-next-method  returns  the  value  or   values
	   returned by the method it calls.

	   Further computation is possible after call-next-method returns.

	   The definition  of  the functions  call-next-method  has  lexical
	   scope (for it is defined only within the body of a method defined
	   by a method-defining form) and indefinite extent.

	   For generic functions using a type of method combination  defined
	   by the short form of define-method-combination,  call-next-method
	   can be used in :around methods only.

	   The function next-method-p  can be  used to test  whether or  not
	   there is a next method.

	   If call-next-method is used in methods that do not support it, an
	   error is signaled.


change-class                                          [generic function]
	   instance new-class

change-class                                            [primary method]
	   (instance standard-object)
	   (new-class standard-class)

change-class                                            [primary method]
	   (instance t)
	   (new-class symbol)

	   The  generic  function  change-class  changes  the  class  of  an
	   instance to a  new class. It  destructively modifies and  returns
	   the instances.

	   If in the old class, the value of that slot of the same name as a
	   local in the new class, the value of that slot is retained.  This
	   means that if the slot has a value, the class, the value of  that
	   slot is retained. This  means that if the  slot has a value,  the
	   value returned by slot-value after change-class is invoked is eq1
	   to the  value  returned  by  slot  value  after  change-class  is
	   invoked. Similarly, if the slot was unbound, it remains  unbound.
	   The other slots are intialized.

	   The instance argument is a Lisp object, The new-class argument is
	   a class object or a symbol that  names a class. If the second  of
	   the  prodeeding  methods   is  selected,   that  method   invokes
	   change-class on instance and (find-class new-class). The modified
	   instance is returned .  The result of change-class  is eq to  the
	   instance argument.

Examples:

(defclass position () ())

(defclass x-y-position (position)

	((x :initform 0 :initarg :x)
	 (y :initform 0 :initarg :y)))

(defclass rho-theta-position (position)
	((rho :initform 0)
	 (theta :initform 0)))

(defmethod update-instance-for-different-class :before
			((old x-y-position)
			 (new rho-theta-position)
			 &key)

	;; Copy the position information from old to new make ne w
	;; be a rho-theta-position at the same position s old.
	(let ((x (slot-value old 'x))
		  (y (slot-value old 'y)))
		(setf (slot-value new 'rho) (sqrt (+ (* x x) (* y y)))
			  (slot-value new 'theta) ( atan y x))))

;;; At this point an instance of the class x-y-position can be
;;; changed to be an instance of the rho-theta-position
;;; using change-class:

(setq p1 (make-instance 'x-y-position :x 2 :y 0))

(change-class p1 'rho-theta-position)

;;; The result is that the instance bound to p1is now
;;; an instance of the class rho-theta-position.
;;; The update-instance-for-different-class method
;;; performed the initialization of the rho and theta
;;; slots based on the values of the x and y slots.
;;; which were maintained by the old instance.

	   After completing  all others  actions, change-class  invokes  the
	   generic function update-instance-for-different-class. The generic
	   function  update-instance-for-different-class  can  be  used   to
	   assign values to slots in the transformed instance.

	   The   generic   function   change-class   has   several   sematic
	   difficulties. First, it performs a destructive operation that can
	   be invoked within a method on an instance that was used to select
	   that method. When multiple  methods are involved because  methods
	   are being combined, the methods  currently executing or about  to
	   be  executed   may  no   longer  be   applicable.  Second,   some
	   implementations might use compiler optimizations of slot  access,
	   and when the  class of  instance is changed  the assumptions  the
	   compiler made might be violated.  This implies that a  programmer
	   must not  use  change-class inside  a  methods for  that  generic
	   function access any slots, or the results are undefined.



class-name                                            [generic function]
	   class

class-name                                              [primary method]
	   (class class)

	   The generic function class-name takes a class object and  returns
	   its name. The  class argument  is a class  object. The  new-value
	   argument is any object. The name of the given class is  returned.
	   The name ofan anonymous class is nil.

	   If S is a symbol such  that S =(class-name C) and C  =(find-class
	   S), then S is the proper name of C.



(setf class-name)                                    [generic functions]
	   new-value class
(setf class-name)                                       [primary method]
	   new-value (class class)

	   The generic function (self-class name)  takes a class object  and
	   sets its  name.  The  class  argument  is  a  class  object.  The
	   new-value argument is only object.


class-of object                                               [function]

	   The function class of returns the class of which the given object
	   is an instance. The argument to class of many be any Common  Lisp
	   object. The  function class  of returns  the class  of which  the
	   argument is an instance.


compute-applicable-methods                                    [function]
	   generic-function
	   function-arguments

	   Given a generic function  and a set  of arguements, the  function
	   computer-applicable-methods returns the set  of methods that  are
	   applicable for those arguments.

	   The  methods  are  sorted  according  to  proceedure  order.  The
	   generic-function argument must be a generic function object.  The
	   function-arguments argument is  a list of  the arguments to  that
	   generic function. The result is a  list of the arguments to  that
	   generic function. The result is a list of the applicable  methods
	   ibn order of precedence.


defclass class-name ({superclass-name}*)                         [macro]
		 ({slot-specifier}*) || |class-option ||

		class-name ::= symbol
		superclass-name ::=symbol
		slot-specifer ::= slot-name | (slot-name || | slot-option ||)
		slot-name ::= symbol
		slot-option ::=   { :reader reader-function-name}*
						| { :writer writer-function-name}*
						| { :accessor reader-function-name}*
						| { :allocation allocation-type}*
						| { :initarg initarg-name}*
						| { :type type-specifier}*
						| { :documentation string}*

		reader-function-name ::= symbol
		writer-function-name ::= function-name/
		function-name ::= {symbol | (setf symbol)}
		initarg-name ::= symbol
		allocation-type ::= :instance | : class
		class-option ::= (:default-initargs initarg-list)
					   | (:documentation string)
					   | (:metaclass class-name)
		initarg-list ::= {initarg-name default-initial-value-form}*

	   The macro defclass defines a new named class. It returns the  new
	   class object as its result.

	   The  syntax   of  defclass   provides  options   for   specifying
	   initialization  arguments  for  slots,  for  specifying   default
	   initialization values for slots, and for requesting that  methods
	   on specified  generic functions  be automatically  generated  for
	   reading and  writing the  values  of slot.  No reader  or  writer
	   functions are  defined  by  default; their  generations  must  be
	   explicitly requested.

	   Defining a new a class also causes a type of the same name to  be
	   defined. The predicate (typep object class-name) returns true  if
	   the class of the given object is class-name itself or a  subclass
	   of the class  class-name. A class  object can be  used as a  type
	   specifier. Thus (typep object class) returns true if class of the
	   object is class itself or a subclass of class.

	   The class-name  argument  is a  non-nil  symbol. It  becomes  the
	   proper name of  the new class.  If a class  with the same  proper
	   name already exists  and that  class is an  instance of  standard
	   class, and if  the defclass form  for the definition  of the  new
	   class specifies a class of  class standard class, the  definition
	   of the existing class is replaced.

	   Each superclass-name argument is a non-nil symbol that  specifies
	   a direct superclass of the new class. The new class will  inherit
	   slots and  methods from  each of  its direct  superclasses,  from
	   their direct superclass, and so on.

	   Each slot-specifier argument is the name of a list consisting  of
	   the slot  name  followed  by  zero  or  more  slot  options.  The
	   slot-name argument is a symbol  that is systematically valid  for
	   use as a variable name. If there are any duplicate slot names, an
	   error is signaled.

	   The following slot options are available:

	   The :reader slot options specifies that an unqualified method  is
	   to be defined on the generic function named reader function  name
	   to read the value of the given slot. The reader-function-name  to
	   read the  value  of  the given  slot.  The  reader-function  name
	   argument is  a non-nil  symbol. The  :reader slot  option may  be
	   specified more than once for a given slot.

	   The :writer slot option specifies  that an unqualified method  is
	   to be defined on the generic function named  writer-function-name
	   to write the value of the slot. The writer function-name argument
	   is a function-name. The :writer slot option may be specified more
	   than once for a given slot.

	   The :accessor slot opition  specifies that an unqualified  method
	   is  to   be   defined   on  the   given   slot   function   named
	   reader-function-name to read the value of the given slot and that
	   an unqualified method is to  be defined on tyhe generic  function
	   named (setf reader function-name) to be used with setf to  modify
	   the value of  the slot.  The reader  function-name argument  is a
	   non-nil symbol. The :accessor slot  option may be specified  more
	   than once for a given slot.

	   The :allocation slot option is  used to specify where storage  is
	   to be allocated  for the given  slot. Storage for  a slot may  be
	   located in  each instance  or  in the  class object  itself,  for
	   example. The value of the allocation- type argument can be either
	   the keyword :instance or the keyword :class. The :allocation slot
	   option may be  specified at most  once for a  given slot. If  the
	   :allocation slot option is not specified, the effect is the  same
	   as specifying :allocation :instance.

	   If allocation-type :instance, a local  slot of the given naem  is
	   allocated in each instance of the class.

	   If allocation-type is :class, a shared slot of the given name  is
	   allocated. The value of  the slot is shared  by all instances  of
	   the class. If a class defines  such as shared slot, any  subclass
	   C1 of C2 will share this single slot unless the defclass form for
	   C2 specifies a slot of the same name or there is a superclass  of
	   C2 that precedes C1 in the  class precedence list of C2 and  thta
	   defines a slot of the same name.

	   The :initform slot option  is used to  provide a default  initial
	   value form to  be used  in the  initialization of  the slot.  The
	   :initform slot option may be specified  at most once for a  given
	   slot. This form  is evaluated every  time it is  used to at  most
	   once for a given slot. The lexical environment in which this form
	   is evaluated is  the lexical  environment in  which the  defclass
	   form was evaluted Note that  the lexical environment refers  both
	   to variables  and  to functions.  For  local slots,  the  dynamic
	   environment is the dynamic environment in which make instance was
	   called; for shared slots, the dynamic environment is the  dynamic
	   envioronment in which the defclass form was evaluated.

	   No implementation is permitted to  extend the syntax of  defclass
	   to  allow  (slot  name  form)  as  abbreviation  for  (slot  name
	   :initiform). The initform slot option declares an  initialization
	   argument  named   initarg.   name   and   specifies   that   this
	   initialization argument  the given  slot. It  the  initialization
	   argument has  a value  in the  call to  initialize instance,  the
	   value will  be  stored  into  the  given  slot,  and  the  slot's
	   :initform slot option, if any, is  not evaluated. If none of  the
	   initialization arguments specified for a given slot has a  value,
	   the slot is initialized according  to the :initform slot  option,
	   if specified. The :initarg-name argument can be any symbol.

	   The :type slot  option specifies  that the contents  of the  slot
	   will always  be  of  the  specified  data  type.  It  effectively
	   declares the  result type  of the  reader generic  function  when
	   applied to an object of this  class. The result of attempting  to
	   store in a slot a  value that does not  statisfy the type of  the
	   slot. The :type of the slot  is undefined. The :type slot  option
	   may be specified at most once for a given slot.

	   The :documentation slot  option provides  a documentation  string
	   for the slot.

	   Each class  option is  an option  provides a  documentation  that
	   refers to  the  class as  a  whole or  to  all class  lsots.  The
	   following class options are available:

	   The :default-initargs  class  option is  followed  by a  list  of
	   alternating initialization  argument  names and  default  initial
	   value forms. If any of these initialization names does not appear
	   in the initialization argument list supplied to make-instance the
	   corresponding default initial  value form is  evaluated, and  the
	   initialization argument name  and form's value  are added to  the
	   end of the  initialization argument list  before the instance  is
	   created. The default initial value form is evaluated each time it
	   is used. The lexical environment  in which this form is  evaluted
	   is the lexical environment in which make-instance was called.  If
	   an initialization  argument  name  appears more  than  once  in a
	   :default-initargs  class  option,  and  error  is  signaled.  The
	   :documentation class option may be specified at most once.

	   The :metaclass optionis  used to  specify that  instances of  the
	   class being  defined are  to have  different metaclass  than  the
	   default provided by  the system (the  class standard-class).  The
	   :metaclass option may be specified at most once.

	   The new class object is returned as the result.

	   If a class  witrh the same  proper name already  exists and  that
	   class is an instance of standard-class, and if the defclass  form
	   for the definition at the time that they are next accessed.

	   Note the following rules of defclass for standard classess:

	   It is  not required  that the  superclass be  defined before  the
	   defclass form for that class is evaluated.

	   All the superclass of a class must be defined before an  instance
	   of the class can be made.

	   A class must  be defined  before it can  be used  as a  parameter
	   specializer in a defmethod form.

	   The Object System my be extended to cover situations where  these
	   rules are not obeyed.

	   Some slot options are inherited  by a class from its  superclass,
	   and some can  be shadowed or  altered by providing  a local  slot
	   description.  No  class  options  except  :default-initargs   are
	   inherited. For  a  detailed description  of  how slots  and  slot
	   opitions ar inherited, see CLtL2, 28.1.2.

	   The options to defclass can  be extended. An implementation  must
	   signal an error if  it observes a class  option or a slot  option
	   that is not implemented locally.

	   It is valid to specify more than one reader, writer, accessor, or
	   initialization argument  for a  slot. No  other slot  option  may
	   appear more than once in a  single slot description, or an  error
	   is signaled.

	   If no reader, writer, or accessor is specified for a slot can  be
	   accessed only by the function slot value.



defgeneric function-name lambda-list                             [macro]
			|| |option|  {method-description}*}}

		 function-name ::= {symbol |(setf symbol)}
		 lambda-list ::= ( {var}*
						   |&optional {var| (var)}*
						   |&rest var|
						   |&key {keyword-parameter}*
						   |&allow-other-keys||)

		keyword-parameter::= var|({var|keyword var)})
		option ::= (argument-precedence-order {parameter-name}*)
				 | (declare {declaration}+)
				 | (:documentation string)
				 | (:method-combination symbol {arg}*)
				 | (:generic-function-class class-name)
				 | (:method-class class-name)
		method-description ::= (:method {method-qualifier}*
								 specialized-lambda-list
								 [] {declaration}
								 | documentation []
								 {form}*)
		method-qualifier ::= non-nil-atom
		specialized-lambda-list ::=
			  ( {var|(var parameter-specializer-name)}*
				[&optional {var|(var | initform
									 | supplied-p-parameter]])}*]
				[&rest var]
				[&key {specialized-keyword-parameter}*
					| &allow-other-keys]]
				[&aux {var | (var [initform])}*])
		specialized-keyword-parameter ::=
				var | ({var|(keyword var)}
						[initform [supplied-p-parameter]])
		parameter-specializer-name ::= symbol
									   | eql eql-specializer-form)

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

	   If (fboundp  function-name) is  nil, a  new generic  function  is
	   created.  If  (fdefinition   function-specifier)  is  a   generic
	   function, that  generic function  is modified.  If  function-name
	   names a  non-generic function,  a macro,  or a  special form,  an
	   error is signaled.

	   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   lambda-list  option.  If   this
	   condition does not hold, and error is signaled.

	   The macro defgeneric  returns the geneic  function object as  its
	   result.

	   The function-name argument is a non-nil  symbol or a list of  the
	   form (setf symbol).

	   The lambda-list  argument is  an  ordinary lambda-list  with  the
	   following exceptions:

	   The use of &aux is not allowed.

	   Optional and keyword arguments may not have default initial value
	   forms noruse supplied-p parameters. The generic function  passess
	   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 forms and can use supplied-p parameters.

	   The following options are provided. A given option may occur only
	   once, or an error is signaled.

	   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  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.

	   The declare option is used  to specify declarations that  pertain
	   to the  generic  function.  The following  standard  Common  Lisp
	   declaration is allowed:

	   - An  optimize  declaration 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  this  standard
	   requires, but an implementation can extend the Common Lisp Object
	   System to recognize other qualities. A simple implementation that
	   has only one method selection technique and ignores the  optimize
	   declaration 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.  If
	   am implementation notices a declaration that does not support and
	   that has not been proclaimed  as a non-standard declaration  name
	   in a declaration proclamation, it should issue a warning.

	   The :documentation  argument  associates a  documentation  srting
	   with the generic function. The documentation type for this string
	   function. The form (documentation function-name/'function) may be
	   used to retrieve this string.

	   The :generic function class  option may be  used to specify  that
	   the generic  function  is to  have  a differect  class  than  the
	   default provided by the system (class standard-generic-function).
	   The class-name argument is the name specifies an existing generic
	   function    that    has    a    different    value    for     the
	   :generic-function-class argument  and  the new  generic  function
	   class is  compatable  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
	   the 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.

	   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  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
	   list of the form (setf symbol), the name of the block is symbol.

	   The generic function object is returned as the result.

	   The effect  of the  defgeneric macro  is as  the following  three
	   steps  were  performed:  first,   methods  defined  by   previous
	   defgenric forms are  removed; second, ensure-generic-function  is
	   called; and finally, methods specified by the current  defgeneric
	   form are added to generic function.

	   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 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-list
	   that are  congruent with  this  shape. If  a defgeneric  form  is
	   evaluated and  some  methods  for  thast  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 CLtL2, section 28.1.4.

	   Implementation 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.

	   See   CLtL2,   section   28.1.6.4.   as   well   as    defmethod,
	   ensure-generic-function, and generic-function.


define-method-combination name                                   [macro]
						  [[ |short-form-option]]
define-method-combination  name lambda-list                      [macro]
						   ({method-group-specifier}*)
						   [(:arguments . lambda-list)]
						   [(:generic-function generic-fn-symbol)]
						   []{declaration}* |doc-string]]
						   {form}*

		short-form-option ::= :documentation string
							| :identity-with-one-argument boolean
							| :operator operator

		method-group-specifier ::=(variable {{qualifier-pattern} =
									 |predicate}
								   [[|ong-form-option]])
		long-form-option::= :description format-string
						  |:order order
						  |:required boolean

	   The macro define-method-combination is  used to define new  types
	   of method combination.

	   There are two forms of define-method-combination. The short  form
	   is a simple facility for the  cases that are expected to be  most
	   commonly needed. The long form is more powerful but more verbose.
	   It resembles defmacro in that the body is an expression,  usually
	   using backquote,  that  computes  a  Lisp  from.  Thus  arbitrary
	   control structures can be implemented. The long form also  allows
	   arbitrary processing of method qualifiers.

	   In  both  the  short  and  long  forms,  name  is  a  symbol.  By
	   convention, non-keyword, non-nil symbols are usually used.

	   The short-form syntax of define method-combination is  recognized
	   when the second subform  is a non-nil symbol  or is not  present.
	   When the short from is used, name is defined as a type of  method
	   combination that  produces  a  Lisp  form  (operator  method-call
	   method-call ...). The operator is a  symbol that can be the  name
	   of a  function,  macro, or  special  form. The  operator  can  be
	   specified by a keyword option; it defaults to name.

	   Keyword options for the short form are the following:

	   The   :documentation   option   is    used   to   document    the
	   method-combination type.

	   The :identify-with-one-argument  option enables  as  optimization
	   when boolean is true (the default is false). If there is  exactly
	   one appliable  method and  it is  a primary  method, that  method
	   serves as the effective method  and operator is not called.  This
	   optimization avoids the need to create a new effective method and
	   avoids the overhead of a  function call. This option is  designed
	   to be used with operators such as progn, and, +, and max.

	   The :operator  option specifies  the name  of the  operator.  The
	   operator argument is a symbol that can be the name of a function,
	   macro, or  special form.  By convention,  name and  operator  are
	   often the  same  symbol. This  is  the  default, but  it  is  not
	   required.

	   None of the subforms is evaluted.

	   These types  of  method  combination require  one  qualifier  per
	   method. An error is signaled if there are applicable methods with
	   no qualifiers or with  qualifiers that are  not supported by  the
	   method combination type.

	   A method combination precedure defined in this way recognizes two
	   roles for methods.  A method  whose one qualifier  is the  symbol
	   naming this type of method combination is defined to be a primary
	   method. At least one  primary must be applicable  or an error  is
	   signaled. A  method  with :around  as  its one  qualifier  is  an
	   auxilary method that  behaves the  same as an  :around method  in
	   :around methods; it cannot be used in primary methods defined  by
	   the short form of the define-method combination macro.

	   A method combination  procedure defined  in this  way accepts  an
	   optional   argument    named    order,    which    defaults    to
	   :most-specific-first. A value of :most-specific-last reverses the
	   order of the primary methods without affecting the iorder of  the
	   auxilary methods.

	   The short form automatically includes error checking and  support
	   for :around methods.



defmethod function-name {method-qualifier}*                      [macro]
		  specialized-lambda-list
		  [[ {declaration}* |doc-string]] {form}*

	   function-name ::= {symbol|setf symbol)}
	   method-qualifier::=non-nil-atom
	   parameter-specialier-name::=symbol|(eql-specializer-form)

	   The macro defmethod defines a method on a generic function.

	   If (fboundp function-name) is nil, a generic function is  created
	   with default  values  for  the argument  precedence  order  (each
	   argument is more specific than the arguments to its right in thwe
	   argument list),  for  the  generic  function  class,  (the  class
	   standard generic-function),  for  the  method  class  (the  class
	   standard-method),  and  for  tyhe  mthod  combination  type  (the
	   standard method combination type). The lambda-list of the generic
	   function is congruent  with the lambda-list  of the method  being
	   defined; if the  defmethod form mentions  keyword arguments,  the
	   lambda-list of trhe  generic function will  mention &key (but  no
	   keyword  arguments).   If  function-name   names  a   non-generic
	   function, a macro, or a special form, an error is signaled.

	   If a generic function is currently named by function-name,  where
	   function-name is a symbol  or a list of  the form (setf  symbol),
	   the  lambda-list  of  the  method  must  be  congruent  with  the
	   lambda-list of the generic function.  If this condition does  not
	   hold, an error is signaled.

	   The function-name argument is a non-nil  symbol or a list of  the
	   form (setf symbol).  It names  the gernic function  on which  the
	   method is defined.

	   Each method-qualifier  argument  is an  object  that is  used  by
	   method  combination  to  identufy  the  given  method.  A  method
	   qualifier is  a  non-nil atom.  The  method combination  type  my
	   further restrict what  a method  qualifier may  be. The  standard
	   method combination type allows for unqualified methods or methods
	   whose sole qualifier is the keyword :before, the keyword  :after,
	   or the keyword :around.

	   A  specializer-lambda-list   is   like   an   ordinary   function
	   lambda-list except that the name  of a required parameter can  be
	   replaced  by  a  specializer  parameter,  a  list  of  the   form
	   (variable-name-parameter-specializer-name).     Only     required
	   parametersmay  specialized.  A  parameter  specialier  name  is a
	   symbol that  names a  class or  [eql] eql-specializer-form).  The
	   parameter specializer  name (eql  eql-specializer-form  indicates
	   that  the  corresponding  argument  must  be  applicable.  If  no
	   parameter specializer  name is  specified  for a  given  required
	   parameter, the parameter specialier  defaults to the class  names
	   t.

	   The form  arguments sp[ecify  the method  body. The  body of  the
	   method is enclosed  in an  implicit block.  I 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 symbol.

	   The result of defmethod is the method object.

	   The class of the method object  that is created is that given  by
	   the method  class option  of the  generic function  on which  the
	   method is defined.

	   If the generic functions already hs a method that agrees wih  the
	   method being defined  on parameter  specializers and  quliaifers,
	   defmethod replaces the  existing method  with the  one now  being
	   defined.

	   The  parameter  specializers  are  derived  from  the  parameters
	   specializer name sa adescribed in section 28.1.6.2.

	   The expansion  of defmethod  macro  refers to  each  specializers
	   parameter  (see  the  ignore  declaration  specifier),  including
	   parameters that have an explicit parameter specializer name of t.
	   This means that a compiler warningdoes  not occur if the body  of
	   the method does not refer to a specialized parameter. Note that a
	   parameter  that  specilizes  on  t  is  not  synonymous  with  an
	   unspecialized parameter in ths content.



documentation                                         [generic function]
				&optional doc-type
documentation                                           [primary method]
				(method standard-method)
				&optional doc-type
documentation                                           [primary method]
				(generic-function standard-generic-function)
				&optional doc-type
documentation                                           [primary method]
				(class standard-class)
				&optional doc-type
documentation                                           [primary method]
				(method-combination method-combination)
				&optional doc-type
documentation                                           [primary method]
				(slot-description standard-slot-description)
				&optional doc-type
documentation                                           [primary method]
				(symbol symbol)
				&optional doc-type
documentation                                           [primary method]
				(list list)
				&optional doc-type

	   The ordinary function documentation is a symbol is replaced  by a
	   generic function. The generic function documentation returns  the
	   documentation string associated  with the given  object if it  is
	   available; otherwise documentation returns nil.

	   The first argument  of documentationisa  symbol, a  function-name
	   list of  the  form (setf  symbol),  a method  object,  a  generic
	   function  object,  a  method   combination  object,  or  a   slot
	   descriptionobject. Whether a second  argument should be  supplied
	   depends on the type of the first argument.

	   If the  first  agrument  is a  method  object,  a  classobject, a
	   generic function object, a method  combination object, or a  slot
	   dscription object, the second argument  must not be supplied,  or
	   an error is signaled.

	   If the argument is a symbol or a list of the form (setf  symbol),
	   the second argument must be supplied.

	   - The forms

	   (documentation symbol 'function)

	   and

	   (documentation '(setf symbol) 'function)

	   return  the  documentation  string   of  the  function,   generic
	   function, special form, or macro named by the symbol or list.

	   -  The  form   (documentation  symbol   'variable)  returns   the
	   documentation string of the special variable or constant named by
	   the symbol.

	   -  The  form  (documentation   symbol  'structure)  returns   the
	   documentation string  of the  defstruct  structure named  by  the
	   symbol.

	   - The form (documentation symbol 'type) returns the documentation
	   string of the  class object named  by te symbol,  if there is  no
	   such class,  it  returns the  documentation  string of  the  type
	   specifier named by the symbol.

	   - The form (documentation symbol 'setf) returns the documentation
	   string of the defsetf  or define-setf-method defintion string  of
	   the method combination type named by the symbol.

	   An implementation (documenation  may extend the  set symbol  that
	   are acceptable  as  the  second  argument. If  a  symbol  is  not
	   recognized as an  acceptable argument by  the implementation,  an
	   error must be signaled.

	   The documenation  string  associated  with the  given  object  is
	   erturned unless  none is  available, in  which case  documenation
	   returns nil.



(setf documentation)                                  [generic function]
	   new-value
	   x
	   &optional doc-type

(setf documentation)                                  [primary function]
	   new-value
	   (method standard-method)
	   &optional doc-type

(setf documentation)                                  [primary function]
	   new-value
	   (generic-function standard-generic-function)
	   &optional doc-type

(setf documentation)                                  [primary function]
	   new-value
	   (class standard-class)
	   &optional doc-type

(setf documentation)                                  [primary function]
	   new-value
	   (method-combination method-combination)
	   &optional doc-type

(setf documentation)                                  [primary function]
	   new-value
	   (slot-description standard-slot-description)
	   &optional doc-type

(setf documentation)                                  [primary function]
	   new-value
	   (symbol symbol)
	   &optional doc-type

(setf documentation)                                  [primary function]
	   (list list)
	   &optional doc-type

	   The generic function (setf documentation)  is used to update  the
	   documentation.

	   The  first   argument  of   (setf   documentation)  is   te   new
	   documentation.

	   The second argument of documentation is a symbol, a function-name
	   list pf the form (setf symbol), a method object, a class  object,
	   a generic function object, a method combination object, or a slot
	   description object. Whether a  third argument should be  supplied
	   depends on the type of the second argument.



ensure-generic-function function-name                         [function]
	   &key
	   :lambda-list
	   :argument-precedence-order
	   :declare
	   :documentation
	   :generic-function-class
	   :method-combination
	   :method-class
	   :environment

	   function-name::= {symbol | (setf symbol)}

	   The function ensure-generic-function is used to define a globally
	   named generis function with  no methods or  to specify or  modify
	   options and declarations that pertain to a globally named generic
	   function as a whole.

	   If (fboundp  function-name) is  nil, a  new generic  function  is
	   created.  If   (fdefinition  function-name)   is  a   non-generic
	   function, a macro, or a special form, an error is signaled.

	   If  function-name  specifies  a   generic  function  that   has a
	   different value for any of  the following arguments, the  generic
	   function    is    modified    to     have    the    new     value
	   :argument-precedence-order,       :declare,       :documentation,
	   :method-combination.

	   If function specifies  a generic  function that  has a  different
	   :method-class value,  the  value  is  changed  but  any  existing
	   methods are not changed.

	   The function-name specifiesa generic function that has  different
	   :method-class value,  the  value  is  changed  but  any  existing
	   methods are not changed.

	   The function-name argument  is a  symbol or  a list  of the  form
	   (setf symbol).

	   The keyword  arguments  correspond  to the  option  arguments  of
	   defgeneric, except that  the :method-class and  :generic-function
	   arguments can be class objects as well as names.

	   The  :environment  argument  is  the  same  as  the  &environment
	   argument to macro  expansion functions. It  is typically used  to
	   distinguish between compile-time and run-time environments.

	   The :method-combination argument is a method combination object.

	   The generic function object is returned. See defgeneric.



find-class                                                    [function]
	   symbol
	   &optional errorp environment

	   The function find-class object named  by the given symbol in  the
	   given environment.

	   The first argument to find-class is a symbol.

	   If there is no such class and the errorp argument is not supplied
	   or is non-nil, find-class signals an  error. If there is no  such
	   class and the errorp is nil, find-class returns nil. The  default
	   value of errorp is t.

	   The optional environment argument is the same as the &environment
	   argument to macro  expansion functions. It  is typically used  to
	   distinguish between compile-tome and run-time environments.

	   The result of find-class is the  class is the class object  named
	   by the given symbol.

	   The class associated with a  particular symbol can be changed  by
	   using setf with find-class. The results are undefind if the  user
	   attempts to change  the class  associated with a  symbol that  is
	   defined as a type specifier in CLtL2, chapter 4.



find-method                                           [generic function]
	   generic-function
	   method-qualifiers
	   specializers
	   &optional errorp

find-method
	   (generic-function standard-generic-function)
	   method-qualifiers
	   specializers
	   &optional errorp

	   The generic  function find-method  takes a  generic function  and
	   returns the method  object that agrees  on method qualifiers  and
	   parameter   specializers   with   the   method   qualifiers   and
	   specializers arguments of find method.

	   The generic-function argument is a generic function.

	   The method-qualifiers argument is a list of the method qualifiers
	   for the method.

	   The order of the method qualifiers is significant.

	   The  specializers   argument  is   a  list   of  the   parameters
	   specializers for the method. It must correspond in length to  the
	   number of required arguments of the generic function, or an error
	   is signaled. This means  that to obtain  the default method  on a
	   given generic function, a list whose elements are the class named
	   t must be given.

	   If there  is  no such  method  and  the errorp  argument  is  not
	   supplied or is non-nil, find method signals an error. If there is
	   no such  method  and  the errorp  argument  is  nil,  find-method
	   returns nil. The default value of errorp is t.

	   The result of  find-method is  the method object  with the  given
	   method qualifiers and parameter specializers.



function-keywords method                              [generic function]
function-keywords (method standard-method)              [primary method]

	   The generic  function function-keywords  is  used to  return  the
	   keyword parameter specifiers for a given method.

	   The method argument is a method object.

	   The generic function-keywords returns two  values: a list of  the
	   explicitly named  keywords  and  a boolean  that  states  whether
	   &allow-otherkeys had been specified in the method definition.



generic-flet                                              [special form]
	   ( {(function-name lambda-list
				  [[ |option|{method-description}*]]}*)
			 {form}*

	   The generic-flet special forms is  analogous to the flet  special
	   form. It  produces  new  generic functions  and  establishes  new
	   lexical function bindings.

	   Each  generic  function  is  created  with  the  set  of  methods
	   specified by its method descriptions.

	   The special form generic-flet is used to define generic functions
	   whose names are meaningful only  locally and to exectue a  series
	   of forms with these function  definition bindings. Any number  of
	   such local  generic-flet have  lexical scope;  they retain  their
	   local definitions only within the  body of the generic flet.  Any
	   references within  the  body  of the  generic-flet  to  functions
	   whose-names are the same as those defined within the generic flet
	   are thus  refernces to  the  local functions  instead of  to  sny
	   global functions of the  sam enames. The  scope of these  generic
	   functiondefinition bindings, however, includes  only the body  of
	   the generic-flet,  not  the definitions  themselves.  Within  the
	   method bodies,  local  function  names  that  match  those  being
	   defined recursive functions with generic-flet.

	   The function-name,  lambda-list,  option,  method-qualifier,  and
	   specialized-lambda-list arguments are the same as for defgeneric.

	   A generic-flet local  method definition is  identical in from  to
	   the method definition part of a defmethod.

	   The body of  each 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.

	   The result  retuned  by  generic-flet  is  the  value  or  values
	   returned by the last  form executed. If  no forms are  specified,
	   generic-flet returns nil.



generic-function lambda-list                                     [macro]
		[[ |option | {method-description}*]]

	   option::=(:argument-precedence-order {parameter-name}+)
			   |(declare {declaration}+)
			   |(:documentation string)
			   |(:method combination symbol {arg}*)
			   |(:generic-function class class name)
			   |(:method-class class-name)
	   method-description::=(:method {method qualifier}*
									   specialized-lambda-list
									   {declaration |documentation}*
									   {form}*)

	   The generic-function macro creates an anonymous generic function.
	   The generic function is created with the set of methods specified
	   by its method descriptions.

	   The  option,   method  qualifier,   and   specialized-lambda-list
	   arguments are the same as for defgeneric.

	   The generic function object is returned as the result.

	   If no  method descriptions  are specified,  an anonymous  generic
	   function with no methods is created.



generic-label                                             [special form]
	   ({(function-name lambda-list
				   [[|option |{method-description}*]])}*)
			   {form}*

	   The generic-labels  special  form  is  analogous  to  the  labels
	   special form. It produces  new generic functions and  establishes
	   new lexical function definition  bindings. Each generic  function
	   is created  with  the set  of  methods specified  by  its  method
	   descriptions.

	   The  special  form  generic-labels  is  used  to  define  generic
	   functions whose names are meaningful only locally and to  execute
	   a series of forms  with the body of  the generic-labels form  are
	   thus references to the local  functions instead of to any  global
	   functions of the same names. The scope of these generic functions
	   definitions bindings  includes the  method bodies  themselves  as
	   well as the body of the generic labels construct.

	   The generic-labels local method  definition is identical in  form
	   to the method definition part of a defmethod.

	   The body of  each 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 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.

	   The result  returned by  generic-labels is  the value  or  values
	   returned by the last  form executed. If  no forms are  specified,
	   generic-labels returns nil.


initialize-instance instance &rest-initargs           [generic function]
initialize-instance                                     [primary method]
	   (instance standard-object)
	   &rest initargs

	   The   generic   function   initialize-instance   is   called   by
	   make-instance to initilaise a newly created instance. The generic
	   function initilise-instance is called  with the new instance  and
	   the defaulted initialization arguments.

	   The  system-supplied   primary  method   on   initialize-instance
	   initializes the slots of the instance wth values according to the
	   initialization arguments and the :initform forms of the slots. It
	   does this by calling the generic functoin shared-initialize  with
	   the following  arguements  are  provided  should  be  initialized
	   according  to  their  :initform  forms)  and  the  object  to  be
	   initialized.

	   The initargs  argument  consists  of  alternating  initialization
	   arguments names and values.

	   The modified instance is returned as the result.

	   Programmers can define methods for initialize-instance to specify
	   actions to  be taken  when an  instance is  initialized. If  only
	   :after methods for intialization and therefore will not interfere
	   with the default behaviuor of initialize-instance.



invalid-method-error                                          [function]
	   method
	   format-string
	   &rest args

	   The function invalid-method-error is used to signal an error when
	   there is an applicable method whose qualifiers are not valid  for
	   the method combination type.

	   The error message is constructed by using a format string and any
	   arguments to  it.  Because  an implementation  may  need  to  add
	   additional  contextual   information   to  the   error   message,
	   invlid-method-error should  be  called only  within  the  dynamic
	   extent of a method combination function.

	   The function invalid-method-error is called automatically  when a
	   method fails to satisfy every qualifier pattern and predicate  in
	   a define-method combination form.  A method combination  function
	   that    imposes    additional     restrictions    should     call
	   invalid-method-error explicitly  if  it encounters  a  method  it
	   cannot accept.

	   The method argument is the invalid method object.

	   The format-string argument is a control string that can be  given
	   to format, and args are any arguments required by that string.

	   Whether invalid-method-error returns to  its caller or exits  via
	   throw is implementation-dependant.



make-instances-obsolete class                         [generic function]
make-instances-obsolete (class standard-class)          [primary method]
make-instances-obsolete (class symbol)                  [primary method]

	   The   generic   function   make-instances-obsolete   is   invoked
	   automatically by  the  system  when defclass  has  been  used  to
	   redefine an existing standard  class and the  set of local  slots
	   accessible in an instance is  changed. It can also be  explicitly
	   invoked by the user.

	   The function make-instances-obsolete has the effect of initiating
	   the progress  of  updating the  instances  of the  class.  During
	   updating,            the             generic             function
	   update-instance-for-redefined-class will be invoked.

	   The class argument is a class object symbol that names the  class
	   whose instances are to be made obsolete.

	   If the second of the proceeding methods is selected, that  method
	   invokes make-instances-obsolete on (find-class class).

	   The  modified   class   is   returned.   The   result   of   make
	   instances-obsolete is eq  to the class  argument supplied to  the
	   preceeding methods.



method-combination-error format-string &rest args             [function]

	   The function method-combination-error is used to signal an  error
	   in method combinaion. The error message is constructed by using a
	   format string and any arguments to it. Because an  implementation
	   may need to  add additional contextual  information to the  error
	   message, method-combination-error  should be  called only  within
	   the dynamic extent of a mthod combination function.

	   The format-string argument is a control string that can be  given
	   to format, and args are any arguments rewuired by that string.

	   Whether method-combination-error returns to  its caller or  exits
	   via throw is implementation-dependant.



method-qualifiers method                              [generic function]
method-qualifiers (method standard-method)              [primary method]

	   The generic  function method-qualifiers  returns  a list  of  the
	   qualifiers of the given method.

	   The method argument is a method object.

	   A list of the qualifiers of the given method is returned.

Example:

(setq methods (remove-duplicates methods
								 :from-end t
								 :key #'method-qualifiers
								 :test #'equal))

	   See defined-method-combination.



next-method-p                                                 [function]

	   The locally defined function next-method-p can be used within the
	   body of a method defined  by a method-defining form to  determine
	   whether a next method exists.

	   The function next-method-p takes no arguments.

	   The function next method-p returns true or false.

	   Like call-next-method,  the  function next-method-p  has  lexical
	   scope (for it is defined only within the body of a method defined
	   by a method defining form) and indefinite extent.

	   See call-next-method.



no-applicable-method generic-function                 [generic function]
	   &rest function-arguments

no-applicable-method (generic function t)               [primary method]
	   &rest function-arguments

	   The  generic  function  no-applicable-method  is  called   when a
	   generic  function  of   the  class-standard-generic-function   is
	   invoked and on method on that generic function is applicable. The
	   default method signals an error.

	   The generic function no-applicable-method  is not intended to  be
	   called by programmers. Programmers may write methods for it.

	   The generic-function  argument  of non-applicable-method  is  the
	   generic function object on which no applicable method was found.

	   The function-arguments arguements is a  list of the arguments  to
	   that generic function.



no-next-method generic-method &rest args              [generic function]
no-next method                                          [primary method]
	   (generic-function standard-generic-function)
	   (method standard-method) &rest args

	   The generic function no-next-method is called by call-next-method
	   when there  is  no  next-method. The  system-supplied  method  on
	   no-next-method signals an error.

	   The generic function no-next-method is not intended to be  called
	   by Programmers. Programmers may write methods for it.

	   The generic-function argument is  the generic function object  to
	   which the method that is the second argument belongs.

	   The method  argument is  the method  that contain  the  call-next
	   method for which there is no next method.

	   The args argument is a list of the arguments to call-next-method.

	   See call-next-method.



print-object object stream                              [generic method]
print-object (object standard-object) stream)           [primary method]

	   The   generic   function   print-objetc   writes   the    printed
	   representation  of   an  object   to  a   stream.  The   function
	   print-object is  called by  the print  system; it  should not  be
	   called by the user.

	   Each  implementation  must   provide  a  method   on  the   class
	   standard-object and  methods on  enough other  classes so  as  to
	   ensure that there is always an applicable method. Implementations
	   are free  to  add methods  for  other classes.  Users  can  write
	   methods for print-object  for their  own classes if  they do  not
	   wish to inherit an implemetation-supplied method.

	   The first argument is any  Lisp object. The second argument  is a
	   stream; it cannot be t or nil.

	   The function print-object returns its first argument, the object.

	   Methods  on  print-object  must  obey  theprint  control  special
	   variables named *print-xxx* for various xxx. THe specific details
	   are the following:

	   - each method must  implement *print-escape*. The  *print-pretty*
	   control variable can be  ignored by most  methods other than  one
	   for lists.

	   - the *print-circle* control variable  is handled by the  printer
	   and can be ignored by methods.

	   The printer takes care  of *print-level* automatically,  provided
	   that each method handles exactly one level of structure and calls
	   wtire (or an equivalent function)  recursively if there are  more
	   structural levels. The  printer's decision of  whether an  object
	   has componants  (and therefore  should not  be printed  when  the
	   printing   depth   is   not    less   than   *print-level*)    is
	   implementation-dependant.    In    some    implementations    its
	   *print-object method is not called; in others the method  called,
	   and the determination thast the  object has comoponants is  based
	   on what it tries to write to the stream.

	   Methods that  produce  output  of  indefinite  length  must  obey
	   *print-length*, but most  methods other than  the one can  ignore
	   it.

	   The *print-base*,  *print-radix*,  *print-case*,  *print-gensys*,
	   and *print-array*  control varables  apply to  specific types  of
	   objects and are handled by the methods for those objects.

	   If those rules are not obeyed, the results are undefined.

	   In general, the printer and  the print-object methods should  not
	   rebind the print  control variables as  they operate  recursively
	   through the structure, but this is implementation-dependant.

	   In  some   implemenations  the   stream  argument   passed   to a
	   print-object  method  is  not  the  original  stream  but  is  an
	   intermidiate stream that implements part of the printer.  Methods
	   should therefore not depend on the identity of this stream.

	   All of  the existing  printing functions  (write, printl,  print,
	   princ,   pprint,   write   to    string,   printl   to    string,
	   princ-to-string, the ~S and ~A format operations, and the ~B, ~D,
	   ~E, ~F,  ~G, ~$,  ~O,  ~R, and  ~X  foermt operations  when  they
	   encountera non-numeric value)  are required to  be changed to  go
	   through the print-object generic function. Each implementation is
	   required to replace  its former implementation  of printing  with
	   one or  more  print-object  methods. Exactly  which  causes  have
	   methods for print-object is not specified; it would be valid  for
	   an implementation to have one default method that is inherited by
	   all system-defined clases.



reinitialize-instance                                 [generic function]
	   instance
	   &rest initargs

reinitialize-instance                                   [primary method]
	   (instance standard-object)
	   &rest initargs

	   The generic function reinitialize-instance can be used to  change
	   the values of  local slots according  to initialiation  argments.
	   This generic function is called  by the Meta-Object Protocol.  It
	   can also be called by users.

	   The  system-supplied  primary  method  for  reinitialize-instance
	   checks the validity  of initialization arguments  and signals  an
	   error if  an  initialiation  argument  is  supplid  that  is  not
	   declared valid.  The  method  then  calls  the  generic  function
	   shared-initialize with the following arguments; the instance, nil
	   (which means no  slots should be  initialized according to  their
	   :initform forms) and the initialization arguments it received.

	   The instance argment is the object to be initialized.

	   The instance  argument  consists  of  alternating  initialization
	   argument names and values.

	   The modified instance is returned as the result.

	   Initialization arguments are declared valid by using the :initarg
	   option   to    defclass,    or   by    defining    methods    for
	   reinitialize-instance or shared-initialize.  The keyword name  of
	   each keyword parameter specifier in the lambda-list of any method
	   defined on reinitialize-instance or shared-initialize is declared
	   a valid initialization name for all classes for which that method
	   is applicable.



remove-method generic-function method                   [generic method]
remove-method                                         [primary function]
	   (generic-function standard-generic-function) method

	   The  generic  function  remove-method  removes  a  method  from a
	   generic function. It destructively modifies the specified generic
	   fucntion and returns the modified generic function as its result.

	   The generic-function argument is a generic function object.

	   The  method   argument  is   a   method  object.   The   function
	   remove-method does not signal an error  i fthe method is not  one
	   of the methods on the generic function.

	   The  modified  generic  function  is  returned.  The  result   of
	   remove-method is eq to the generic-function argument.

	   See find-method.



shared-initialize instance slot numbers               [generic function]
				  &rest initargs
shared-initialize (instance standard-object)          [primary function]
				  slot-names
				  &rest initargs

	   The generic function shared-initialize is used to fill the  slots
	   of an  instance  using  initialization  arguments  and  :initform
	   forms. It is called when an instance is created, when an instance
	   is re-initialized, when  an instance is  updated to conform  to a
	   redefined class, and when an instance is updated to conform  to a
	   different class. The generic function shared-initialie is  called
	   by     instance,     update-instance-for-redefined-class,     and
	   update-instance-for-different-class.

	   The  generic  function  shared-initialize  takes  the   following
	   arguments; the instance to  be initialized, a specification  of a
	   set of names  of slots accessible  in that instance,  and of  any
	   number of  initialization  argument  list.  The  system  supplied
	   primary method on  shared-initialize initializes  the slots  with
	   values according to the initialization arguments are provided for
	   those slots.

	   The system-slots primary method behaves as follows, regardless of
	   whether the slots are local or shared:

	   If an initialization argument in the inilialization argument list
	   specifies a value for  that slot, that value  is stored into  the
	   slot, even if a value has already been stored in the slot  before
	   the method is run.

	   Any slots indicated by the second argment that are still  unbound
	   at this point are initialized according to their :initform forms.
	   For any  such slot  that  has an  :initform  form, that  form  is
	   evaluated in  the lexical  environment of  its defining  defclass
	   form and the result  is stored into the  slot. For example,  if a
	   :before method store a value in the slot.

	   - The rules mentioned in section 28.1.9.4 are obeyed.

	   - The  instance argument  is the  object to  be initialized.  The
	   slot-names  arguments  specifies  the   slots  that  are  to   be
	   initialized  according   to   their   :initform   forms   if   no
	   initialization arguments apply.  It is supplied  in one of  these
	   three forms below

	It can be  list of  slots names, which  specifies the  empty set  of
	slots names.

	It can be nil, which specifies the empty set of slot names.

	It can be the symbol t, which specifies the set of all the slots.

	   The initargs argument consists of alternating argument names  and
	   values.  The  modified  instance  is  returned  as  the   result.
	   Initialization  arguments  are  declared   valid  by  using   the
	   :initargs  option  to  defclass,  or  by  defining  methods   for
	   shared-initialize. The  keyword name  of each  keyword  parameter
	   specifier  in   the  lambda-list   of  any   method  defined   on
	   shared-initialize is  declared  a valid  initialization  argument
	   name for all classes for which that method is applicable.

	   Implementations are  permitted  to optimize  forms  that  neither
	   produce nor depend on side effects by evaluating these forms  and
	   storing them into  slots before  running any  initialize-instance
	   methods,  rather   than  by   handling   them  in   the   primary
	   initialize-instance   method   (This   optimization   might    be
	   implemented  by  having   the  allocate-instance  method   copy a
	   prototype instance).

	   Implementation are permitted  to optimize  default initial  value
	   forms for initialization arguments  associated with slots by  not
	   actually creating the complete inilialization arguments list when
	   the only  method that  would  receive the  complete list  is  the
	   method on standard-object.  In this case,  default initial  value
	   forms can be treated like  :initfor forms. This optimization  has
	   no visible effects other than a performance improvement.

	   See  CLtL2,  sections  28.1.9   28.1.9.4  28.1.9.2  as  well   as
	   initialize-instance, reinitialize-instance,  update-instance  for
	   redefined-class,             update-instance-for-different-class,
	   slot-boundp, and slot-makeunbound.



slot-boundp instance slot-name                                [function]

	   The function  slot-boundp  test whether  a  specific slot  in  an
	   instance is bound.

	   The arguments are the instance and the name of the slot.

	   The function slot-boundp returns true or false.

	   This   function   allows   for   writing   :after   methods    on
	   initialize-instance in order to initialize only those slots  that
	   have not alreay been bound.

	   If no slot of the given name exists in the instance, slot-missing
	   is called as follows:

	   (slot-missing (class-of instance)
			  instance
			  slot-name
			  'slot-boundp)

	   The     function     slot-boundp     is     implemented     using
	   slot-boundp-using-class. See slot-missing.



slot-exists-p object slot-name                                [function]

	   The function slot-exists-p tests whether the specified object has
	   a slot of the given name.

	   The object argument  is any object.  The slot-name argument  is a
	   symbol.

	   The function slot-exists-p returns true or false.

	   The    function     slot-exists-p    is     implemented     using
	   slot-exists-p-using-class.



slot-makeunbound instance slot-name                           [function]

	   The function slot-unbound restores a  slot in an instance to  the
	   unbound state.

	   The argument to slot-makunbound are the instance and the name  of
	   the slot.

	   The instance is returned as the result.

	   If no slot of the given name exists in the instance, slot-missing
	   is called as follows:

	   (slot-missing (class-of instance)
			  instance
			  slot-name
			  'slot-makunbound)

	   The function slot makunbound is implemented using slot makunbound
	   using-class. See slot-missing.



slot-missing class object slot-name operation         [generic function]
			 &optional new-valu
slot-missing (class t) object slot-name operation       [primary method]
			 &optional new-value

	   The generic function slot-missing is  invoked when an attempt  is
	   made  to  access  a  slot   in  an  object  whose  metaclass   is
	   standard-class and the name of the slot provided is not a name of
	   a slot is that class. The default method signals an error.

	   The generic function slot-missing is not intended to be called by
	   programmers.

	   Programmers may write methods for it.

	   The required  arguments  to slot-missing  are  the class  of  the
	   object that  being accessed,  the object,  the slot  name,  and a
	   symbol that indicates the  operation that caused slot-missing  to
	   be invoked. The  optional argument to  slot-missing is used  when
	   the operation is attempting to set the value of the slot.

	   If a method written for slot-missing returns values, these values
	   get returned as the values of the original function invocation.

	   The generic function slot-missing may be called during evaluation
	   of    slot-value,    (setf    slot-value),    slot-boundp,    and
	   slot-makunbound. For each of  these operations the  corresponding
	   symbol  for   the  operation   argument  is   slot-value,   setf,
	   slot-boundp, and slot-makunbound, respecitively.

	   The set  of  arguments  (including the  class  of  the  instance)
	   facilities defining methods on the metaclass for slot-missing.



slot-unbound class instance slot-name                 [generic function]
slot-unbound (class t) instance slot-name               [primary method]

	   The generic function slot-unbound is called when an unbound  slot
	   is read in  an instance  whose metaclass  is standard-class.  The
	   default method signals an error.

	   The generic function  slot-unbound is not  intended to be  called
	   programmers. Programmers may write  mwthods for it. The  function
	   slot-unbound    is     called     only    by     the     function
	   lsot-value-using-class and thus indirectly by slot-value.

	   The arguments to slot-unbound are the class of the instance whose
	   slot was accessed, the instance itself, and the name of the slot.

	   If a  method written  for a  slot-unbound returns  values,  these
	   values get  returned  as  the values  of  the  original  function
	   invocation.

	   An unbound slot may occur if no :initform form was specified  for
	   mthe  slot  and  the  lsot  value   has  not  been  set,  or   if
	   slot-makunbound has been called on the slot.

	   See slot-makunbound.



slot-value object slot-name                                   [function]

	   The function slot-value returns the  value contained in the  slot
	   slot-name ofthe given object. If there is no slot with that name,
	   slot-missing is called. If the  slot is unbound, slot-unbound  is
	   called.

	   The macro setf can be used with slot-value to change the value of
	   a slot.

	   The arguments are the object and the name of the given slot.

	   The result is the value contained in the given slot.

	   If an attempt is  made to read  a slot and no  slot of the  given
	   name exists in the instance, slot-missing is called as follows:

	   (slot-missing (class-of instance)
			   instance
			   slot-name
			   'slot-value)

	   If an attempt is made  to wirte a slot and  no slot of the  given
	   name exists in the instance, slot-missing is called as follows:

	   (slot-missing (class-of instance)
			  instance
			 slot-name
			 'setf
			 new-value)

	   The     function     slot-value     is     implemented      using
	   slot-value-using-class. Implementations  may optimize  slot-value
	   by compiling it in-line. See slot-missing and slot-unbound.



update-instance-for-different-class                   [generic function]
	   previous
	   current
	   &rest initargs

update-instance-for-different-class                     [primary method]
	   (previous standard-object)
	   (current standard-object)
	   &rest initargs

	   The  generic  function  update-instance-different-class  is   not
	   intended to  be  called  by programmers.  Programmers  may  write
	   methods for  it. This  function is  called only  by the  function
	   change-class.

	   The  system-supplied  primary   method  on  update-instance   for
	   different-class checks the  validity of initialization  arguments
	   and signals an  error if an  initialization argument is  supplied
	   that is not  declared valid. This  method then initializes  slots
	   with  values  according  to  the  initialization  arguments   and
	   intializes the newly added slots  with values according to  their
	   :initform form.  It does  this by  calling the  generic  function
	   shared initialize with the  following arguments; the  instance, a
	   list of names of  the newly added  slots, and the  initialization
	   arguments it received.  Newly added slots  are those local  slots
	   for which no slot of the same name exists in the previous class.

	   Methods for update-instance-for-different-class can be defined to
	   specify actions to be taken when an instance is updated. If  only
	   :after  methods   for   update-instance-for-different-class   are
	   defined,    they    will    be    run    :after    methods    for
	   update-instance-for-different-class are defined, they will be run
	   after the system-supplie  primary method  for initialization  and
	   therefore will  not  interfere  with  the  default  behaviour  of
	   update-instance-for-different-class.

	   The arguments to update-instance-for-different-class are computed
	   by change-class. When change-class  is invoked on an  instance, a
	   copy of that  instance is made;  change-class then  destructively
	   alters   the   original   instance.   The   first   argument   to
	   update-instance-for-different-class, previous, is  that copy;  it
	   holds the old slot values temporarily. This argument has  dynamic
	   extent within change-class; if it  is referenced in any way  once
	   update-instance-for-different-class  returns,  the  results   are
	   undefined.         The         second         argument         to
	   update-instance-for-different-class,  current,  is  the   altered
	   original instance.

	   The intended use  of previous is  to extract old  slot values  by
	   using slot-value or by invoking a reader generic function, or  to
	   run other  methods  that  were applicable  to  instances  of  the
	   original class.

	   The  initargs  argumen  consists  of  alternating  initialization
	   argument names and values.

	   The  value  returned  by  update-instance-for-different-class  is
	   ignored by change-class.

	   See the example for the function change-class.

	   Initialization arguments are declared valid by using the :initarg
	   option   to    defclass,    or   by    defining    methods    for
	   update-instance-for-different-class  or  shared-initialize.   The
	   keyword  name  of  each   keyword  parameter  specifier  i   nthe
	   lambda-list      of       any       method       defined       on
	   update-instance-for-different-class   or   shared-initilize    is
	   declared a vlid initialization argument name for all classes  for
	   which method is applicable.

	   Methods on update-instance-for-different-class can be defined  to
	   initialise  slots  differently  form  change-class.  The  default
	   behaviour of change-class is described in CLtL2, section 28.1.11.



update-instance-for-redefined-class                   [generic function]
	   instance
	   added-slots
	   discarded-slots
	   property-list
	   &rest initargs

update-instance-for-redefined-class                     [primary method]
	   (instance standard-object)
	   added-slots
	   discarded-slots
	   property-list
	   &rest initargs

	   The generic function  update-instance-for-redefined-class is  not
	   intended to  be  called  by programmers.  Programmers  may  write
	   methods      for       it.       The       generic       function
	   update-instance-for-redefined-class  is   called   by   mechanism
	   activated by make-instances-obsolete.

	   The        system-supplied        primary        method        on
	   update-instance-for-different-class  checks   the   validity   of
	   initialization   arguments   and   signals   an   error   if   an
	   initialization argument is supplied  that is not declared  valid.
	   This method then  initializes the newly  added slots with  values
	   according to their :initform forms.  It does this by calling  the
	   generic function shared-initialize with the following  arguments;
	   the instance,  a list  of names  of the  newly added  slots,  the
	   initialization arguments it received. Newly added slots are those
	   local slots for which no slot of the same name exists in the  old
	   versio of the class.

	   When make-instances-obsolete is invoked or when a class has  been
	   redefined and an instance  is being updated,  a property list  is
	   created that  captures  the slot  names  and values  of  all  the
	   discard slots with values i the original instance. The  structure
	   of the instance  is transformed so  that it can  conforms to  the
	   current     class      definition.     The      arguments      to
	   update--instance-for-redefined-class   are    this    transformed
	   instance, a  list of  the names  of the  new slots  added to  the
	   instance, a list of  the names of the  old slot names and  values
	   for slots that were local in the old class and are shared in  the
	   new class.

	   The initargs  argument  consists  of  alternating  initialization
	   arguments names and values.

	   The  value  returned  by  update-instance-for-redefined-class  is
	   ignored.

	   Initialization arguments are declared valid by using the :initarg
	   option   to    defclass    or    by    defining    methods    for
	   update-instance-for-redefined-class  or  shared  initialize.  The
	   keyword  name  of  each   keyword  parameter  specifier  in   the
	   lambda-list    of     any     method    defined     on     update
	   instance-for-redefined-class or  shared-initialize is  declared a
	   valid initialization argument name for all classes for which that
	   method is applicable.

	   See CLtL2,  sections 28.1.10  28.1.9.4 and  28.1.9.2 as  well  as
	   shared initialize and make-instances-obsolete.

(defclass position () ())

(defclass x-y-position (position)
  ((x :initform 0 :accessor position x)
   (y :initform 0 :accessor position-y)))

;;; It turns out polar coordinates are used more than Cartesian
;;; coordinates, so the representation is altered and some new
;;; accessor methods are added

(defmethod update-instance-for-redefined-class :before
		   ((pos x-y-position) added deleted plist &key)
  ;; Iransform the x-y coordinates to polar coordinates
  ;; and store into the new slots.
  (let ((x (getf plist 'x))
		(y (getf plist 'y)))
	(setf (position-rho pos) (sqrt (+ (* x x) (* y y)))
		  (position-theta pos) (atan y x))))

;;; All instances of the old x-y-position class will be updated
;;; automatically

;;; The new representation is given the look and feel of the old one.

(defmethod position-x ((pos x-y-position))
   (with-slots (rho theta) pos (* rho (cos theta))))

(defmethod (setf position-x) (new-x (pos x-y-position))
   (with-slots (rho-theta) pos
	  (let ((y (position-y pos)))
		(setq rho (sqt (+ (* new-x new-x) (* y y)))
			  theta (atan y new-x))
		new-x)))

(defmethod position y ((pos x-y position))
   (with slots (rho theta) pos (* rho (sin theta))))

(defmethod (setf position-y) (new-y (pos x-y-position))
   (with-slots (rho-theta) pos
	 (let ((x (position-x pos)))
	   (setq rho (sqrt (+ (* xx) (* new-y new-y)))
			 theta (atan new-y x))
	   new-y)))



with-accessors ({slot-entry}*) instance-form                     [macro]
			   {declaration}* {form}*

	   The macro with-accessorss creates a lexical environment in  which
	   specified slots are lexically  available through their  accessors
	   as if they were variables.  The macro with-accessors invokes  the
	   appropriate accessors to access the specified slots.

	   Both setf and setq can be used to set the value of the slot.

	   The result  returned  is that  obtained  by executing  the  forms
	   specified by the body argument.

	   Example:

	   (with-accessors ((x position-x) (y position-y)) p1 (setq x y))

	   A with-accessors expression of the form

	   (with-accessors     (slot-entry1     ...slot-entryn)     instance
	   declaration1 ... declaration1 ...declarationm) form1 ...formk)

	   expands into the equivalent of

	   (let   ((in    instance))    (symbol-macrolet    ((variable-name1
	   (accessor-name1 in))
				   ...
					(variable-namen (accessor-namen  in)))  declaration1
	   ...declarationm) form1 ... formk)

	   See with-slots and symbol-macrolet.



with-added-methods (function-name lambda-list             [special form]
					[[|option | {method-description}*]])
				   {form}*

	   The  with-added-methods   special  form   produces  new   generic
	   functions  and   establishes   new-lexical   function   defintion
	   bindings. Each generic function is  created by adding the set  of
	   methods specified  by its  methd  definitions to  a copy  of  the
	   lexically visible  generic  function of  the  same name  and  its
	   methods. If such a generic function does not already exist, a new
	   generic  function   is  created;   this  generic   function   has
	   lexical-scope.

	   The special  form with-added-methods  is sed  to define  function
	   whose names are meaningful only  locally and to execute a  series
	   of forms with these function definition bindings.

	   The names of functions defined by with-added-methods have lexical
	   scope; they retain their local  definitions only within the  body
	   of the  with-added-methods construct.  Any refernces  within  the
	   body of the with-added-methods  construct. Any references  within
	   the body of the  with-added-methods construct to functions  whose
	   names are the same as those defined within the with-added-methods
	   form are thus references to the local functions instead of to any
	   global bindings includes the method bodies themselves as well  as
	   the body of the with-added-methods contruct.

	   The     function-name,     option,     method-qualifier,      and
	   specialized-lambda-list arguments are the same as for defgeneric.

	   The body of  each 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 a symbol.

	   The result returned by with-added-methods is the value or  values
	   of  the  last   form  executed.  If   no  forms  aer   specified,
	   with-added-methods returns nil.

	   If a generic  function with  the given name  already exists,  the
	   lambda-lists of all existing methods on that function as well  as
	   with  the   lambda-lists   of   all  methods   defined   by   the
	   with-added-methods form; otherwise an error is signaled.

	   If function-name specifies an existing generic function that  has
	   different value for  any of the  following option arguments,  the
	   copy of the generic  function is modified to  have the new  value
	   :argument-precedence-order,       declare,        :documentation,
	   :generic-function-class, :method-combination.

	   If function-name specifies an existing generic function that  has
	   different value for the :method class option argument, that value
	   is changed in the  copy of th generic  function, but any  methods
	   copied from the existing generic function are not changed.

	   If a function of the given name already exists, that function  is
	   copied into  the default  method for  a generic  function of  the
	   given name.  Note  that  this  behaviour  differs  from  that  of
	   defgeneric.

	   If a macro or special form  of the given name already exists,  an
	   error is signaled.

	   If there is  no existing generic  function, the option  arguments
	   have  the  same  default  values  as  the  option  arguments   to
	   defgeneric.

	   See  generic-labels,  generic-flet,  defmethod,  defgeneric,  and
	   ensure-generic-function.



with-slots ({slot-entry*) instance-form {declaration}* {form}*   [macro]

slot-entry::=slot-name |(Variable-name slot-name)

	   The macro with-slots creates a  lexical context for referring  to
	   specified slots  as  though  they  were  varable.  Within  such a
	   context the value of the slot can be specified by using its slots
	   name, as if  it were a  lexically bound variable.  Both setf  and
	   setq can be used to set value of the slot.

	   The macro with-slots translates an appearance of the slot name as
	   a variable into a call to slot-value.

	   The result  returned  is that  obtained  by executing  the  forms
	   specified by the body argument.

Example:

(with-slots (x y) position-1
   (sqrt (+ (* x x) (* y y))))

(with-slots ((x1 x) (y1 y)) position-1
  (with-slots ((x2 x) (y2 y)) posisiotn-2
	(psetf x1 x2
		   y1 y2))))

(with-slots (x y) position
  (setq x (1+ x)
		y (1+ y)))

	   A with-slots expression of the form:

	   (with-slots (slot-entry1  ...slot-entryn)  instance  declaration1
	   ... declarationm) form1 ...formk)

	   expands into the equivalent of

	   (let ((in instance)) (symbol-macroletn (Q1 ... Q2n)  declaration1
	   ... declarationm) form1 ...formk)

	   where Q1 is

	   (slot entry1 (slot-value in 'slot-entry1))

	   it slot-entry1 is a symbol and is

	   (variable-name1 (slot-value in 'slot-name1))

	   if slot-entryj is of the form (variable-namej slot-namej).

--- Copyright University of Sussex 1990. All rights reserved. ----------
