[GLD%MIT-OZ@MIT-MC.ARPA: ObjectLisp]

[Kahn.pa@Xerox.ARPA]

I just received the following message from Gary Drescher.
It seems that there will be three proposals to discuss on the meeting on
Thursday (Math Sciences auditorium from 4 to 6pm).  HP, Xerox, and the
following one (LMI):

     ----- Begin Forwarded Messages -----

Return-Path: <@MIT-MC.ARPA:GLD@MIT-OZ>
Received: from MIT-MC.ARPA by Xerox.ARPA ; 15 AUG 85 12:54:01 PDT
Received: from MIT-OZ by MIT-MC.ARPA via Chaosnet; 15 AUG 85  15:51:03
EDT
Date: Thu, 15 Aug 85 15:52 EDT
Message-ID: <GLD.12135387162.BABYL@MIT-OZ>
 From: GLD%MIT-OZ@MIT-MC.ARPA
To: Kahn.pa
Subject: ObjectLisp
In-reply-to: Msg of 15 Aug 1985  13:22-EDT from GLD


Hi Ken.  The folks at LMI tell me I should send my current ObjectLisp
Manual
to the appropriate CommonLisp mailing list, whose name I've
unfortunately
misplaced.  So I'm mailing it to you instead; could you be so kind as to
forward it to the list?

I'll be at IJCAI on the 21st & 22nd; see you then.

Thanks,
Gary

mit-oz:<gld.obl>manual.tex   (LaTex format)

%       -*- Mode:Text -*-
\documentstyle[draft]{article}
\setlength{\textheight}{9in}
\setlength{\textwidth}{6.5in}
\setlength{\topmargin}{-0.25in}
\setlength{\oddsidemargin}{0in}
\setlength{\evensidemargin}{0in}

\newcommand{\code}[1]{\mbox{\tt #1}}
\newcommand{\argd}[1]{{\normalsize \sl #1}}
\newcommand{\deff}[2]{\bigskip \noindent
  \makebox[\textwidth]{\code{#1} \hfill {\it #2}}}
\newcommand{\OBL}{{\sc ObjectLisp\/}}
\newcommand{\LISP}{{\sc Lisp\/}}

\begin{document}

{\centering \Large \OBL{} Manual\\[2ex] \large Gary L. Drescher\\}

\noindent \makebox[\textwidth]{Copyright \copyright Gary L. Drescher
1985
 \hfill Draft of \today}

\section{Introduction: Objects and \OBL}

\OBL{} is a dialect of \LISP{} that facilitates object-oriented
programming.\footnote{The Flavors system is another such facility.  This
document introduces only \OBL{}; but there are occasional footnotes
addressed
to Flavors users, explaining how some common applications of Flavors can
be
mimicked using \OBL.} Object-oriented programming involves the creation
of
various {\em classes} (kinds or categories) of things, and {\em
instances}
(individuals, examples) of those classes.  For example, there might be a
class
of ``automobiles'', and ``the car I just bought'' might be an instance
of that
class.  The classes often form a hierarchy\footnotemark--
\footnotetext{More
generally, the classes form a {\em lattice}.  The difference is that in
a
hierarchy, each class is a specialization of just one other class; in a
lattice, more than one class can be combined when making a subclass.}
you can
make a new class by saying that it is a {\em specialization}, a more
specific
version, of another class; for example, ``convertible'' is a
specialization of
``automobile''.  In \OBL, both classes and instances are implemented by
what
are simply called {\em objects}.  \footnote{The word {\em object} is
traditionally used to refer to any kind of datum in \LISP-- a list, a
symbol, a
fixnum, etc.  In this document, however, {\em object} refers only to the
object-entities provided by \OBL for object-oriented programming.}

In \OBL, an object has a collection of bindings of variables and
functions,
which determine the object's properties and behavior.  A {\em variable
binding}
can be thought of as a distinct version of some variable, with its own
separate
value for that variable; for example, one object might have a binding of
the
symbol \code{x} to the value 3, while another binds \code{x} to 4.  The
ordinary \LISP{} environment is considered \OBL's {\em global object},
and
symbols are bound there to their ordinary \LISP{} global values.  A {\it
function binding} is similar to a variable binding, but it associates a
symbol
with a definition, rather than a value.  Ordinary use of \code{defun}
creates a
global function binding.

A {\em specialization} of an existing object is a new object that can be
given
its own variable and function bindings; in addition, it {\em inherits}
all the
bindings of the previous object, except for symbols whose bindings the
new
object replaces (this is called {\em shadowing}) with bindings of its
own.  By
making a specialization of a class object, you can make a new class that
is
just like the old one, except for the differences you specify.

Similarly, an instance of a class inherits bindings from that class, and
can be
given exceptions and contributions of its own; in these respects, an
instance
object is just like a specialized class object.  The difference is a
matter of
convention, of how the objects are built and used: the bindings given to
an
instance describe the properties of some {\em individual} entity; the
bindings
of a class describe things common to {\em all} entities of a certain
kind.

For example, we might define a class object called \code{icon}.
Instances of
this class are small pictures that can be moved about on the graphics
screen.
The \code{icon} object includes, say, a binding for the function
\code{goto-xy}
(which expects two numbers specifying the new X and Y coordinates at
which to
display the picture).  \code{icons}'s binding of the function
\code{goto-xy}
(along with any other bindings \code{icon} may have) is inherited by all
specializations of \code{icon}, and also by all instances of
\code{icon--} all
such objects share that inherited binding, except those objects where
the
binding has been shadowed.  In addition, each \code{icon} instance
includes
(let's say) a binding of the variables \code{x-coord} and
\code{y-coord}; these
say where on the screen the icon is currently drawn.  Obviously, those
variables can't be shared by all icons; each icon needs its own bindings
of
\code{x-coord} and \code{y-coord}, since different icons can be in
different
positions.

Typically, as in this example, class objects are given function
bindings, and
instance objects are given variable bindings.  The functions determine
how
members of a class behave, and are shared by all instances of a class;
the
variables describe the state or attributes of individual instances, and
each
instance has its own.  We speak of {\em class functions} and {\em
instance
variables}\footnote{These are analogous to flavor methods and instance
variables, respectively, in the Flavor system.  Flavors provide no
counterpart
for class variables and instance functions, however.}.  In addition
(though
less commonly) it can be useful to have variable bindings in class
objects
(class variables) and function bindings in instance objects (instance
functions).

\OBL{} requires the use of only a handful of new primitive functions:
\begin{itemize}
 \item \code{make-obj} and \code{kindof} are used to make new objects.
 \item \code{ask} is used to cause any sequence of \LISP{} expressions
to be
evaluated in the environment of a given object.
 \item \code{defobfun} is used (in place of \code{defun}) to create
function bindings in an object.
 \item \code{have} is used to create variable bindings in an object.
\end{itemize}

These primitives are described in
section~\ref{building-objects-section}.  In
addition, there are other object primitives that, although not strictly
necessary, are useful to abbreviate common patterns of functions, or for
increased efficiency and clarity, or for esoteric manipulation of
objects.
These are described in section~\ref{reference-section}.

\section{Building object systems}
 \label{building-objects-section}
\subsection{Making an object}

The function \code{make-obj} creates and returns a fresh object.  For
example:
\begin{verbatim}
    (setq icon (make-obj))}
\end{verbatim}
The global variable \code{icon} is now bound to a new object.

Let's define the functions \code{goto-xy}, \code{draw-self}, and
\code{undraw-self} for the object \code{icon}.
\begin{verbatim}
    (defobfun (goto-xy icon) (x y)
      (undraw-self x-coord y-coord)
      (draw-self x y)
      ;; Record the new position for next time.
      (setq x-coord x)
      (setq y-coord y))
    
    ; Draw icon at X,Y.
    (defobfun (draw-self icon) (x y)
      (bitblt-to-graphics-window tv:alu-xor icon-array x y))
    
    ; Erase icon already drawn at X,Y.
    (defobfun (undraw-self icon) (x y)
      (draw-self x y)) ; (XOR'ing the same thing twice cancels.)
\end{verbatim}
(Assume that the global function \code{bitblt-to-graphics-window} has
been
defined, and that the global variables {\code x-coord} and
\code{y-coord} are
bound to coordinate numbers, and \code{icon-array} is bound to an array
that
has the icon's picture.)

\code{defobfun} has the same syntax as \code{defun}, except for the
function specifier.  Instead of just the function's name, there is a
list of
the function's name and another symbol.  The other symbol must be bound
to an
object.  The function is defined locally to that object-- that is, the
object
is given its own function binding of the symbol that names the function.
Here,
the object bound to \code{icon} gets its own function bindings of
\code{goto-xy}, \code{draw-self}, and \code{undraw-self}.

Suppose the global variables \code{x-coord} and \code{y-coord} have both
been
initialized to 0, and the icon has been drawn at (0,0).  To move the
icon to
(100,100), we say
\begin{verbatim}
    (ask icon (goto-xy 100 100))
\end{verbatim}

The first argument to \code{ask} must be an object.  The remainer of the
\code{ask} form-- the body of the \code{ask}-- is evaluated in the
environment of the designated object.  This means that that object's
bindings
are in effect during the evaluation of the body.   (For the duration of
that
evaluation, The object passed to \code{ask} is called the {\em current
object}.)  In particular, the function \code{goto-xy} is bound in the
\code{icon} object, due to the \code{defobfun} definition above; so
\code{icon}'s definition is the one that is used when the above
\code{ask}
form is evaluated.  When \code{goto-xy} calls \code{draw-self} and
\code{undraw-self}, we are still (dynamically) within the body of the
\code{ask}, so \code{icon}'s function bindings of \code{draw-self} and
\code{undraw-self} are referred to.

After \code{goto-xy} has run, \code{x-coord} and \code{y-coord} are both
set to
100, and the drawing of the icon has moved to (100,100).  Note that we
have
defined \code{goto-xy} {\em only} for the \code{icon} object; if we just
say
\code{(goto-xy 50 75)} without addressing \code{icon}, we get an
undefined-function error (unless of course someone has {\em also}
defined
\code{goto-xy} globally; in that case, the global definition is
invoked).

\subsection{Classes and instances}

You may have noticed something unsatisfactory about this example: there
is just
one version of each of the variables \code{x-coord}, \code{y-coord}, and
\code{icon-array} (\code{icon-array} is global; \code{x-coord} and
\code{y-coord} are bound in \code{icon}.)  How, then, is it possible to
create
several different icons, all at different locations (and perhaps with
different
picture-arrays)?

The answer is to think of \code{icon} as a class object, and to create
various
corresponding instance objects.  Here's how that works.  Suppose we wish
to
create two icon instances, \code{icon1} and \code{icon2}.   We say
\begin{verbatim}
    (setq icon1 (kindof icon))
    (setq icon2 (kindof icon))
\end{verbatim}

\code{kindof} creates a new object as a specialization of the object(s)
provided as inputs.  (Actually, \code{kindof} and \code{make-obj} are
synonyms; \code{kindof} sounds more natural when arguments are passed,
but
both functions accept zero or more arguments.)  When there is just one
argument-- as in this example-- the specialized object {\em inherits}
all the
bindings of the {\em base object} (the object that it specializes, that
it is
``based on'').  For example, that the above definitions of
\code{goto-xy},
\code{draw-self}, and \code{undraw-self} are accessible during a
\code{ask}
to \code{icon1} or \code{icon2}, as well as to \code{icon} itself.

In addition to inheriting bindings, a specialized object can be given
its {\it
own} bindings.  These are {\em not} inherited by the base object;
inheritance
only goes in one direction.  But of course, other objects can be made as
specialized objects of a given specialized object; {\em those} objects
will
inherit the bindings established in the given object and they will also
inherit, in turn, the bindings that the given object inherited.  The
only
exception to this inheritance occurs when an object {\em shadows} a
variable or
function binding that it would otherwise have inherited; it does this by
having
its {\em own} binding of the same variable or function, which supercedes
the
one it would have inherited.

We want \code{icon1} and \code{icon2} to be instances of \code{icon}.
Thus, we
must supply these objects with appropriate instance variables--
variables that
specify the individual attributes of the two icons.  In particular, we
want
\code{icon1} and \code{icon2} each to have its own binding of the
variables
\code{x-coord}, \code{y-coord}, and \code{icon-array}.  We use
\code{have}
to create these bindings. {\code{(have '\argd{sym val})} causes
the current object to acquire its own binding of the symbol \argd{sym},
with
value \argd{val}.
\begin{verbatim}
    (ask icon1
      (have 'x-coord 0)
      (have 'y-coord 25)
      (have 'icon-array circular-design))
\end{verbatim}

Now \code{icon1} has its own bindings of \code{x-coord} and
\code{y-coord} (to
0 and 25, respectively), and of \code{icon-array} (to an array with a
circular
design, assuming that the global variable \code{circular-design} had
been bound
to such an array).  To initialize \code{icon1}'s picture on the screen,
we
should also say
\begin{verbatim}
    (ask icon1 (draw-self 0 25))
\end{verbatim}
And similarly:
\begin{verbatim}
    (ask icon2
      (have 'x-coord 0)
      (have 'y-coord 50)
      (have 'icon-array square-design)
      (draw-self 0 50))
\end{verbatim}
\code{icon1} and \code{icon2}'s variable bindings are separate from one
another, and from any global bindings of the same symbols.  For example,
evaluating \code{y-coord} globall still returns 100.  But {\code (ask
icon1
y-coord)} returns 25, and \code{(ask icon2 y-coord)} returns 50.

Suppose we say \code{(ask icon1 (goto-xy 0 75))}.  When \code{goto-xy}
was
done within \code{icon} instead of \code{icon1} (above), occurrences of
\code{x-coord}, \code{y-coord}, and \code{icon-array} in the body of
{\code
goto-xy} referred to the {\em global} bindings of those symbols; that
was
because the \code{icon} object had no bindings of those symbols.  (And
if we
now said \code{(ask icon (goto-xy 0 75))}) again, the references to
those
variables would {\em still} refer to their global values.)  But with
{\code
(ask icon1 (goto-xy 0 75))}, those same references occur during a
\code{ask}
to \code{icon1}, which {\em does} bind those symbols.  Hence, the
references
now are to \code{icon1}'s bindings.  Notice especially that this is true
both
for {\em getting} the values of these symbols (when the symbols are
evaluated
to provide arguments to \code{goto-xy}'s call to \code{undraw-self}),
and also
for {\em setting} their values (by the \code{setq}'s at the end of
{\code
goto-xy}).  \code{setq} never {\em creates} new variable bindings in an
object;
only \code{have} does that.  \code{setq} just changes the value of an
existing binding.\footnote{Readers familiar with the taxonomy of binding
schemes will notice that objects are dynamically scoped closures.  That
is,
upon entry to an object (via \code{ask}), all the variables for which
that
object has bindings are dynamaically bound to the associated values;
upon
exiting the \code{ask}, those bindings are dissolved (the values first
being
saved in the object, for the sake of any subsequent \code{ask} to that
object).  (More accurately, if one \code{ask} occurs dynamically within
another, the outer \code{ask}'s object is exited before entering the
inner
\code{ask}, then re-entered upon exiting the inner \code{ask}).} So now,
\code{(ask icon1 y-coord)} returns 75; but \code{(ask icon2 y-coord)}
still
returns 25, and evaluating \code{y-coord} globally still returns 100.

Now we have an \code{icon} class and some icon instances, but something
is
still awry.  Surely it is unacceptable to have to initialize each new
instance
by \code{ask}'ing it to \code{have} each of its instance variables (and
to draw itself initially), as we did above.  This problem will be
especially
acute when we build objects that need dozens of instance variables and
initializing actions.  Fortunately, of course, there's no need to do all
this
manually-- we can define a function to do it automatically.  For
example:
\begin{verbatim}
    (defobfun (exist icon) (&rest args &key* (x 0) (y 0)
                                             (array default-icon-array))
      ;; Establish a binding of the variable X-COORD to the value of
      ;; the EXIST function's parameter X:
      (have 'x-coord x)
      ;; Etc:
      (have 'y-coord y)
      (have 'icon-array array)
      ;; Make the initial drawing.
      (draw-self x y)
      ;; (Ignore the following line for now; it is explained below.)
      (apply 'shadowed-exist args))
\end{verbatim}
 From now on, making new ICON instances is much easier; for example:
\begin{verbatim}
    (setq icon3 (kindof icon))  (ask icon3 (exist))
    (setq icon4 (kindof icon))  (ask icon4 (exist 'array
circular-design))
\end{verbatim}
The caller can provide keyword arguments to override the \code{exist}
function's defaults for the initial instance-variable values.  Of
course, we
might instead have defined the \code{exist} function to ``hardwire''
some or
all of the initial values, rather than giving the caller the choice of
supplying them; and we might have had other \code{exist} arguments, ones
that
did not correspond to instance-variable initializations.
\label{key-intro}

\begin{quote}
Note: \code{defobfun} treats \code{\&key*} arguments slightly
differently than
\code{\&key} ones.  With \code{\&key*,} the default is that a key name
is {\it
not} put in the keyword package; hence \code{(exist 'array ...)} above
rather
than \code{(exist :array ...)}.  Also, \code{\&allow-other-keys} is
implicit
when \code{\&key*} is used.  The rationale for these differences is
explained
at the end of section~\ref{key-explanation}.
\end{quote}

The idea behind the \code{exist} function is simple: although the
different
instances of \code{icon} cannot share instance variables with one
another--
each instance needs its own set of instance variables-- the instances
{\em can}
share a ``template'' for {\em creating} those variables (and for
performing
other needed initializations).  That shared template is provided, in the
form
of the \code{exist} function bound in the \code{icon} class object.
There is
nothing magic about using the name \code{exist} for this function; but
it turns
out to be a good idea to have a standard name for instance-initializing
functions, and \code{exist} is that standard.

\bigskip

We have just seen that \OBL{} does not insist on distinguishing between
classes
and instances-- both are just objects, made by the function
\code{kindof} (or
\code{make-obj})).  In fact, the distinction between classes and
instances
is entirely a matter of the conventions that the user follows.  Recall
that
when we first created the \code{icon} object, we didn't have to say
whether it
was a class or an instance-- and indeed, we used it as {\em both}.  We
defined
the class functions \code{goto-xy}, \code{draw-self}, and
\code{undraw-self}
locally to \code{icon,} as though \code{icon} were a class object.  But
when we
actually told \code{icon} to move to a new position (by saying
\code{(ask icon
(goto-xy 100 100))}, we were treating it as a instance.  It is often
useful,
when creating a new class of object on the fly, to treat the class as a
prototype instance.  That way, you don't have to decide in advance what
instance variables need to be created-- you just use global variables.
And
conversely, it may be useful to treat an instance object as a prototype
class,
by giving the instance some experimental function bindings to specialize
its
behavior.  But the conventional class/instance distinction is important,
and it
is strongly recommended that object-oriented software be designed
according to
this convention.

To facilitate the class/instance distinction, \OBL{} provides the
primitive
\code{oneof} for making instance objects, and \code{defkind} for making
class
objects.  Both of these primitives can be thought of as calling
\code{kindof,}
as well as performing some auxiliary actions.  \code{oneof} and
\code{defkind}
are useful because their auxiliary actions are especially convenient for
instances and classes (respectively); and because these primitives make
implicit declarations about the nature of the object being created,
resulting
in more efficient code.  \code{oneof} and \code{defkind} are documented
in
part~\ref{reference-oneof} of the reference section.

\subsection{Object binding vs lexical binding}
\label{obj-vs-lex}

Here is a point that deserves emphasis, as it is an easy one to stumble
on:
lexical binding {\em overrides} object binding; only {\em free
references} can
refer to object bindings.  This is now explained in detail.

Within a lambda expression (or within any implicit lambda expression,
such as a
\code{defun} or a \code{let}), certain variables-- the parameters in the
arglist of a lambda expression or function body, or the variables in the
varlist of a \code{let--} are {\em lexically bound}.  Suppose the
variable
\code{a} is lexically bound in any kind of lambda expression.  Any
reference to
\code{a} in the body of that expression-- any form to get or set the
value of
\code{a--} refers to the current lexical binding of \code{a,} {\em
regardless}
of whether we happen to be inside a \code{ask} to an object that
contains a
binding of \code{a.} For example, suppose the object bound to the symbol
\code{obj1} binds \code{a} to 10 and \code{b} to 20; and suppose we say:
\begin{verbatim}
    (let ((a 3))
      (ask obj1
         (setq a (1+ a))
         (print a)
         (setq b (1+ b))
         (print b)))
\end{verbatim}

The \code{a} that gets incremented by the expression \code{(setq a (1+
a))} is
the \code{let}'s binding of \code{a}, {\em not} \code{obj1}'s binding of
\code{a}; \code{obj1}'s binding of \code{a} is unaffected.  Similarly,
the
\code{a} in \code{(print a)} refers to the \code{let}'s binding of
\code{a};
hence, the number 4 is printed.  The two references to \code{b}, on the
other
hand, are {\em free} references-- that is, \code{b} is not lexically
bound in
this expression.  Therefore, \code{b} {\em does} refer to \code{obj1}'s
binding; \code{obj1}'s value for \code{b} is incremented, and the new
value,
21, is printed.  (Of course, if \code{obj1} had no binding for \code{b,}
then
the reference would be to the global variable \code{b}.)

(A possible source of confusion: the function \code{have} {\em creates}
an
object-binding of the specified variable, rather than {\em referring} to
an
existing binding; so \code{(have 'a {\argd value})} gives the current
object
its own binding of A, {\em even if} the \code{have} occurs in an
expression
where A is lexically bound.)

To repeat: lexical binding overrides object binding.  This fact can be
helpful
when you need to communicate one object's value for some variable to
another
object that binds the same variable.  For example, you should convince
yourself
that this expression:
\begin{verbatim}
    (ask icon1 (let ((x x-coord)
                      (y y-coord))
                  (ask icon2 (goto-xy x y))))
\end{verbatim}
changes \code{icon2}'s position to coincide with \code{icon1}'s, whereas
\begin{verbatim}
    (ask icon1 (ask icon2 (goto-xy x-coord y-coord)))
\end{verbatim}
leaves \code{icon2}'s position unchanged, since \code{x-coord} and
\code{y-coord} refer here to \code{icon2}'s own bindings.

Functions, as well as variables, can be lexically bound; function
binding is
accomplished in \LISP{} by using \code{flet} or \code{labels}.  For
functions,
too, lexical binding overrides object binding.

\section{Specialized classes}

The real power of object-oriented programming comes from being able to
{\em specialize} existing classes of objects.  A new object can be built
just
by saying how it {\em differs} from an old one; everything not mentioned
is
just inherited, and stays the same.

For example, suppose we want to make a kind of icon that draws a line
when it
moves, leaving a trail behind it.  First, we make a specialized object
 from
\code{icon}:
\begin{verbatim}
    (setq icon-with-trail (kindof icon))
\end{verbatim}
This time, we're going to regard the new object as a specialized {\em
class}
object, whereas in the previous section, \code{kindof} was used to
create a
specialization of \code{icon} that we regarded as an {\em instance} of
\code{icon}.

\code{icon-with-trail} needs to shadow the inherited function binding of
\code{goto-xy} (from \code{icon}), and to supply its own definition
instead.
\code{icon-with-trail}'s \code{goto-xy} should do what the shadowed
\code{goto-xy} does; and in addition, the new \code{goto-xy} function
needs to
draw a line.  Here is a definition that is {\em almost} right:
\begin{verbatim}
    (defobfun (goto-xy icon-with-trail) (x y)
      ;; Draw line from (X-COORD,Y-COORD) to (X,Y), assuming that the
function
      ;; DRAW-LINE-ON-GRAPHICS-SCREEN has been suitably defined.
      (draw-line-on-graphics-screen x-coord y-coord x y)
      ;; Now invoke the shadowed GOTO-XY.
      (goto-xy x y)) ; This line is >WRONG<, however.
\end{verbatim}
The problem here is that the occurrence of \code{goto-xy} (in the last
line)
will {\em not} refer to the shadowed version of \code{goto-xy}; it will
refer
to the {\em shadowing} definition, which is the above definition itself.
This
version of \code{goto-xy} will call {\em itself}, not the shadowed
version of
itself.

It is common for a shadowing definition of a function to want to call
the
shadowed version, {\em in addition} to performing some new idiosyncracy.
Here,
we could accomplish this by looking up \code{icon}'s definition of
\code{goto-xy,} and copying it into the end of \code{icon-with-trail}'s
definition.  But it is much better to be able to {\em call}
\code{icon}'s
\code{goto-xy}, without needing to know how it was implemented-- and
without
needing to {\em change} \code{icon-with-trail}'s version of
\code{goto-xy} if
\code{icon}'s version is ever redefined, and we want to stay compatible
with
it.  \OBL's {\em shadowed} facility makes this possible.  Here is the
correct
definition of \code{icon-with-trail}'s \code{goto-xy}:
\begin{verbatim}
    (defobfun (goto-xy icon-with-trail) (x y)
      (draw-line-on-graphics-screen x-coord y-coord x y)
      (shadowed-goto-xy x y))
\end{verbatim}

Within the text of a definition of the function {\em name}, the symbol
\mbox{\code{shadowed-}{\em name}} refers to the version of {\em name}
that {\it
would have} been inherited, had not this very definition shadowed it.
So here,
for \code{icon-with-trail}, we've added our line-drawing idiosyncracy to
\code{goto-xy}'s shadowed behavior, without needing to be concerned with
how
that shadowed behavior was implemented.

Next, suppose we say:
\begin{verbatim}
    (setq icon5 (kindof icon-with-trail))
    (ask icon5 (exist 'x 10 'y 10))
    (ask icon5 (goto-xy 50 50))
\end{verbatim}
Now we've got \code{icon5} drawn at (50,50), and a line drawn on the
screen
 from (10,10) (where \code{icon5} first appeared) to (50,50).  Note that
the
\code{exist} function just invoked was inherited by \code{icon5} from
\code{icon-with-trail,} which in turn inherited it from \code{icon}; the
functions \code{draw-self} and \code{undraw-self} are similarly
inherited.

Here's another specialization of \code{icon}:
\begin{verbatim}
    (setq boundary-icon (kindof icon))
    
    (defobfun (goto-xy boundary-icon) (x y)
      (unless (out-of-bounds? x y)
         (shadowed-goto-xy x y)))
    
    (defobfun (out-of-bounds? boundary-icon) (x y)
      (or (< x (car x-bounds)) (>= x (cadr x-bounds))
          (< y (car y-bounds)) (>= x (cadr y-bounds))))
    
    (defobfun (exist boundary-icon) (&rest args &key* (x-bounds '(0
100))
                                                      (y-bounds '(0
100)))
      (have 'x-bounds x-bounds)
      (have 'y-bounds y-bounds)
      (apply 'shadowed-exist args))
    
    (setq icon6 (kindof boundary-icon))
    (ask icon6 (exist 'scale 5))
\end{verbatim}
\code{boundary-icon} is a kind of \code{icon} that never strays outside
a
certain rectangular region.  The region is specified by the instance
variable
\code{x-bounds} (which is a list of the lower and unpper values for the
icon's
x-coordinate) and the instance variable \code{y-bounds} (similarly).
Notice
that \code{boundary-icon}'s definition of \code{goto-xy} doesn't
necessarily
invoke \code{shadowed-goto-xy}-- first, it checks to see if the new
\code{x,y}
coordinates are within bounds.  If they aren't, no further action is
taken; if
they are, \code{goto-xy} behaves as usual.

Notice how \code{boundary-icon}'s \code{exist} function is set up.  This
version of \code{exist} only knows about the instance variables that are
special to \code{boundary-icon}: the variables \code{x-bounds} and
\code{y-bounds}.  Any other key arguments that might be passed to
\code{boundary-icon}'s \code{exist} function are simply passed on to the
{\it
shadowed} \code{exist} function (via the parameter \code{args}); and
\code{boundary-icon}'s \code{exist} function has no knowledge of what
those
passed-on arguments may be.  This compartmentalization of knowledge is
valuable; to support it, \code{exist} functions should {\em always} be
defined
with no arguments other than \code{\&key*} ones.  And \code{exist}
functions
should always be defined to call \code{shadowed-exist}, passing all
arguments
along, so that the initializing actions (especially instance-variable
creation)
of the base class(es) happen along with the actions peculiar to the
specialized
object's \code{exist} definition.

\label{key-explanation} \code{\&key*} was introduced on
page~\pageref{key-intro}.  Now the rationale for \code{\&key*} becomes
apparent.  First, extraneous arguments to an \code{exist} function might
be
expected by a \code{shadowed-exist}; so each \code{exist} function
should allow
all keys (which happens automatically with \code{\&key*}.  Second, it is
important to avoid accidental name conflicts between one \code{exist}
function's keywords and those of a shadowed \code{exist} procedure
called be
the first one.  The only way to assure this avoidance, without knowing
the
other names involved, is to keep the symbols in different {\em
packages};
hence, \code{\&key*'s} default of keeping the keyword symbol's original
package, rather than moving all keyword symbols into the keyword
package.

\section{Multiple inheritance}
\label{multiple-inherit}

\code{kindof} can be called with several base objects as arguments.  In
this
case, the object that \code{kindof} creates is a specialization of all
the
input objects-- that is, the new object inherits bindings from each of
those
objects.  This is useful when either:
\begin{itemize}
\item The input objects are {\em disjoint}-- that is, if there is no
overlap
between the symbols bound by one such object, and those bound by any
other.  In
this case, the set of bindings inherited by the object is simply the
union of
all the input object's bindings.
 \item The input objects are all specializations of some common base
object.
That is, each input object adds its own idosyncracies to the common base
object.  In this case, the new object is a combination of the
idiosyncracies of
the input objects, together with the common base object.  This is
explained
more precisely below.
\end{itemize}

Consider an example of the second sort.  Here, we create a new class
object,
\code{boundary-icon-with-trail}, that inherits from both
\code{boundary-icon}
and \code{icon-with-trail} (which share the base object \code{icon}).
\begin{verbatim}
    (setq boundary-icon-with-trail (kindof boundary-icon
icon-with-trail))
    (setq icon7 (kindof boundary-icon-with-trail)
    (ask icon7 (exist))            ;ICON7 is an instance of
BOUNDARY-ICON-WITH-TRAIL.
    (ask icon7 (goto-xy 0 100))    ;ICON7 moves to 0,100, drawing a
trail.
    (ask icon7 (goto-xy 200 200)   ;Nothing happens, for 200,200 is out
of bounds.
\end{verbatim}
\label{binding-frames}

To understand how these forms work, we need to be more explicit about
the
composition of objects.  Think of an object as a list of {\em binding
frames},
listed from {\em innermost} to {\em outermost}.  An object's own
bindings
reside in its innermost frame; its inherited bindings reside in the
other
frames, which the object shares with its base object(s).  When
\code{kindof} is
called with no arguments, the resulting object's list of frames has only
one
member: the freshly-created frame.  (\LISP's ordinary global
environment,
\OBL's ``global object'', can be thought of as having a frame containing
all
global variable and function bindings; this is implicitly the outermost
frame
of {\em all} objects.) When \code{kindof} is called with just one
argument, the
new object's list of frames begins with a fresh frame that \code{kindof}
creates, followed by all the frames of the input object.

Now suppose \code{kindof} is called with several input objects.  Once
again, we
get a list of frames starting with the new object's own freshly-created
frame.
The other frames are gotten by, first, appending together the list of
frames
 from each of the input objects (in the order in which the inputs were
passed);
second, eliminating any {\em duplicated} frames in the appended list,
leaving
only the {\em outermost} occurrence of each frame.  For example, just
above,
these objects
\begin{quote}
\code{boundary-icon}: \mbox{[\code{boundary-icon}'s frame],}
 \mbox{[\code{icon}'s frame].}\\
\code{icon-with-trail}: \mbox{[\code{icon-with-trail}'s frame],}
 \mbox{[\code{icon}'s frame].}
\end{quote}
were combined to form
\begin{quote}
\code{boundary-icon-with-trail} (before eliminating duplications):\\
\mbox{[\code{boundary-icon-with-trail}'s frame],}
\mbox{[\code{boundary-icon}'s frame],}
\mbox{[\code{icon}'s frame],}\\ \mbox{[\code{icon-with-trail}'s frame],}
\mbox{[\code{icon}'s frame].}\bigskip
after eliminating duplications:\\
\mbox{[\code{boundary-icon-with-trail}'s frame],}
\mbox{[\code{boundary-icon}'s frame],}\\
\mbox{[icon-with-trail's frame],} \mbox{[icons's frame].}
\end{quote}

Note that after duplicates are eliminated, the inherited frames consist
of the
two specialized frames (from \code{boundary-icon} and
\code{icon-with-trail})
followed by the frame(s) (just one, in this case) from their common base
object, \code{icon}.  \code{icon7}, of course, looks like this:
\begin{quote}
\code{icon7}: \mbox{[\code{icon7}'s frame],}
 \mbox{[\code{boundary-icon-with-trail}'s frame],}
 \mbox{[\code{boundary-icon}'s frame],}\\
 \mbox{[\code{icon-with-trail}'s frame],} \mbox{[\code{icon}'s frame].}
\end{quote}

Because the specialized frames are followed by the common inherited
frame(s),
the combined object behaves as though both specializations were made,
successively, to the common object.  When \code{icon7} is told to
\code{goto-xy}, the reference to \code{goto-xy} is resolved, as always,
by
finding the innermost frame in \code{icon7} that contains a binding of
the
function \code{goto-xy.} Therefore, \code{boundary-icon}'s definition is
found.
This version of \code{goto-xy} first checks if its arguments are within
bounds.
If not, no further action is taken-- in particular,
\code{shadowed-goto-xy} is
{\em not} called.  But if the coordinates are ok,
\code{shadowed-goto-xy} {\it
is} called.  This \code{shadowed-goto-xy} refers to the next-innermost
definition of \code{goto-xy} in \code{icon7}'s list of frames-- namely,
\code{icon-with-trail}'s definition.  \code{icon-with-trail}'s
\code{goto-xy}
draws the required trail, and also calls \code{shadowed-goto-xy}--
referring
again to the next-innermost binding of \code{goto-xy}, in this case
\code{icon}'s.  \code{icon}'s \code{goto-xy} takes care of the basic
erasing
and redrawing of the icon's picture, and maintains the icon's
\code{x-coord}
and \code{y-coord} variables.

Similarly, when \code{icon7} was told to \code{exist,}
\code{boundary-icon}'s
\code{exist} function was invoked.  It called \code{shadowed-exist},
invoking
\code{icon}'s \code{exist}.  (Recall that \code{icon-with-trail} was
never
given its own definition of \code{exist}; it just inherits
\code{icon}'s.)
Thus, the instance-variable creation (and other initializing actions) of
{\it
all} the objects that \code{boundary-icon-with-frame} was made from were
taken.
This underscores the need to define \code{exist} functions to call
\code{shadowed-exist}, so that combined objects get the
appropriately-combined
initializations.

\section{Stylistic issues}

This section recommends certain stylistic practices for \OBL{}
programming.

\begin{enumerate}
\item Organize things into abstract functional units.

If there's some coherent task to perform-- like, ``move this icon to
X,Y''--
then {\em define a function} to do the task.  This is always an
important
programming principle, but it is especially important for
object-oriented
programming.  In \OBL, one object's definition of some function (say,
\code{goto-xy}) can be shadowed by a specialized object, which
substitutes its
own definition.  This definition might, say, add some idiosyncracy to
the
function's task, or it might perform the same task by a different
algorithm
than the shadowed version.  The more things you organize into distinct
functional units, the more things you can selectively shadow in
specialized
objects.

\item Don't bind the same symbol for {\em unrelated} purposes in
different
objects.

All function bindings of a given symbol should take the same arguments
and
fulfill the same general purpose.  It's {\em possible} to use the same
symbol
to name two completely unrelated functions in two different objects (if
you
always know which version of the function you want, and which kind of
object
you're talking to).  But this is a confusing practice.  You won't be
able to
tell, just by looking, which version of the function you're invoking
(even
though you knew when you wrote the code).  And it won't be possible to
globally
document the function (because such basic properties as the number of
arguments
might differ in different objects).

As always, use {\em packages} to prevent accidental duplication of the
same
name in different bodies of code.  In addition to the advantages of
clarity
and documentability, this may yield a runtime efficiency gain.

This principle applies to variables, too.  Don't bind the same variable
in
several different objects-- except, of course, for an instance variable,
which
serves the same purpose in each instance it appears in.  Even for an
instance
variable, there should be only one class object that is responsible (via
an
\code{exist} function or a \code{definstancevar}) for creating that
variable.

Since avoiding duplication of object bindings is a matter of clarity and
efficiency (as opposed to being necessary for code to work at all), it
is ok to
be lax about it when writing small, informal, improvised programs.  But
serious
systems should take the principle seriously.

\item Follow the principle of {\em data abstraction}: keep internal
implementation details from being accidentally accessed by users of the
system.

Typically a class object has some set of functions that comprise the
preferred
interface to instances of that class.  That is, there are certain
functions
that a user is expected to call inside that object (and perhaps certain
variables that the user is expected to refer to); these functions (and
variables) are the preferred interface.  Other functions and variables
are
supposed to be {\em internal} to the object-- these are referred to by
the
interface functions, but are not intended to be accessed {\em directly}
by the
user.  Typically, the internal functions and variables are ones that
could
cause the object to be put in an erroneous state, perhaps causing an
error to
be signalled; the interface routines are designed to guarantee
consistency of
the object's state, as long as those routines are the only ones that the
user
calls directly.

At the least, the documentation that goes with an object should say what
functions are part of the preferred interface; none of the object's
other
functions or variables should be referenced by the user.  As a further
precaution, you may wish to {\em enforce} this distinction; this, again,
is a
job for packages.  Simply create a package, and put all the code for an
object
in that package.  All function and variable symbols in that code will be
internal to the package, and thus inaccessible from outside, except for
symbols
explicitly declared {\em external}; these should be the designated
interface
symbols.  (Of course, any user may, by appropriate maneuvering, access
the
internal symbols of a package; but users who do this know that they
proceed at
their own risk.)  Objects and packages can be orthogonal; there might be
several packages, each of which contains some code for each of several
objects.
Hence, what is accessible to whom can be finely tuned.

\item Don't overextend the object-oriented approach.

Object inheritance is appropriate when a number of entities form a
natural {it
specialization} hierarchy, one being a kind of another.  But object
specialization isn't the right way to relate the elements of other kinds
of
hierarchies-- for example, an inclusion hierarchy, where one entity is a
{\it
part of} another (eg, a hand is a part of an arm is a part of a body);
or a
ranking hierarchy (eg president, manager, worker), where one entity is a
subordinate of another.  A hand is not {\em a kind of} arm, and so a
hand
object should not be defined to inherit the attributes of an arm object,
nor
should arm inherit from body.  But hand and arm might be defined as
specializations of a general body-{\em part} object.

\end{enumerate}

\section{Reference}
\label{reference-section}
\subsection{Using \OBL}

\subsubsection{The \code{obj} package}

\OBL's symbols reside in the \code{obj} package.  Names of \OBL{}
primitives,
and some other useful symbols, are external to the \code{obj} package.
To
access any of these symbols, either refer to \code{obj:{\em symbol}}, or
do a
\code{(use-package obj)} in the package from which you wish to make
access.
The \code{user} package already uses the \code{obj} package.  The
external
symbols are:

\begin{verbatim} 
    ask talkto kindof oneof make-obj remake-obj
    defobfun &key* defkind define-kind defclassvar definstancevar
    defclassvars definstancevars instancevar-defs undef-instancevar
    have unhave fhave unfhave
    ask-funcall mapc-ask mapcar-ask map-ask
    object? obj-equal current-obj exist shadowed-exist
    obj-let-globally obj-listener-loop obl
    obj-name class-name print-self
    base-objs inherited-objs
    what show show-all show-vals specializations
    own own? where there? mapc-own mapcar-own own
    fown fown? fwhere fthere? fdoc mapc-fown mapcar-fown
\end{verbatim}

\subsubsection{Toplevel}

\deff{obj-listener-loop}{Function}

\code{obj-listener-loop} runs a special \OBL{} listener loop.  This is
necessary because, in the present implementation, references to object
bindings
only work properly when made textually within an \code{defobfun};
elsewhere,
free references can only access global bindings (see \code{defobfun}).
\code{obj-listener-loop} \code{defobfun}s, and then funcalls, a dummy
function
for each toplevel expression you type, so that your expression can
access
object bindings.

If the current object is other than the global object-- if, for example,
you're
in a break loop dynamically within a \code{ask}; of if, at toplevel,
you've
executed a \code{talkto} for some object (see section
\ref{reference-talkto})--
the \OBL{} listener loop identifies that object as part of the
listener's
prompt.

\deff{obl \{\argd{form}\}*}{Macro}

\code{obl} is used to access object bindings from outside the textual
scope of
an \code{defobfun}.  \code{obl} defines (via \code{defobfun}) and
funcalls a
dummy function whose body consists of the \argd{form}s.

\subsection{Evaluating inside objects}

\deff{ask \argd{obj-form} \{\argd{form}\}*}{Macro}

\argd{obj-form} must evaluate to an object (or \code{nil}, to refer to
the
global object).  The \argd{form}s constitute the body of the \code{ask},
an
implicit progn that is evaluated inside the object that \argd{obj-form}
evaluates to.  That object is said to be the {\em current object} for
the
duration of the evaluation of the \argd{form}s (except, of course, when
another
\code{ask} is invoked during that evaluation, temporarily establishing
another
current object).

\deff{ask-funcall \argd{obj-form symbol} \{\argd{arg-form}\}*}{Macro}

\code{ask-funcall} is useful when you wish to invoke a function inside
some
object, but the arguments to the function need to be evaluated in the
current
object. \argd{obj-form} must evaluate to an object; \argd{symbol} must
be a
symbol.  \argd{arg-forms} are evaluated in the current object.  Then,
\argd{symbol} is \code{fsymeval}'ed inside the specified object, and the
resulting function is applied to the arguments inside the specified
object.

A different technique for calling a function inside some object, but
with the
arguments evaluated in the current environment, is to lambda-bind some
variables to the values, then refer to those variables in the body of
the
\code{ask}.  This works because object scoping only captures free
references.
See section \ref{obj-vs-lex}, Object Binding vs Lexical Binding.

\deff{mapc-ask \argd{objlist-form} \{\argd{form}\}*}{Macro}

\argd{objlist-form} must evaluate to a list of objects.  A \code{ask} is
done
to each in turn, using the \argd{form}s as the body.  The list of
objects is
returned.

\deff{mapcar-ask \argd{objlist-form} \{\argd{form}\}*}{Macro}

\argd{objlist-form} must evaluate to a list of objects.  A \code{ask} is
done
to each in turn, using the \argd{form}s as the body.  A list of the
resulting
values is returned.

\label{reference-talkto}
\deff{talkto \&optional \argd{object}}{Function}

\argd{object} must be an object (or \code{nil}, to refer to the global
object.)
\code{object} becomes the current object.  \code{talkto} with no
argument (or
with \code{nil} as its argument) sets the current object to the global
object.

\code{talkto} is to \code{ask} as \code{setq} is to special-variable
binding.

\code{talkto} should only be used interactively, at listener level.
\code{talkto} puts you inside an object, allowing you to get or set its
variables' values (or call its functions) just as though you were making
global
references.  The object listener loop's prompt indicates what the
current
object is, if it is other than the global object.

\subsection{Creating objects}

\deff{kindof \&rest \argd{objects}}{Function}

\code{kindof} creates and returns a new object.  The \argd{objects} must
all
be objects.  If no arguments are passed, \code{kindof} creates a bare
object
that inherits only from the global object.  If one argument is passed,
the new
object is a specialization of that object.  If several arguments are
passed,
the new object is a specialization of all the \argd{objects} (see
section~\ref{multiple-inherit}).

More precisely, \code{kindof} creates and returns an object whose
binding
frames, innermost to outermost are: a new frame, which will contain the
new
object's own bindings; the frames of the first \argd{objects} argument;
the
frames of the next \argd{objects} argument; and so on.  (The arguments
must
all be objects.)  If any frame appears more than once, duplicate
appearances
are deleted, leaving only the outermost occurrence.  The global frame
(containing the ordinary \LISP{} global values and definitions for all
symbols) is implicitly the outermost frame of every object.  See
section~\ref{multiple-inherit} for elaboration.

\deff{make-obj \&rest \argd{objects}}{Function}

\code{make-obj} is a synonym of \code{kindof}.

\deff{remake-obj \argd{object} \&rest \argd{objects}}{Function}

\code{remake-obj} is used to alter an existing object's base objects.
\argd{object} is altered so that its base objects are \argd{objects},
all of
which must be objects.  The change propagates transitively to
specializations
of \argd{object}.  The new object has the same innermost binding frame
as the
original, so the original's own bindings are preserved.

Suppose there is a form in your file that says \code{(defvar obj3
(kindof
obj2))}, followed by \code{defobfun}s of many functions for \code{obj3}.
If
you were to re-execute the \code{kindof}-- either with the same base
object, or
with different one(s)-- then the functions you had defined for the
object
previously bound to \code{obj3} would not be defined for the new object
bound
to \code{obj3}.  And any specializations of the old \code{obj3} would
still
just be specializations of the old \code{obj3}, oblivious to any
differences
in the new one.  Using \code{remake-obj} solves these problems.
Usually,
\code{remake-obj} is called via \code{defkind}, which is described just
below.

\label{reference-oneof}
\deff{oneof \argd{class} \&rest \argd{keys}}{Function}

\code{oneof} is used to create a new object that is intended to be an
instance
of {\em class}, which must be an object.  \code{oneof} creates a
\code{kindof}
{\em class}, then calls the function \code{exist} inside the new object.
{\it
keys} are passed as arguments to \code{exist}.  The new object is
returned.

\deff{exist \&rest \argd{keys} \&key* \argd{obj-name}}{Function}

The global \code{exist} function recognizes the keyword \code{obj-name};
if
that keyword is supplied, the current object is given a binding of
\code{obj-name} to the argument provided.  An object's binding of {\it
obj-name} helps control the object's printed representation (see
section~\ref{obj-prep}).  \code{exist} also creates bindings of instance
variables declared by \code{definstancevar}, documented in the following
section.

\label{reference-defkind}
\deff{defkind \argd{name} \{\argd{base-class-symbol}\}*}{Macro}

\code{defkind} is used to make an object intended to be a class object.
{\it
name} and \argd{base-class-symbol}s must be symbols; and each of the
\argd{base-class-symbol}s symbols must be bound to an object.
\code{defkind}
creates an object that is a specialization of the base class objects.
In
addition, \code{defkind} takes some auxiliary actions that are useful
for class
objects:

\begin{itemize}
\item The global symbol \argd{name} is \code{defvar}'ed to be the new
class
object.
\item Crucially, if \argd{name} is already bound to an object,
\code{defkind}
creates the new object via \code{remake-obj} (see just above),
preserving the
original object's bindings, and propagating the altered base objects to
any
extant specializations of the original object.  If \argd{name} is not
bound to
an object, \code{make-obj} is used instead.
\item \argd{name}'s source file is recorded.
\item The symbol \code{class-name} is bound to \argd{name} in the new
class
object; \code{class-name} helps control an object's printed
representation (see
section~ref{obj-prep}).
\end{itemize}

\code{defkind} is for use at top level in a file (or from a listener);
it
should not be called from within a function.

% !!! cref examples next section

\subsection{Creating and deleting bindings}

\deff{have \argd{symbol} \&rest \argd{sym-val-pairs}}{Function}

\argd{sym-val-pairs} must be a list of alternating symbols and values.
For
each symbol, \code{have} gives the current object its own variable
binding of
the symbol to the corresponding value. (The last symbol's value may be
omitted,
and defaults to \code{nil}.)

\deff{unhave \argd{symbol}}{Function}

\code{unhave} deletes the current object's own variable binding (if any)
of the
symbol {\em symbol}.

\deff{fhave \argd{symbol} \&rest \argd{sym-fcn-pairs}}{Function}

\argd{sym-val-pairs} must be a list of alternating symbols and
functions.  For
each symbol, \code{have} gives the current object its own function
binding of
the symbol to the corresponding function.  (The last symbol's function
may {\it
not} be omitted, since there is no reasonable default.)

\code{fhave} signals an error if \argd{symbol} is {\em unshadowable};
see the
end of section~\ref{reference-defobfun}.

\deff{unfhave \argd{symbol}}{Function}

Deletes the current object's own function binding (if any) of the symbol
{\it
symbol}.

\deff{defclassvar (\argd{class-sym classvar})
\{\argd{init-form}\}}{Macro}

\code{defclassvar} makes a binding of the symbol \argd{classvar} for the
object
that is the value of the symbol \argd{class-sym}.  Its value is
initialized to
the value of \argd{init-form}, if that form is supplied, else
\code{nil.}
\argd{defclassvar} also declares \argd{classvar} to be a special
variable
(which is appropriate because it will be freely-- ie nonlexically--
referenced), and records the source  where it was defined.

\deff{definstancevar (\argd{class-sym instancevar})
\{\argd{init-form}\}}
 {Macro}

\code{definstancevar} is used to establish an instance variable, the
symbol
\argd{instancevar}, for all instances of the object that is the value of
the
symbol \code{class-sym}.  This is a little more complicated than
establishing a
class variable, since the instance objects which are to bind
\code{instancevar}
haven't (necessarily) even been created yet.  \code{definstancevar}
associates
the variable \argd{instancevar} (along with \argd{init-form}, if
supplied) with
the designated class object.  The global \code{exist} function finds all
such
variables for the base objects of the object being told to exist.  That
object
is given its own binding of each such variable, and (unless that binding
already existed) the associated \argd{init-form} is evaluated, providing
the
value to bind the variable to.  This is done from innermost to outermost
base
object; within a base object, the order is that in which the instance
variables
were declared.
% !!! this shd really refer to inherited rather than base objs, but the
concept
%     isn't defined yet.

Like \code{defclassvar}, \code{definstancevar} declares
\argd{instancevar}
special and records the source file of its definition.

% !!! ? instancevar-defs ?

\deff{undef-instancevar \argd{symbol object}}{Function}

\code{undef-instancevar} undoes the effect of any previous
\code{definstancevar} of the symbol \argd{symbol} for the object
\argd{object}.

\deff{defclassvars \argd{obj-sym} \{\argd{var-init}\}*}{Macro}

\code{defclassvars} is used to declare multiple class variables for the
same
object, the object which is the value of the symbol \argd{obj-sym}.
Each
\argd{var-init} is either a symbol (which becomes a class varaible
initialized
to \code{nil}), or a list of two elements: the symbol to be bound, and
the
form which is evaluated to give its initial value.

\deff{definstancevars \argd{obj-sym} \{\argd{var-init}\}*}{Macro}

\code{definstancevars}is used to declare multiple instance variables for
the
same object.  \code{definstancevars} is to \code{definstancevar} as
\code{defclassvars} is to \code{defclassvar}.

% !!! example

\subsection{DEFOBFUN} \mbox{}
\label{reference-defobfun}

\deff{defobfun \argd{(function-name object-name) arglist}
\{\argd{form}\}*}
 {-or-}

\deff{defobfun \argd{function-name arglist} \{\argd{form}\}*}{Macro}

\code{defobfun}, like \code{defun}, defines a function with
\argd{arglist} as
its arglist and \argd{body} as its body.

\argd{function-name} and \argd{object-name} (if \argd{object-name} is
supplied)
must be symbols; \argd{object-name} must evaluate to an object.  If
\argd{object-name} is supplied, the specified object is given its own
function-
inding of \argd{function-name} to the defined function.  If
\argd{object-name}
is not supplied, the function is defined globally (this is not quite the
same
as using \code{defun}, because of the following implementation quirk).

 \begin{quote} In the present implementation, object bindings are only
accessible for symbols referenced textually within an \code{defobfun}.
Thus,
if you intend a global function to be called inside any object, and to
refer to
variables or functions bound in that object, you must define that global
function using \code{defobfun} rather than \code{defun.} If \code{defun}
is
used, only the global values and definitions of freely-referenced
symbols will
be accessed; object bindings will be circumvented.  This temporary
implementation restriction should {\em not} be used deliberately to
bypass
object bindings; \code{defun} should be used only for functions that are
expected never to refer to values or functions that are have object
bindings.
To deliberately circumvent object bindings, use \code{(ask nil ...)}.

A related quirk is that \code{defobfun}, unlike \code{defun}, always
{\it
compiles} the function it defines.  This is because the lookup mechanism
for
object bindings works by intercepting free references in the compiler;
thus,
references to object bindings only work from compiled code.  This will
be
changed in a future release.
 \end{quote}

Textually within a \code{defobfun} of \argd{function-name}, calling
\code{shadowed-}\argd{function-name} invokes the shadowed version of
\argd{function-name}-- the version that would be referenced by the
symbol
\argd{function-name}, had not this very \code{defobfun} provided a
shadowing
definition.  If no shadowed binding exists, calling
\code{shadowed-}\argd{function-name} just returns \code{nil}.

\code{defobfun} recognizes an extra lambda-list keyword, \code{\&key*}.
With
this variant of \code{\&key}, the default keyword symbol for each
keyword
argument is the same as the parameter symbol, rather than being a symbol
in the
keyword package.  Also, \code{\&allow-other-keys} is implicitly declared
by
\code{\&key*}.  Section~\ref{key-explanation} explains the rationale for
this.

For reasons of efficiency, all symbols in the global package (part of
the
package system, not to be confused with the global object), as well as
all
symbols from certain internal system packages, are {\em unshadowable}--
they
cannot be shadowed by function bindings.  Hence, \code{defobfun} and
\code{fhave} signal an error if an attempt is made to function-bind such
a
symbol (except globally).  (If you are not familiar with the package
system,
all this just means that you are not allowed to shadow the definitions
of
\LISP{} system primitives.)

\subsection{Inspecting objects}

\deff{current-obj}{Function}

\code{current-obj} returns the current object-- that is, returns the
{\it
object} argument from the dynamically-innermost \code{ask} (or last
\code{talkto}).  For example, \code{(ask \argd{obj} (current-obj))}
always
returns \argd{obj}.

\deff{print-self}{Function}

Prints the printed representation of the current object.  This is always
called
to produce the printed representation of an object; hence, an object's
printed
representation can be altered by giving the object an shadowing
definition of
\code{print-self}.

\label{obj-prep}

What \code{print-self} prints is governed by the current object's
variable
bindings of the symbols \code{obj-name} and \code{class-name}.  If the
object
has its own binding of \code{class-name}, then the printed
representation is
\code{\#<The generic \argd{class} \argd{id}>}, where \argd{class} is the
printed representation of the value of \code{class-name}, and \argd{id}
is a
unique internal number.  Otherwise, if the object has its own binding of
\code{obj-name}, then if it inherits a binding of \code{class-name,} the
printed representation is \code{\#<\argd{name}, a \argd{class}
\argd{id}>}.  If
the object has its own binding of \code{obj-name}, but no binding (own
or
inherited) of \code{class-name}, the printed representation is
\code{\#<\argd{name}, no class \argd{id}>}.  If the object does not have
its
own binding of \code{obj-name} or \code{class-name}, it prints as
\code{\#<Object \argd{id}>}.

\bigskip

For the following functions, the optional argument \argd{object}
defaults to
the current object; also, \code{nil} can be specified to refer to the
global
object.

\deff{obj:what \&optional \argd{object}}{Function}

\code{what} prints the base object(s) from which \argd{object} was made.

\deff{obj:show \&optional \argd{object}}{Function}

\code{show} prints the values and functions for which \argd{object} has
its
own bindings.

\deff{obj:show-all \&optional \argd{object}}{Function}

\code{show-all} prints the values and functions for which \argd{object}
has
its own or inherited bindings (except for global bindings).

\deff{obj:show-vals \&optional \argd{object}}{Function}

\code{show-vals} prints the symbols for which \argd{object} has its own
variable bindings, together with their values.

\deff{obj:own \&optional \argd{object}}{Function}

\code{own} returns a list of all symbols for which \argd{object} has its
own
variable bindings.

\deff{obj:own? \argd{symbol} \&optional \argd{object}}{Function}

\code{own?} returns \code{t} or \code{nil} according to whether
\argd{object}
has its own variable binding of the symbol \argd{symbol}.

\deff{obj:there? \argd{symbol} \&optional \argd{object}}{Function}

\code{there?} Returns \code{t} or \code{nil} according to whether
\argd{object}
has a variable binding (its own or inherited) of the symbol
\argd{symbol}.

\deff{obj:where \argd{symbol} \&optional \argd{object}}{Function}

\code{where} returns the object (if any) from which {\em object}
inherits its
binding of the symbol \code{symbol} (or returns \argd{object} itself if
\argd{object} has its own variable binding of \argd{symbol}.)
\code{nil} is
returned if there is no such object, or if it is the global object.

\deff{obj:mapc-own \argd{function} \&optional \argd{object}}{Function}

\code{mapc-own} \code{mapc}'s \argd{function} over the symbols for which
\argd{object} has its own variable bindings.

\deff{obj:mapcar-own \argd{function} \&optional \argd{object}}{Function}

\code{mapcar-own} \code{mapcar}'s \argd{function} over the symbols for
which
\argd{object} has its own variable bindings.

\deff{obj:fown \&optional \argd{object}}{Function}

\code{fown} returns a list of all symbols for which \argd{object} has
its own
function bindings.

\deff{obj:fown? \argd{symbol} \&optional \argd{object}}{Function}

\code{fown?} returns \code{t} or \code{nil} according to whether
\argd{object}
has its own function binding of the symbol \argd{symbol}.

\deff{obj:fthere? \argd{symbol} \&optional \argd{object}}{Function}

\code{fthere?} Returns \code{t} or \code{nil} according to whether
\argd{object} has a function binding (its own or inherited) of the
symbol
\argd{symbol}.

\deff{obj:fwhere \argd{symbol} \&optional \argd{object}}{Function}

\code{fwhere} returns a list of those objects, among \argd{object} and
the
objects that \argd{object} inherits from, that have their own function
bindings
for \argd{symbol}.  The list is from innermost (most-specialized) to
outermost.
Note that \code{where} returns a single object, while \code{fwhere}
returns a
list of objects.  This is because only the single innermost binding of a
variable is accessible from an object; whereas, for a function, {\em
all} base
objects' bindings may be accessed if successive calls to the
\code{shadowed-}
versions are made.

\deff{obj:fdoc \argd{symbol} \&optional \argd{object}}{Function}

\code{fdoc} is used to locate any definition(s) of the symbol
\argd{symbol} in
the object \argd{object}. \code{fdoc} looks at \argd{object} itself, and
all
objects from which it inherits, and indicates which of those objects (if
any)
have their own function bindings of \argd{symbol}.

\deff{obj:mapc-fown \argd{function} \&optional \argd{object}}{Function}

\code{mapc-fown} \code{mapc}'s \argd{function} over the symbols for
which
\argd{object} has its own function bindings.

\deff{obj:mapcar-fown \argd{function} \&optional
\argd{object}}{Function}

\code{mapcar-fown} \code{mapcar}'s \argd{function} over the symbols for
which
\argd{object} has its own function bindings.

\deff{base-objs \&optional \argd{object}}{Function}

\code{base-objs} returns a list of \argd{object}'s base objects.

\deff{inherited-objs \&optional \argd{object}}{Function}

\code{inherited-objs} returns a list of the objects that \argd{object}
inherits
 from.  These include not only \argd{object}'s base objects, but also
{\it
their} base objects, and so on.  More precisely, for each binding frame
in
\argd{object}, innermost to outermost, excluding \argd{object}'s own
frame, the
object whose own bindings are held in that frame appears (in that order)
in the
list returned by \code{inherited-objs}.

\deff{specializations \&optional \argd{object}}{Function}

\code{specializations} returns a list of the objects that inherit from
\argd{object} (unless \code{object} is \code{nil}, signifying the global
object, in which case \code{specializations} returns \code{nil}).

\deff{obj-equal \argd{object1 object2}}{Function}

\code{obj-equal} returns \code{t} or \code{nil} according to whether
\argd{object1} and \argd{object2} have the same binding frames (and in
the same
order) as one another.

\deff{object? \argd{thing}}{Function}

\code{object?} returns \code{t} or \code{nil} according to whether
\argd{thing}
is an \OBL{} object.

\end{document}


     ----- End Forwarded Messages -----