\documentstyle[11pt,clu2tex,simplemargins]{article}
\setallmargins{1.5in}
\begin{document}

\begin{titlepage}
\vspace*{2in}
{\LARGE CromChex}

\vspace*{.5in}
{\Large Human Resources and the Main Loop}

\vspace*{2in}
{\Large Juliet C.\ Bourne}

\vspace*{1in}
{\large \today}

\vspace*{1in}
Revised for submission for Phase Two of the Writing Requirement
\end{titlepage}

\tableofcontents
\newpage

\section{Introduction}

Cromwell's checkers is a simple variant of checkers which does not allow
``king''-ing. CromChex is a program written in Clu which implements
Cromwell's checkers so that a user can play against the computer.
During the design phase, CromChex was broken into three sections: Game,
Utilities, and Human Resources. The Game section deals with the rules
and strategy of the game, such as checking the legality of moves and
computing the computer's next move. The Utilities section provides data
abstractions such as \verb+simplescreen+, \verb+board+, and other
general abstractions that make designing and coding the other two
sections simpler.

The Human Resources section of CromChex includes parsing the input from the
user, giving error messages when appropriate, and executing the commands
given in the input.  Two data abstractions were found to be useful:
\verb+input_obj+ and \verb+window_obj+. These allow easy display and
manipulation of text on a certain section of a screen. (These
abstractions are described in sections 2 and 3, respectively.) Input
parsing and command execution are contained in top-level procedures,
which comprise the \verb+Command+ module described in section 5. Section
4 describes the \verb+Help+ module which contain top-level procedures
that provide helpful information about the commands available in
CromChex.  Finally, section 6 describes the \verb+Main Loop+ which
integrates all of these parts, as well as the parts from the Game and
Utilities sections, into the final product: CromChex.

\section{The Input Cluster}

\subsection{Design Overview}

The \verb+input_obj+ data abstraction was created to represent the input
line of the CromChex game where the user types in commands. It has a
very simple line-editing capabilities: adding and deleting characters.
It does not allow the use of arrow keys, which would complicate the
implementation of \verb+input_obj+ considerably. The {\em input object}
has associated with a \verb+simplescreen+ and a certain area on it which
is where the text of the input line is displayed and manipulated.

\subsection{Specifications}

The abstract model for a {\em input object} is a buffer, with a fixed
maximum length and a fixed position on a screen, which stores what is
currently on the input line represented by the {\em input object}.
Following are the specifications for the \verb+input_obj+ cluster:

\input{inputspc.tex}

\subsection{Implementation Overview}

The representation for an {\em input object} is a record object which
consists of an array of characters for the buffer, a \verb+simplescreen+
object, three integers representing the starting row and column and the
width of the input line, and a string for the prompt to be displayed on
the input line. So, the Clu representation looks like:

\vspace*{-.1in}
\begin{verbatim}
ss = simplescreen, ac = array[char]
rep = record[buffer: ac, scr: ss, row, col, width: int, 
             prompt: string]
\end{verbatim}

The abstraction function maps a set of these record elements
into an {\em input object}. The representation invariant shows the
restrictions on the values of the elements in order for such a record
object to represent valid a {\em input object}. 

\vspace*{.1in}
\noindent Abstraction function:

\noindent $A(i) = \forall j \, | \, 0 \leq j \leq$ac\$size(\verb+buffer+) :

(\verb+row+, \verb+col+ + string\$size(\verb+prompt+) + j) on the screen is
i[ac\$low(\verb+buffer+) + j]

\vspace*{.1in}
\noindent Rep invariant:

exists position [\verb+row+,\verb+col+] on \verb+scr+

\& \verb+col+ + \verb+width+ + string\$size(\verb+prompt+) $<$ 
ss\$get\_width(\verb+scr+)

\& ac\$size(\verb+buffer+) $<$ \verb+width+ - string\$length(\verb+prompt+)

\subsection{Validation Strategy}

The strategy for testing the implementation of the \verb+input_obj+
cluster was to do both black-box and glass-box testing using {\em
xfiles}. All possible signals and paths in the code were generated and
saved. For loops, all possible paths were reduced to the special cases
of zero and one passes through the loop as well as a generalized
``many'' passes through the loop. Since an {\em input object} is really
part of a screen, some of the tests had to be manually watched since the
output couldn't be written to a file.

\section{The Window Cluster}

\subsection{Design Overview}

At first, the \verb+window_obj+ data abstraction was two abstractions,
the \verb+help_obj+ and \verb+error_obj+ abstractions. The original idea
was that a {\em help object} would represent the help area of the screen
for CromChex, and an {\em error object} would represent the error area.
The Help Cluster was to contain the data abstraction for an object that
would print out the appropriate text for the various commands in
CromChex. However, it was decided that those procedures should not be
put in a data abstraction as such since they are specific to CromChex.
So, they were broken out into a separate module (see section 4).

Now the \verb+help_obj+ and \verb+error_obj+ abstractions were the same,
with the same concepts and operations available. Thus, they were
collapsed into the single abstraction \verb+window_obj+. A {\em window
object} represents an area of a screen to which text can be written.
The procedure to display text in the boxed area represented by the {\em
window object} was the most difficult to implement since it involved
breaking arbitrary strings into strings that would fit. Other procedures
involved the simple manipulation of what was displayed on the screen.

\subsection{Specifications}

The abstract model for a {\em window object} is a buffer which holds
what is currently being displayed on the area of the screen represented
by the {\em window object}.

\vspace*{.1in}
\input{windowspc.tex}

\subsection{Implementation Overview}

The representation for a {\em window object} is a record object which
consists of an array of strings for the \verb+on_screen+ buffer, a
\verb+simplescreen+ object, and four integers representing the starting row
and column of the window as well as its width and height.  So, the Clu
representation looks like:

\begin{verbatim}
ss = simplescreen
as = array[string]
rep = record[on_screen: as, scr: ss, row, col, width, height: int]
\end{verbatim}

The abstraction function maps a set of record elements into a {\em
window object}. There are certain restrictions on the values these
record elements can take in order to comprise a valid {\em window
object} and these restrictions are seen in the representation invariant.

\vspace*{.1in}
\noindent Abstraction function:

\noindent $A(h) = $

$\forall i$: $0 \leq i \leq$ as\$high(\verb+h.on_screen+) - 
as\$low(\verb+h.on_screen+)

$\forall j$: as\$low(\verb+h.on_screen+) $\leq j \leq$ 
as\$high(\verb+h.on_screen+)

(\verb+row+$+ i$,\verb+col+) through (\verb+row+$+ i$,\verb-col + width-) on
the screen is \verb+h.on_screen+$[j]$ 

\vspace*{.1in}
\noindent Rep invariant:

exists position [\verb+row+,\verb+col+] on \verb+scr+

\& \verb+col+ + \verb+width+ $<$ ss\$get\_width(\verb+scr+)

\& \verb+row+ + \verb+height+ $<$ ss\$get\_height(\verb+scr+)

\& as\$size(\verb+on_screen+) $\leq$ \verb+height+

\& $\forall i$ :  as\$low(\verb+on_screen+) $\leq i \leq$ 
as\$high(\verb+on_screen+)

$\,\,\,\,\,\,$ string\$size(\verb+on_screen+$[i]$) $\leq$ \verb+width+ 

\vspace*{.1in}
The most interesting algorithm in the implementation of the
\verb+window_obj+ was the one to break an arbitrary length string
between words (i.e. where there is whitespace) into an array of strings
which are less than a given length $n$.  Also, \verb+\n+ can indicate a
forced line break in the middle of the string. Basically, the algorithm
scans the string character by character, keeping track of how many
characters ($i$) it has scanned and where it started scanning ($p$) for
the current line in the buffer. If the character scanned is
\verb+\n+, whatever has been scanned up until that point is put into the
current line of the buffer and the markers $i$ and $p$ are set to be
position of the character after the \verb+\n+.  Otherwise, if the
maximum number of characters ($n$) have been scanned, and the current
character isn't a space, then the algorithm backpedals looking for the
last space scanned. (If the current character is a space, then the
algorithm simply puts all of the characters scanned since $p$ into the
current line of the buffer and resets the markers.) If it doesn't find a
space in the scanned characters then it rejects the string, because
there is a word of with length greater than $n$.

\subsection{Validation Strategy}

The strategy for testing the \verb+window_obj+ cluster was similar to
testing the \verb+input_obj+ cluster, since they are so similar. Both
black-box and glass-box testing was done using {\em xfiles}. Again, all
possible signals and paths in the code were generated and saved and
zero, one, and many passes were tested for loops. Also, manual checking
of the results of tests was necessary since a {\em window object}
involves displaying text on a screen.

\section{The Help Module}

\subsection{Design Overview}

Originally the Help Module was the \verb+help_obj+ cluster. However, it
was decided to separate the object representing the area of the screen
where help messages would be displayed and the actual text to be
displayed (see section 2).  So the Help Module consists of procedures
for each of the available commands in CromChex. They all take a {\em
window object} as an argument and display the appropriate text on the
screen using that {\em window object}.

\subsection{Specifications}

There is no abstract model for this module; it is merely a collection of
procedures. All the specifications look like the following, with one of
these substituted for {\em command}: general (for general help), move,
advise, time, new, load, save, difficulty, undo, help.

\vspace*{.1in}
\codebegin{0}{help\_{\em command} = {\bf proc}(help: window\_obj) {\bf signals}
(not\_possible)}\codeend
\comment{}{4}{modifies:}{help}
\comment{}{4}{effects:}{Prints out help information for {\em command}
onto the help area specified by help. Signals not\_possible if the help area
is too small.}

\subsection{Implementation Overview}

The implementation of all the procedures in the Help Module is basically
the same. They all use the \verb+display+ procedure for a {\em window
object}, and they try to display successively smaller strings.  If the
\verb+display+ operation signals \verb+too_long+ for all attempted
strings, then the procedure will signal \verb+not_possible+.

\subsection{Validation Strategy}

Test strategy for the Help Module consisted of running each procedure
with a different sized {\em window object}, one of which had the
dimensions of the {\em window object} to be used for the help area in
CromChex.  

\section{The Command Module}

\subsection{Design Overview}

The Command Module consists of a main procedure (\verb+exec_command+)
which handles the user's input that is handed to it. It parses the input
(and any arguments), calls the appropriate procedure to execute the
command, and prints (or signals) any problems with the command or its
arguments.  The utility procedures that help \verb+exec_command+ do this
are: \verb+completion+, \verb+match+, \verb+get_command+,
\verb+get_args+, and \verb+upcase+.  The rest of the procedures are the
implementation of the various commands available in CromChex, with the
exception of two other utility procedures.

\subsection{Specifications}

There is no object associated with the Command Module, therefore there
is no abstract model.

\vspace*{.1in}
\input{commspc.tex} 

\subsection{Implementation Overview}

There is no data abstraction in the Command Module; there are only
procedures. Most of the procedures are straightforward: they follow the
specifications of what the commands of CromChex are supposed to do, as
given in the {\em User Manual}. The less obvious implementations are
those of the utility procedures, \verb+completion+ and \verb+match+
probably being the most interesting.  The procedure \verb+match+ is used
by \verb+completion+. What \verb+match+ does is iterate through the
characters of the (possibly) partial string and checks them against the
characters of the string it is given to match against. Then
\verb+completion+ uses \verb+match+ to check its argument (a buffer
containing a partial command) against all of the available commands in
CromChex. Another interesting algorithm is the one for \verb+get_args+.
Given an array of characters, it strips away all leading, intervening
(greater than one), and trailing spaces. The algorithm involves toggling
between states, one for when it is throwing away spaces and one for when
it is scanning non-space characters.

Again, all of the other procedures are fairly straightforward given the
specifications of what the commands in CromChex are supposed to do.

\subsection{Validation Strategy}

Simple automated testing, using {\em xfiles}, could have been done for the
Command Module. However, this would be very laborious and
time-consuming. It sufficed to test the trickier algorithms, such as
\verb+completion+ and \verb+get_args+, and debug the rest of the
procedures using the main loop, making sure all of the commands worked
as they were supposed to.

\section{The Main Loop}

\subsection{Design Overview}

The Main Loop of CromChex involves creating all of the necessary objects
for the game, setting up the screen et cetera, and then going into a
loop waiting for and getting input from the user and executing commands.
In retrospect, looking at all of the objects that are passed around, it
would have been better to have created a \verb+game_obj+ data
abstraction to encapsulate all of these various objects and then write
procedures which work on these objects. It would have been cleaner and
probably more understandable in terms of code. However, it was
implemented solely as top-level procedures passing objects around.

\subsection{Specifications}

There are three procedures besides the \verb+start_up+ procedure in the
main section of code.

\newpage
\input{mainspc.tex}

\subsection{Implementation Overview}

The trickiest part of the implementation was getting the timing right.
While the procedure \verb+wait_for_input+ waits for the user to type a
new key, it uses a {\em timer object} to keep track of how much time to
subtract off the user's time. Once there is a key waiting to be
processed, the procedure \verb+get_input+ takes over. It does a {\em
tagcase} on the kind of key the keyboard received and executes the
appropriate sequence of procedure calls.

Command-line completion was implemented using the \verb+completion+
command from the Command Module. Basically, if a space character is
received, \verb+get_input+ tries to complete what was in the input
buffer. If there was already a completed command in the buffer, it
does not try to do completion and just adds the space to the buffer.

\subsection{Validation Strategy}

Testing of the program in its entirety consisted of repeated execution
of the CromChex game, noting any discrepancies between the
specifications and the actual implementation of the game. Discrepancies
included unimplemented features and unforeseen problems as well as
unhandled exceptions (errors). The evidence of validation is hopefully
an uncrashable program.

\end{document}

\appendix{Code}
\section{Input Cluster}
\input{input.tex}
\section{Window Cluster}
\input{window.tex}
\section{Help Module}
\input{help.tex}
\section{Command Module}
\input{command.tex}
\section{Main Loop}
\input{main.tex}

