X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/5074c9e679e605f36e4d7946fcc7dfa5594c2bc7..8a7afc76fd5f929de335cf318741e3489d6c6107:/doc/concepts.tex

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 21951dd..39dfd2e 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -63,22 +63,33 @@ having to implement additional syntax.
 For the most part, Sod takes a fairly traditional view of what it means to be
 an object system.
 
-An \emph{object} maintains \emph{state} and exhibits \emph{behaviour}.  An
-object's state is maintained in named \emph{slots}, each of which can store a
-C value of an appropriate (scalar or aggregate) type.  An object's behaviour
-is stimulated by sending it \emph{messages}.  A message has a name, and may
-carry a number of arguments, which are C values; sending a message may result
-in the state of receiving object (or other objects) being changed, and a C
-value being returned to the sender.
-
-Every object is a (direct) instance of some \emph{class}.  The class
-determines which slots its instances have, which messages its instances can
-be sent, and which methods are invoked when those messages are received.  The
-Sod translator's main job is to read class definitions and convert them into
-appropriate C declarations, tables, and functions.  An object cannot
+An \emph{object} maintains \emph{state} and exhibits \emph{behaviour}.
+(Here, we're using the term `object' in the usual sense of `object-oriented
+programming', rather than that of the ISO~C standard.  Once we have defined
+an `instance' below, we shall generally prefer that term, so as to prevent
+further confusion between these two uses of the word.)
+
+An object's state is maintained in named \emph{slots}, each of which can
+store a C value of an appropriate (scalar or aggregate) type.  An object's
+behaviour is stimulated by sending it \emph{messages}.  A message has a name,
+and may carry a number of arguments, which are C values; sending a message
+may result in the state of receiving object (or other objects) being changed,
+and a C value being returned to the sender.
+
+Every object is a \emph{direct instance} of exactly one \emph{class}.  The
+class determines which slots its instances have, which messages its instances
+can be sent, and which methods are invoked when those messages are received.
+The Sod translator's main job is to read class definitions and convert them
+into appropriate C declarations, tables, and functions.  An object cannot
 (usually) change its direct class, and the direct class of an object is not
 affected by, for example, the static type of a pointer to it.
 
+If an object~$x$ is a direct instance of some class~$C$, then we say that $C$
+is \emph{the class of}~$x$.  Note that the class of an object is a property
+of the object's value at runtime, and not of C's compile-time type system.
+We shall be careful in distinguishing C's compile-time notion of \emph{type}
+from Sod's run-time notion of \emph{class}.
+
 
 \subsection{Superclasses and inheritance}
 \label{sec:concepts.classes.inherit}
@@ -120,7 +131,7 @@ class then the only superclass of $C$ is $C$ itself, and $C$ has no proper
 superclasses.
 
 If an object is a direct instance of class~$C$ then the object is also an
-(indirect) instance of every superclass of $C$.
+(indirect) \emph{instance} of every superclass of $C$.
 
 If $C$ has a proper superclass $B$, then $B$ must not have $C$ as a direct
 superclass.  In different terms, if we construct a directed graph, whose
@@ -334,6 +345,9 @@ details.
 
 \subsection{C language integration} \label{sec:concepts.classes.c}
 
+It is very important to distinguish compile-time C \emph{types} from Sod's
+run-time \emph{classes}: see \xref{sec:concepts.classes}.
+
 For each class~$C$, the Sod translator defines a C type, the \emph{class
 type}, with the same name.  This is the usual type used when considering an
 object as an instance of class~$C$.  No entire object will normally have a
@@ -343,6 +357,10 @@ class type,\footnote{%
   chains.  See \xref{sec:structures.layout} for the full details.} %
 so access to instances is almost always via pointers.
 
+Usually, a value of type pointer-to-class-type of class~$C$ will point into
+an instance of class $C$.  However, clever (or foolish) use of pointer
+conversions can invalidate this relationship.
+
 \subsubsection{Access to slots}
 The class type for a class~$C$ is actually a structure.  It contains one
 member for each class in $C$'s superclass chain, named with that class's
@@ -370,6 +388,11 @@ to it in a slot.  (This will also help preserve binary compatibility, because
 the private structure can grow more members as needed.  See
 \xref{sec:concepts.compatibility} for more details.)
 
+Slots defined by $C$'s link superclass, or any other superclass in the same
+chain, can be accessed in the same way.  Slots defined by other superclasses
+can't be accessed directly: the instance pointer must be \emph{converted} to
+point to a different chain.  See the subsection `Conversions' below.
+
 
 \subsubsection{Sending messages}
 Sod defines a macro for each message.  If a class $C$ defines a message $m$,
@@ -857,11 +880,10 @@ While method combinations may set their own rules, usually keyword methods
 can only be defined on keyword messages, and all methods defined on a keyword
 message must be keyword methods.  The direct methods defined on a keyword
 message may differ in the keywords they accept, both from each other, and
-from the message.  If two superclasses of some common class both define
-keyword methods on the same message, and the methods both accept a keyword
-argument with the same name, then these two keyword arguments must also have
-the same type.  Different applicable methods may declare keyword arguments
-with the same name but different defaults; see below.
+from the message.  If two applicable methods on the same message both accept
+a keyword argument with the same name, then these two keyword arguments must
+also have the same type.  Different applicable methods may declare keyword
+arguments with the same name but different defaults; see below.
 
 The keyword arguments acceptable in a message sent to an object are the
 keywords listed in the message definition, together with all of the keywords