% extwords.tex
% David.N.Williams@umich.edu
% Last revision:  July 13, 2000

\section{Overview of structure extension words}\label{extwords}

As in the previous section, we given only a functional overview here,
without stack effects.  Details can be found in {\tt cstruct.fs}.

\subsection{Structure Extension word set}
\begin{alltt}
  \verb|{  }#|
  \verb|{}structof  {}structof/|
  \verb|structof{}  }&  }&/|
  ]&  ]&/  ]@  ]!  ]c@  ]c!  ]2@  ]2!  ]execute
\end{alltt}

\subsection{Description}

The words \verb|{| and \verb|}#| simply count the number of parameter
stack elements between them, and could be of general utility.%
\footnote{We think that words like {\tt \{} should be declared
officially to have at-will meanings.}
Although we indicate at the end of this section how \verb|}#| can be
used explicitly for early binding of field offsets, we use it mainly
as an implementation factor in the {\tt DOES>} part of the structure
instance defining words \verb|{}structof|, \verb|{}structof/|, and
\verb|struct{}|.  The first two are for left field syntax words, and
the third is for right field syntax.  (The same three words are used
to define union instances.)

To illustrate, we continue with our translation of Peters' example. 
In the \verb|{}structof| variant, we create an instance of the
structure {\tt pt.struct} with name \verb|}patient| like this:
\begin{alltt}
      pt.struct \verb|{}structof }patient|
\end{alltt}

To retrieve the address of the {\tt first} field in the {\tt name}
substructure in the structure instance \verb|}patient|, we would say:

\begin{alltt}
      \verb|{ first name }patient|
\end{alltt}
The address of the {\tt name} substructure is returned by
\begin{alltt}
      \verb|{ name }patient|
\end{alltt}
and that of the \verb|}patient| structure data (i.e., the \sda) by
\begin{alltt}
      \verb|{ }patient|
\end{alltt}

A right field variant would be
\begin{alltt}
      pt.struct \verb|structof{} patient{|
\end{alltt}

In the left field variant the structure word \verb|}patient| does the
address calculation.  In the right field variant we use an explicit
field closing operator to do that, a variation on Julian Noble's array
syntax \cite{jnoble:92}, with which it fortunately does not conflict:
\begin{alltt}
      \verb|patient{ name first }&|
\end{alltt}
The addresses of the {\tt name} field and the \verb|patient{|
structure pointer would be given by:
\begin{alltt}
      \verb|patient{ name }&|
      \verb|patient{ }&|
\end{alltt}

The left syntax example in the file {\tt examples.fs} actually uses
the defining word \verb|{}structof/|, which builds instances that
leave the field size as well as the address.  This is very much like
Peters' word {\tt new.struct}, the effective differences being that
{\tt new.struct} does not require an opening \verb|{| for the \id
list of an instance it creates, and that its \id lists have to
resolve all the way to a primitive field.

The right syntax example in {\tt examples.fs} gets the same effect by
using the closing word \verb|}&/| with a structure instance
\verb|patient{| defined using \verb|structof{}|.

The words beginning with {\tt ]} are the closing words for early
binding mentioned in Section~\ref{intro}.  Here is a sample phrase
that could be used in a word definition to compile the address of the
{\tt last name} field of the \verb|}patient| structure instance as a
literal:
\begin{alltt}
      \verb|[ { last name }patient ]&|
\end{alltt}
These words all start by switching to compilation mode, where they
compile a simple action based on a computation stacked from
interpretation mode.  They are best understood directly from the
implementation in the file {\tt cstruct.fs}, and from the examples in
{\tt examples.fs}.

In version~1.0 of this word list, we included early-binding words for
structure field offsets, for example, {\tt ]o}.  We left them out of
this version because they are redundant, and because the offsets are
most often wanted for computing addresses, which is already covered. 
The same effect can be achieved by using a structure type word with
{\tt >sfo} or \verb|>sfo&type| between {\tt [} and {\tt ]}.  For
example, to compile the offset of the {\tt last name} field from the
\sda of \verb|}patient| into a word definition, we would use the
structure type directly in the phrase:
\begin{alltt}
      \verb|[ { last name }# pt.struct >sfo ] literal|
\end{alltt}
To compile the offset of the {\tt name} substructure, we would use:
\begin{alltt}
      \verb|[ { name }# pt.struct >sfo ] literal|
\end{alltt}
The syntax \verb|{| \ldots \verb|}#| can be eliminated by giving the
number of \id's explicitly:
\begin{alltt}
      \verb|[ last name 2 pt.struct >sfo ] literal|
\end{alltt}
and
\begin{alltt}
      \verb|[ name 1 pt.struct >sfo ] literal|
\end{alltt}

\clearemptydoublepage