OBJECTS(3X)

NAME
objects - object oriented programming extension

SYNOPSIS
#include objects.f83

objects

DESCRIPTION
This library realizes the popular class-instance model of object oriented programming. The "world" is divided into classes and instances. The classes hold all common information for the instances. This information is the instance variable fields and the messages an instance can answer. The answer of a message is called a method. A method may call the super class implementation of a message with the prefix word "super". This creates a static binding of the message to the super class. A messages require the object as the top most parameter stack element and will locate an appropriate method at run-time (late-binding).

: .class ( object -- )
    Displays the name of the class of an object on the current output stream.

: .message ( message -- )
    Displays the name of the message on the current output stream. May be used by the error message "doesNotUnderstand" which receives a message as parameter.

: align ( -- )
    Instance variable layout control word. Used to align the next field to an even byte boundary within the definition section of a class.

: basicInstanceSize ( class -- num)
    Returns the instance size in bytes.

subclass.field byte ( -- )
    Used within the instance variable section of a class definition to create a byte field name.
    byte <name> ( object -- addr)
    The field will require an object and will return the address of the byte within the object.

: bytes ( size -- )
    Used within the instance variable section of a class definition to create a byte vector field name.
    <size> bytes <name> ( object -- addr)
    The field will require an object and will return the address of the byte vector within the object.

: canUnderstand ( message class -- bool)
    Returns "true" if the class can understand the message (there exists a method) else "false".

: class ( object -- addr)
    Returns the class address for the object. The class is implemented as a prototype.

: dispose-instance ( object -- )
    Used in the following form:
    <object> dispose-instance ( -- )
    to reclaim memory allocated for an object. The object should not be accessed after this functions. Only objects allocated with the word "new-instance" may be reclaimed. Objects created with the word "instance" should be regarded as global variables.

forward doesNotUnderstand ( message object -- )
    Forward declared error message. Sent to an object when the message lookup mechanism fails. May be used to implement "proxy" objects.

subclass.field enum ( -- )
    Used within the instance variable section of a class definition to create a enumerate field name.
    enum <name> ( object -- addr)
    The field will require an object and will return the address of the enumerate within the object.

forward initiate ( ... object -- )
    This word is called by "new-instance" and "instance" and should be a message used to initiate the newly created object.

: instance ( class -- )
    Used in the following form:
    <class> instance <name> ( -- object)
    to create a named instance of a class. The message "initiate" is send to the newly created instance. This message must be answered.

subclass.field long ( -- )
    Used within the instance variable section of a class definition to create a long integer field name.
    long <name> ( object -- addr)
    The field will require an object and will return the address of the long integer within the object.

: message ( -- )
    Used in the following form:
    message <name> ( ... object -- ... )
    to create a message. The message may be passed to an object as a normal function call. The top most parameter is always required to be an object. A method for the message is located at run-time giving late binding, and polymorphism.

: method ( -- )
    Used in the following form within the definition section of a class:
    method <message> ( ... object -- ...) ... ;
    to define a method for the message. The method will receive the object, self, as the first parameter. To pass the message to the superclass the message prefix word "super" may be used. This is common practice in object oriented programming. The method definition should not contain the words "recurse", "tail-recurse", and "exception>" as these require an entry binding.

: new-instance ( class -- object)
    Used in the following form:
    <class> new-instance ( -- object)
    to create an instance of a class. The message "initiate" is sent to the newly created instance. This message must be answered or the error message "doesNotUnderstand" is sent to the instance. The object may be reclaimed with the word "dispose-instance".

vocabulary objects ( -- )
    The object oriented extension vocabulary. Include to the vocabulary search set, "context", to allow programming in the object oriented programming paradigm.

subclass.field ptr  ( -- )
    Used within the instance variable section of a class definition to create a pointer field name.
    ptr <name> ( object -- addr)
    The field will require an object and will return the address of the pointer field within the object.

: send ( object message class -- object)
    Primitive message sending function. Used by the normal message-passing, "message", mechanism to locate and apply a method.

: subclass ( superclass -- )
    Used in the following form:
    <class> subclass <name>
    { <instance-variable-field> }
    { <method> }
    subclass.end
    to initiate the definition of a class. This definition should contain two major sections; the instance variable fields, and the instance methods. All field names will become local to the class. The words "byte", "bytes", "enum", "word", "long" and "ptr" should be used to create instance variable field names. These will require an object pointer and will return the address of the corresponding field. The field should then be manipulated with the memory access functions. The word "align" may be used before a field name definition to align it to an even byte boundary. The method definition section may contain implementations of messages. A method may be viewed as a normal colon definition with the extension that many definitions, methods, for the same name, message, may exist simultaneous and the selection is performed at run-time (late binding). The method should always receive the object, self, as the top most parameter. The message prefix word "super" may be used to call the super class implementation of a method. This binding is static. The word "this-class" may be used to access the current class. The method may not use the words "recurse", "tail-recurse", and "exceptions>" as these require an entry binding.

: subclass.end ( -- )
    Used in the following form:
    <class> subclass <name>
    { <instance-variable-field> }
    { <method> }
    subclass.end
    to finish the definition of a class. Additional methods and fields should not be defined after this word.

: super ( -- ) immediate compilation
    Used in the following form within a method definition:
    super <message>
    to call a method for a message in the superclass. This word should only be used inside of method definitions.

: superclass ( class1 -- class2)
    Returns the address super class of the class. The value is "nil" for a root class.

: this-class ( -- class) immediate
    Returns the address of the current definitions class. Will return "nil" outside of a class definition.

subclass.field word ( -- )
    Used within the instance variable definition section of a class to create a word integer field name.
    word <name> ( object -- addr)
    The field will require an object and will return the address of the word integer within the object.

INTERNALS
Private definitions in the objects vocabulary;

: allot-instance ( class -- object) private
    Used in the following form:
    <class> allot-instance ( -- object)
    to create an instance of a class. The message "initiate" is sent to the newly created instance. This message must be answered or the error message "doesNotUnderstand" is sent to the instance. The object is allocated from the dictionary area.

slot instance-size: ( class -- num) private
    Slot for a class (prototype) containing the number of byte for an instance of this class.

slot instance-variables: ( class -- entry) private
    Slot for a class (prototype) containing a pointer to the last defined instance variable field entry. The list of variables is terminated by the class itself.

: subclass.field ( size -- ) private
    Use to create instance variable field type names. These field types should only be used within a class definition.

variable the-class ( -- addr) private
    Used within a class definition section to access the address of the current definition class. Outside of the definition section the variable will have the value "nil".

SEE ALSO
tile(1), forth(3X), prototypes(3X).

NOTE
The function list is sorted in ASCII order. The type and mode of the entries are indicated together with their parameter stack effect.

WARNING
This library contains forward declared words which should be supplied. Check that your definitions vocabulary comes before the "objects" vocabulary when defining these words.

COPYING
Copyright (C) 1990 Mikael R.K. Patel

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English.

AUTHOR
Mikael R.K. Patel
Computer Aided Design Laboratory (CADLAB)
Department of Computer and Information Science
Linkoping University
S-581 83 LINKOPING
SWEDEN
Email: mip@ida.liu.se