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}
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
the \emph{chain tail}. Chains are often named after their chain head
classes.
+
\subsection{Names}
\label{sec:concepts.classes.names}
\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
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
corresponding class's slots, one member per slot. There's nothing special
about these slot members: C code can access them in the usual way.
-For example, if @|MyClass| has the nickname @|mine|, and defines a slot @|x|
-of type @|int|, then the simple function
+For example, given the definition
+\begin{prog}
+ [nick = mine] \\
+ class MyClass: SodObject \{ \\ \ind
+ int x; \-\\
+ \}
+\end{prog}
+the simple function
\begin{prog}
int get_x(MyClass *m) \{ return (m@->mine.x); \}
\end{prog}
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$,
\subsection{Method entries} \label{sec:concepts.methods.entry}
-Each instance is associated with its direct class \fixme{direct instances}
-
The effective methods for each class are determined at translation time, by
the Sod translator. For each effective method, one or more \emph{method
entry functions} are constructed. A method entry function has three
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
~mdw / sod / blobdiff