\chapter{COD}

\section{Introduction}
The {\tt COD} program has been designed to fill two roles.
First, it can be used as a programmable calculator.
In this mode you can use the computer to do simple calculations
(on days that your calculator is down).
Second, it is designed to assist in developing and testing COD functions
that can be used as components in PLT models.

This chapter assumes that you want to create a COD file
that can be used with PLT.
If you have no previous experience with COD,
then you should start by running the {\tt COD} program
and learning how to use the stack and various built-in functions.
(In COD, functions are sometimes called {\em words}.)
Next you should create and use some simple {\em colon definitions}
within {\tt COD} itself.
Colon definitions are the way one creates new functions.
COD files contain ASCII text in the same form
as you would type in interactive mode.
A file that can be used as a model component by PLT
is nothing more than a COD file
containing a colon definition and supporting code.
The {\tt COD} program provides tools
for reading and testing functions contained in COD files.

\section{Interactive mode}
The best way to learn about COD
is to run the {\tt COD} program and experiment.
This can be done with
\begin{verbatim}
$ COD
Type HELP for help.

COD>
\end{verbatim}
When COD starts, it first prints information on how to get help,
followed by a blank line.
The blank line actually displays the contents of the stack,
which is initially empty.
Finally, you get the ``\verb@COD>@'' prompt.
At this prompt you can type {\tt HElp}
to obtain interactive help on the various commands and how to use them.

The first thing you will want to do is to enter a number into the stack.
This is done by typing the number and then pressing the \fbox{Return} key.
For example, to enter the number {\tt 2} into the stack,
\begin{verbatim}

COD> 2
 2.0
\end{verbatim}
COD echos the stack and then returns the COD prompt (in this documentation
the final prompt is not shown).
To execute a simple mathematical function, enter
all the numbers required by the function
and then the function itself.
The following sequence shows how to multiply the previously entered {\tt 2}
by the number {\tt 3} to obtain {\tt 2*3}:
\begin{verbatim}
 2.0
COD> 3
 2.0 3.0
COD> *
 6.0
\end{verbatim}
With COD it is not necessary
to enter one token (number or function) per line.
Tokens may be entered, separated by spaces, on a single line.
Hence, to divide the result of the previous calculation by {\tt 0.5},
enter
\begin{verbatim}
 6.0
COD> .5 /
 12.0
\end{verbatim}
COD contains several commands to manipulate the stack.
Thus {\tt SWap} will swap the top two numbers on the stack,
and {\tt DUP} will duplicate the top number on the stack.
When using COD interactively,
you will sometimes wish to clear out the stack.
The can be done using the {\tt ABOrt} command.
Thus,
\begin{verbatim}
 12.0
COD> ABOrt

\end{verbatim}
and the blank line indicating an empty stack will again appear just
before the following COD prompt.
There are a large number of built-in COD functions.
To obtain a list of the functions,
you may use the \, {\tt List~Dictionary} \, command.
If you see a function and would like more information on what it does,
you should use the \verb@ HElp Dictionary @ command.
For a complete list of built-in COD commands,
consult Appendix A.

\section{Colon definitions}
When running COD interactively,
it is sometimes necessary to enter the same sequence of tokens several times.
For such cases, you should create a colon definition
that contains the sequence.
A colon definition consists of a colon \verb@ : @,
followed by the function name,
followed by the sequence of COD functions that you wish to execute
when the function name is typed,
and terminated with a semi-colon \verb@ ; @\@.
For example, although there is no built-in COD function to square a number,
you can create one with
\begin{verbatim}
COD> : X2 DUP * ;
\end{verbatim}
which will have the effect of multiplying the top number on the
stack by itself.
After you have defined \verb@X2@,
it may be used in exactly the same way as any built-in function; thus,
\begin{verbatim}
COD> 3.0 X2
 9.0
\end{verbatim}
A previously-defined colon function
may be used in the definition of a new colon function.
An \verb@X3@ function, for example,
can be constructed from the \verb@X2@ function with
\begin{verbatim}
COD> : X3 DUP X2 * ;
 9.0
COD> 3.0 X3
 9.0 27.0
\end{verbatim}
The name of a colon function is not allowed to match
the name of any built-in function or other colon function.
Hence, a colon function cannot be used
to redefine the action of any existing COD keyword.

It is possible to enter a multi-line colon definition interactively.
While in the midst of a multi-line colon definition,
the stack will not be printed just before the COD prompt.
The following example shows one way to enter a colon definition
that prints the integers from one to five:
\begin{verbatim}
COD> : COUNT5
COD>   5 1 FOR
COD>          I .
COD>       LOOP
COD> ;
 9.0 27.0
COD> COUNT5
 1.0
 2.0
 3.0
 4.0
 5.0
 9.0 27.0
\end{verbatim}
The last line, just before the next COD prompt, is the stack.
This allows us to verify that the original stack has been changed,
and therefore, {\tt COUNT5} is not altering the stack.

\section{COD files}
COD provides a way to read commands from a disk file.
These files contain the same commands
that you would enter {\it via} the interactive mode.
Commands not contained in a colon definition will execute as the file is read.
In order to use a COD file as a model component in PLT,
it is necessary that the file contain at least one colon definition
and it is the last colon definition that will be called
when the component is evaluated.
As an example of a COD file,
assume the file \verb@LINE.COD@ contains the following lines:
\begin{verbatim}
 ! COD program to calculate a line.
 ! P1 + P2*X
 : LINE  P1 X P2 * + ;
\end{verbatim}
All lines that begin with `!' are considered comment lines
and are ignored by COD.
The third line contains the program itself.
\verb@P1@ and \verb@P2@ refer to the parameters
that will be adjusted to minimize $\chi^2$.
When these words execute,
they will load the value of the corresponding parameter into the stack.
When writing COD programs that use parameters,
you must use consecutive numbers starting with one --- {\it i.e.},
do not leave any holes in the sequence.
The keyword {\tt X} is used to push the current value of $x$ into the stack.

   It is also possible to use the COD program to read and test
the code found in a COD file.
The following example demonstrates how this can be done:
\begin{verbatim}
COD> GET LINE  ! Read the test file, note comment lines are echoed.
 ! COD program to calculate a line.
 ! P1 + P2*X
 NTERMS= 2
COD> NEW 1 2.  ! Set parameter 1 to 2.0

COD> NEW 2 1.  ! Set parameter 2 to 1.0

COD> 5         ! Place the number 5.0 in the stack
 5.0
COD> RUN       ! Run the program with an X value of 5.0
 7.0           ! The final result
\end{verbatim}
The \verb@RUN@ command reads the top number on the stack,
makes it the $x$ value,
clears the stack,
and then runs the last program in memory.
All these steps ensure that COD is in the same state as
it will be when called from the PLT routine.

The {\tt Single} step command can be used to debug a COD function.
In the above example, instead of typing {\tt RUN},
you could have entered \, {\tt Single~Init}.
This would have read the top number in the stack,
made it the $x$ value,
cleared the stack,
and then executed the first step in the {\tt LINE} colon definition.
When using {\tt Single} step,
COD echos a line that contains three columns of information.
The first column is the memory location that is about to be executed.
The second column contains the encoded command which can be ignored.
The third column is the decoded command that is to be executed.
When taking single steps,
the stack is still be printed just before the COD prompt appears.
Hence, you can watch each step and its effect on the stack.

Code not contained in a colon definition will execute
as the COD file is being read.
Assume the \verb@FUNC.COD@ file contains the following lines:
\begin{verbatim}
 VAR 2PI
 2 PI * 2PI STO
 : FUNC X 2PI RCL * P1 / COS ;
\end{verbatim}
While this file is being read,
the variable \verb@2PI@ is created and
loaded with the value of $2 \pi$.
The function {\tt FUNC} can now access and use this variable.

\section{Other stack-oriented languages}
People who have used the Forth, Postscript, and/or HP calculators
will recognize certain similarities with COD.
This is partly by accident,
since all these languages were designed
to solve the problem of making a very fast interpreted language.
Given the similarity,
it would be pointless for similar functions
to be implemented differently in COD.
Although there is no standard stack-oriented language,
when compared to HP calculator languages, or to the Postscript language,
the deficiencies/limitations of Forth are serious.
In addition, it is the author's opinion that more people know about
HP calculators and Postscript, then about Forth.
For these reasons,
Forth will no longer be considered to be a model for COD.
It is the intention of the current author to pattern new COD
functions after existing functions from other languages.
Currently, HP calculator language, as implemented on the HP48,
is the most powerful of such languages and will be examined first
for models of new COD functions.
