4   -*- Mode:Text; Package:User; Fonts:(TR12 CPTFONTB TR12I CPTFONT HL10 CPTFONTB* 4HL12B) -*-
  *					4   A         B         C        D         E        F          G*
  3------------------------------------------------------------------------------*


                6CLOS Release Notes*			original version 1/18/89
                                                        latest revision  5/8/89

     Copyright (C) 1989, Texas Instruments Incorporated.  All rights reserved.


6Introduction*

  This document describes the alpha test version of the Common Lisp Object System
  implementation for the TI Explorer and microExplorer, as of version 14.41.


6Installation*

  The files on the distribution tape are contained in two directories: 3"LM:CLOS;*.*#>"* and
  3"LM:UBIN;*.*#>"*.

  You can create these directories on your system host for the CLOS system files and the
  microcode files or allow the tape backup system to create them for you.   (Actually,
  these can be installed on some host other than 3SYS* so long as the proper host name is
  substituted in the 3sys:set-system-source-file* and 3sys:load-mcr-file* forms below.)
        
  Using the Explorer tape backup system <3SYSTEM* 3B*> prepare your tape, restore each
  directory on the tape, rewind the tape, and verify the directory contents before exiting
  the tape backup system.

  Create a file named "3sys:site;clos.system"* containing the following form:

3        (sys:set-system-source-file "CLOS" "sys:clos;defsystem")*

  Load the appropriate microcode file (Explorer I, Explorer II or microExplorer) into your
  mcr partition using the form:

3        (sys:load-mcr-file 2filename partition unit*)


6Loading**

  Reboot using the new microcode and a load band for release 4 or later, load patches
  (because System patch 4.97 or 5.23 or Compiler patch 4.17 will break CLOS if it is
  loaded after CLOS, and Zmacs patch 4.34 conflicts with CLOS patch 14.4), and then
  load the CLOS system by:

        3(make-system :clos :noconfirm)*

  This creates a package named 3"CLOS"* which exports all of the symbols documented in
  the specifications.  These symbols are also made visible from the 3"USER"* package.

  There is a brief tutorial introduction to CLOS in the file 3"sys:clos;intro.text"* and a
  reference card in file 3"sys:clos;reference.text"*.


6Specifications*

  The TI implementation of CLOS is intended to conform to the specifications in
  chapters 1 and 2 of ANSI committee X3J13 document 88-002R (June 1988), with a few
  exceptions as noted in the sections ``specification updates'', ``exceptions to the
  specification'', and ``known problems'' below.

  The meta object protocol defined in chapter 3 of the specification is only partially
  supported at this time.


6Specification updates*

  This section lists changes to the specification that have been adopted by the ANSI
  Common Lisp committee since the June 1988 edition of the CLOS specification.

  The forms 5symbol-macrolet*, 5with-slots*,5 *and 5with-accessors* will accept
  declarations at the beginning of the body.  In particular, type declarations may be
  given for the variables being defined.  For example,
        3(with-slots (n) object (declare (integer n)) (foo n))*
  is equivalent to:  3(foo (the integer (slot-value object* 3'n)))* .

  When the compiler encounters an instance or structure that needs to be written to the
  object file as a constant, it calls the generic function 1make-load-form3 **to find out
  what to do.  1make-load-form* is called with the object as its argument; it is expected
  to return a form which is to be written to the file and evaluated by the loader to
  create the object.  In order to handle recursive data structures, two values may be
  returned, the first being a form to be evaluated to allocate the object and the second
  value being a form to be evaluated to finish initializing the object.  The first form
  should return the object created; the second form can refer to the object as one of its
  arguments; the value returned by the second form is not used.  Users can write
  methods for 1make-load-form* to enable writing instances of their classes.
  
  Function 5symbol-function1 **will continue to work only for1 *symbols; to reference the
  definition of a 3(setf* 2...3)** function, use function 5fdefinition*.

  Functions named 3(setf 2symbol*)* can be defined by 1defun*, 1flet *and 1labels* as well as
  by 1defgeneric*, 1generic-flet* and 1generic-labels.*

  The above changes are already supported on the Explorer.  Those that follow are not yet
  reflected in the Explorer implementation.

  5symbol-macrolet* has been changed from a macro to a special form.  When this
  change is made, the second example on page 2-81 will no longer be valid because
  1macroexpand *will expand1 *a symbol defined by 1symbol-macrolet.*

  Within the body of 1symbol-macrolet*, 1with-slots*, and 1with-accessors*, the variables 
  defined can be altered by 1psetq* and 1multiple-value-setq* besides 1setq* and 1setf*.

  Function 1compute-applicable-methods *will probably be made a generic function.

  The functions 1slot-boundp*, 1slot-exists-p*, and 1slot-makunbound* should not be
  generic functions.

  Instead of making 1describe* a generic function, 1describe* will call the generic
  function 1describe-object* with two arguments -- the object and the output stream.
  Users can then write methods for 1describe-object*.  Note that this parallels the
  relationship between 1print* and 1print-object*.


6Exceptions to the specification
1 **
  The functions 5fboundp* and 1fmakunbound *currently work only for1 *symbols; the
  functions 5ticl:fdefinedp* and 1ticl:fundefine* need to be1 *used for function
  specification lists.

  The following forms work when compiled but not when interpreted:
  5call-next-method*, 5generic-flet*, 5generic-labels*,5 generic-function*,
  and 5with-added-methods*.

  While all of the predefined classes listed on pages 1-16 and 1-17 of the specification
  are supported, with the correct class precedence shown, the type hierarchy has not
  been modified to conform to the disjointness requirement on page 1-17.  This means
  that CLOS method dispatch will work properly, but 1typep* and 1subtypep* differ from
  the class precedence in that types 3hash-table*, 3package*, 3random-state*, and 3readtable*
  are subtypes of 3array*, and instance of these types satisfy 1arrayp* and 1vectorp*.  Also,
  interpreted functions are still represented as lists and thus are not included in the
  class 1function* (unless they happen to be closures).

  Function 1no-next-method* is not used in version 14 of TI-CLOS; this is fixed in
  version 16.

  The use of class objects (rather than class names) as type specifiers in type
  declarations is not yet supported.


6Extensions*

  This section describes features of the TI implementation which are in addition to the
  standard CLOS.  Most of these are either to make CLOS interface well with the
  Explorer environment or to aid debugging.  These extensions should be considered
  experimental, with specifications subject to change.

  Additional predefined classes include: 3ticl:locative*, 3ticl:lexical-closure*,
  3compiled-function*, 3ticl:condition*, 3ticl:stack-group*,3 *and 3sys:process*.

  All flavors are also classes, with metaclass 5ticlos:flavor-class3.**  Flavor instances
  can be used as the first argument of functions 5slot-value*, 5slot-boundp*,
  5slot-exists-p*, and 5slot-makunbound*.  A flavor can be defined either by
  5defflavor* or by using 5defclass* with the option
3        (:metaclass ticlos:flavor-class)*
  This uses the CLOS syntax but is still subject to the same semantic limitations as
  5defflavor* (e.g.  class allocation is not allowed, initargs must be keywords whose
  3symbol-name* is the same as the slot name).

  The metaclass 5ticlos:hybrid-class* can be used to define a class which combines
  the attributes of Flavors and CLOS.  This permits inheritance from either flavors or
  standard classes or a mixture.  Instances will accept flavor messages as defined by the
  included flavors.  This can be useful for building on top of a system-defined flavor.
  For example, windows are flavors, but you can define a hybrid class that includes the
  needed window flavors but lets you do your higher-level programming using CLOS
  syntax and functions while still allowing the instances to handle the flavor messages
  used for low-level I/O.  It should be noted, though, that the implementation of
  1hybrid-class* is somewhat of a kludge, so it is not expected to be as reliable or as
  well defined as either 1standard-class* or 1flavor-class.*

  The predicate function 1ticl:instancep* returns true for both flavor instances and
  CLOS instances (but not structures).

  The macro 5undefmethod* is an easy way to un-do a method definition; the arguments
  are the same as for 5defmethod*.

  A call to 5slot-value* can be used as the argument to 5locf*.  The user can define 3locf*
  methods the same way as 3setf* methods.

  The 5declare* option of 5defgeneric* can include 5arglist* and 5value1s** declarations to
  specify the values to be displayed by 3CTRL-SHIFT-A*.

  For purposes of editing or debugging, CLOS methods are named by function specs of
  the form: 3(ticlos:method 2generic-function-name **[2 qualifier *]2 3(*class-name ...3))**.  The
  combined method that is directly invoked by the generic function can be referenced by
  the name:  3(ticlos:handler 2generic-function-name *(2class-name ...*))*.  For example, a
  method defined by  3(defmethod buzz :after ((x thing) y)* 2...3)**  could3 *be traced by
  saying  3(trace ((method buzz :after (thing t))))*, while the corresponding
  combined method could be traced by 3(trace ((ticlos:handler buzz (thing* 3t))))*.
  Note that 3handler* function specs never include qualifiers.  For 3eql* specializers, the
  function spec contains the actual value, not the form to be evaluated.  For example,
  3(defmethod* 3doi ((x (eql (+ 1 2)))) 2...*) *defines a method whose name is 
  3(method doi* 3((eql* 33)))*.

  By analogy to the flavor 1sys:property-list-mixin*, there is a class named
  1ticlos:property-mixin* which can be included to provide objects with a property
  list that can be accessed by the generic functions3 1ticlos:get-property**, 
  1(setf* 1ticlos:get-property)*, and 1ticlos:remove-property*.  These generic
  functions can also be used to access the property lists of symbols, pathnames, or
  instances of flavors that include 1sys:property-list-mixin*.

  The function 1copy* has been made a generic function so that you can write methods to
  define how you want your objects to be copied.  The default is to return a new
  instance with the contents of all slots 1eq* to those in the original.

  When an 3xld* file is being written (either by 3compile-file* or 3dump-forms-to-file*) and
  a CLOS instance, Flavor instance, or named structure needs to be written to the file,
  the generic function 1make-load-form3 **is called with the object as its argument.  For
  flavor instances, the default method sends a 3:fasd-form* message; for named structures,
  the default method dumps them like arrays.  For CLOS objects, the default is to signal
  an error.  You can either write your own methods for 1make-load-form* or include the
  mixin class 1ticlos:fasdump-mixin*, which provides a method for returning a
  general-purpose pair of reconstruction forms.  Currently, class objects are written by
  causing the loader to invoke 1find-class* on the class name, but this may be a mistake;
  future versions may require explicit user-supplied methods for these also.

  Functions 1make-instance *and 1allocate-instance *accept a 3sys:area* argument
  which specifies the memory area in which to allocate the instance.  For example:
      3(make-instance 'myclass 'sys:area sys:background-cons-area)


6Meta-Object Protocol**

  Following is an alphabetical list of a few chapter 3 functions which are currently
  available and might be useful.  Refer to ANSI committee X3J13 document 89-003 for
  the specifications of these.  (There are also a few obsolete functions from document
  88-003 which are currently implemented, but not listed here.) 3 *Note that this part of
  the CLOS specification has not yet been adopted by X3J13 and is very likely to change
  during the next few months.

  3(1allocate-instance** 2class *&rest 2initargs3)**  =>  2new-uninitialized-instance*
  3(1class-default-initargs2 class**)2  **=>  2list*
  3(1class-direct-default-initargs2 class**)2  **=>  2list*
  3(1class-direct-slots2 class**)2  **=>  2list*
  3(1class-direct-subclasses2 class**)2  **=>  2list*
  3(1class-direct-superclasses2 class**)2  **=>  2list*
  3(1class-finalized-p 2class**)*  =>  2true-or-false*
  3(1class-precedence-list 2class**)  *=>  2list-of-classes*
  3(1class-prototype 2class**)*  =>  2prototype-instance*
  3(1class-slots2 class**)2  **=>  2list*
  3(1compute-effective-method* 2generic-function method-combination method-list*)* => 2form*
  3(1ensure-class2 name*** &key3 :metaclass :environment :superclasses
                           :slots :default-initargs :documentation)* => 2class*
  3(1extract-lambda-list* 2specialized-lambda-list*)*  =>  2lambda-list*
  3(1extract-specializer-names* 2specialized-lambda-list*)*  =>  2list-of-class-names
  3(1finalize-inheritance** class3)**
  3(1generic-function-argument-precedence-order 2generic-function**)* =>2 list-of-symbols*  
  3(1generic-function-declarations 2generic-function**)*  =>  2list*
  3(1generic-function-lambda-list 2generic-function**)*  =>  2list*
  3(1generic-function-method-class 2generic-function**)*  =>  2class*
  3(1generic-function-method-combination 2generic-function**)*  =>  2method-combination*
  3(1generic-function-methods 2generic-function**)*  =>  2list-of-methods*
  3(1generic-function-name 2generic-function**)*  =>  2function-spec*
  3(1method-combination-name 2method-combination**)*  =>  2symbol*
  3(1method-combination-options* 2method-combination*)*  =>  2list*
  3(1method-function 2method**)*  =>  2function*
  3(1method-generic-function 2method**)*  =>  2generic-function*
  3(1method-lambda-list 2method**)*  =>  2list*
  3(1method-specializers 2method**)*  =>  2list-of-classes*
  3(1method-qualifiers 2method**)*  =>  2list*
  3(1method-slot-name 2accessor-method**)*  =>  2symbol*
  3(5slot-boundp1-using-class*** 2class3 *instance3 *slot-name3)**  =>  2true-or-false*
  3(1slot-definition-allocation 2slot-definition**)*  =>  2symbol*
  3(1slot-definition-initargs 2slot-definition**)*  =>  2list*
  3(1slot-definition-initform 2slot-definition**)*  =>  2form*
  3(1slot-definition-initfunction 2slot-definition**)*  =>  2function-or-nil*
  3(1slot-definition-name 2slot-definition**)*  =>  2symbol*
  3(1slot-definition-readers 2slot-definition**)*  =>  2list*
  3(1slot-definition-type 2slot-definition**)*  =>  2type-specifier*
  3(1slot-definition-writers 2slot-definition**)*  =>  2list*
  3(5slot-exists-p1-using-class*** 2class3 *instance3 *slot-name3)**  =>  2true-or-false*
  3(5slot-makunbound1-using-class*** 2class3 *instance3 *slot-name3)**
  3(5slot-value1-using-class*** 2class1 *instance3 *slot-name3)**  =>  2value*
  3(1specializer-direct-generic-functions* 2class*)*  =>  2list*
  3(1specializer-direct-methods* 2class*)*  =>  2list*
  3(1validate-superclass 2class superclass**)*  =>  2true-or-false


6Known problems**

  Methods specialized on 3(eql 2value*) *types are currently dispatched using 1eq*
  instead of 1eql.*  This means that it won't work for numbers other than fixnums
  or short floats.  [SPR 9639]

  Function 1ensure-generic-function* currently ignores its 3:environment* argument.

  The class 1stream* includes file streams but does not include windows when using CLOS
  on Explorer release 4 or 5.  This is fixed in release 6.

  Function 1function-keywords*  returns 3nil* as the first value whenever the second
  value is true.
  
  Redefining a generic function does not remove the methods from the previous
  1defgeneric*.

  Function 1slot-definition-initargs* only works on direct slots, not effective slots.

  Methods added to a generic function that has already been called at least once do not
  always get recorded properly in the case of methods with1 3(eql **...3)* specializers or in
  the case of a 1defmethod *used to replace a method previously defined as a slot
  accessor by 1defclass. * The symptom is that the new method is not invoked, even
  though it can be found by 1find-method*.  In such a situation it may be necessary to
  1fundefine* the generic function and re-install all of the methods.  [SPR 9586]

  Function 1class-direct-subclasses* always returns 1nil* for structure classes.
  [SPR 9641]

  Macros or 1defsubst*s which also have a 1setf *macro defined by 1defsetf* do not work
  correctly when used as the destination of a 1setf *within the body of a
  1symbol-macrolet*, 1with-slots*, or 1with-accessors* form.  The macro is expanded,
  ignoring the 1defsetf*.  [SPR 9627]

  There is no error checking for 1call-next-method* being called with arguments of the
  wrong class.  [SPR 9650]