\chapter{The Scheme user interface}
\label{interface}


This chapter provides details about using Scheme on the Bobcat system.  It
explains how to enter Scheme, how to evaluate expressions, how to
create and edit program files, how test and debug programs, and how to
obtain printed output.  Chapter~\ref{SchemeReference} of this manual
gives a complete list of the primitive procedures and special forms
included in the Scheme implementation.

\section{Running Scheme}
\label{running-scheme}
\index{evaluating Scheme expressions}

You run Scheme by first going through the login procedure as described
in section \ref{login}.  This will leave you in the Emacs editor, in a
buffer named {\tt *scheme*}.\schindex{*scheme*} You create Scheme
expressions by typing them or reading them from a file.  You can
evaluate an expression by giving the Emacs command \ctl{z}, which
evaluates the expression preceding the cursor.  The result of the
evaluation is displayed at the cursor position in the {\tt *scheme*}
buffer.  The simplest way to use Scheme is to work in the {\tt
*scheme*} buffer and type input expressions, following each one by
\ctl{z} to have Scheme print its value.  More generally, you can move
around in the {\tt *scheme*} buffer to re-evaluate or edit some
previous expression.  In general,
\ctl{z} will cause Scheme to evaluate the expression preceding the
cursor.  The command \esc{z} evaluates the current definition (i.e.,
the top-level definition that contains or precedes the cursor).  The
result will always be printed at the cursor position in the {\tt
*scheme*} buffer.

{\bf Helpful hint:}  When you are typing Scheme expressions, use
\ctl{J} rather than {\sc return} to start a new line. \ctl{J} both
starts a new line and indents to the correct amount, as dictated by
the parentheses in your expression.  In this way, your programs remain
much more readible, and it is easier to catch parentheses errors.

\subsection{Indicators of Scheme's status}
\label{scheme-buffer-mode-line}

Normally, Scheme is either running your program or running a system
procedure known as the \defining{read-eval-print} loop (or REP loop).  When
you first start Scheme, it will be running a ``level 1'' REP loop.
The status of Scheme is indicated in the mode line for the {\tt
*scheme*} buffer.

For instance, the following mode line
\begin{scheme}
-----Emacs: *scheme*   I 1 \verb|[|REP Loop\verb|]|   (Scheme: run)----Bot--
\end{scheme}
\noindent
shows that we are at the bottom of the {\tt *scheme*} buffer, which is
connected to a running Scheme.  The character {\tt I} indicates that
Scheme is waiting for input.  When Scheme is running, the {\tt I} is
replaced by an {\tt R}, or by a {\tt G} if Scheme is garbage
collecting.  You can continue to type at the editor while Scheme is
running---this is a good way to confuse yourself.  To keep the
confusion from becoming hopeless, Emacs will not allow you to evaluate
another Scheme expression until the previous evaluation is finished.
The {\tt \verb|[|REP Loop\verb|]|} in the mode line above indicates
that Scheme is running its ordinary read-eval-print loop.

If evaluating an expression signals an error, Scheme ask you whether
you want to {\it abort} from the error.  Aborting will return you to
the read-eval-print loop.  If you do not choose to abort, Scheme will
enter an {\it error REP loop}\index{error REP loop}.  The mode line
indicator will change to {\tt \verb|[|Error\verb|]|}.  Scheme's error
REP loops provide some powerful facilities for debugging, which are
described in chapter~\ref{debugging}.  To exit the error loop and
return to the REP loop, type \ctlc{G} (control-C followed by G).

The number 1 in the mode line above indicates that we are evaluating
expressions at ``level 1.''  Other levels are used during debugging.
If the level number gets higher than 1 and you are not (purposely)
using the debugging system, then you are probably doing something
wrong.  (Most likely, you forgot to exit an error loop by typing
\ctlc{G}.)  See chapter~\ref{debugging} for more information on
read-eval-print levels and on the debugging system.


\subsection{Evaluating expressions from other buffers}
\label{evaluating expressions}

You can move the Emacs cursor and select for evaluation any
expression, either in the {\tt *scheme*} buffer or in some other
buffer.  You can also use Emacs to mark a region and evaluate the
entire region using the Emacs command \escctl{Z}.\schindex{ctl-x z} You
can also evaluate an entire buffer using the
\esc{O} command.\schindex{esc-O} As the expressions are evaluated, the
values returned are shown in the echo area at the bottom of the
screen, and also placed at the end of the
{\tt *scheme*} buffer.

\section{Multiple buffers and windows}
\index{buffer}

If you are working with more than a small amount of code, you will
probably want to compose your programs in one buffer, rather than to
intermix your program text with Scheme output, as in the {\tt
*scheme*} buffer.  In general, you will find it convenient to work with
two text buffers---one for the file you are editing, and the {\tt
*scheme*} buffer for Scheme interactions.  You compose and edit
procedures in the file buffer.  Once you have typed a procedure
definition (most likely a Scheme {\tt define} expression), you can
transmit the definition to Scheme by evaluating it with \esc{z}.  Then
you can move to the {\tt *scheme*} buffer to try the procedure.

In addition to the {\tt *scheme*} buffer, the Scheme system
automatically creates a buffer called {\tt *default-edit*}, which you
can use for editing definitions that are not associated with any
file.\mainschindex{*default-edit* buffer} Loading a file into this
buffer will change the name of the buffer to the name of the file you
select.

\subsection{Windows and screen configurations}
\label{windows}
\mainindex{window}

Figure~\ref{scheme-and-edit-figure} shows the screen configured with
two {\em windows}---one for the {\tt *scheme*} buffer and one for an
edit window containing definitions that will be saved in a file.  You would
normally use this configuration when you are writing and incrementally
testing programs.  When there is more than one window, you can use the
Emacs command
\ctlx{O} to switch between windows.  (That's the letter ``oh'', not
the number zero.)

\begin{figure}
\label{scheme-and-edit-figure}
\vspace{3 in}
\caption{The screen configured using \protect\escx{window-scheme-edit}.}


\label{scheme-and-graphics-figure}
\vspace{3 in}
\caption{The screen configured using \protect\escx{window-scheme-graphics}.}
\end{figure}

\begin{figure}
\label{all-three-windows-figure}
\vspace{3 in}
\caption{The screen configured using \protect\escx{window-all}.}
\end{figure}


Figure~\ref{scheme-and-graphics-figure} shows the screen configured as
a window for the {\tt *scheme*} buffer and a window for graphics.  You
would normally use this configuration for running Scheme programs that
draw graphs.  Graphics is drawn in a region of the screen allocated to
a {\tt graphics} buffer, in which you cannot
type.\mainschindex{graphics buffer}
The Emacs command \escctl{L} clears the entire screen, including the
graphics.  It will redisplay the text region of the screen, but not
the graphics. 

Figure~\ref{all-three-windows-figure} shows the screen configured as
three windows---one for the {\tt *scheme*} buffer, one for graphics
and one for a file.  You would normally use this configuration to
confuse yourself and to impress your parents.

To set up the various screen configurations, you use the following
Emacs extended commands:

\begin{description}

\item [\escx{window-scheme}] Configure the screen with one window,
with the {\tt *scheme*} buffer.\mainschindex{window-scheme}

\item [\escx{window-edit}] Configure the screen with one window for
editing.\mainschindex{window-edit}

\item [\escx{window-scheme-graphics}] Configure the screen with two
windows---one for {\tt *scheme*} and one for
graphics.\mainschindex{window-scheme-graphics}

\item [\escx{window-scheme-edit}] Configure the screen with two
windows---one for {\tt *scheme*} and one for editing.
\mainschindex{window-scheme-edit}

\item [\escx{window-all}] Configure the screen with three
windows---for {\tt *scheme*}, for graphics, and for editing.
\mainschindex{window-all}

\end{description}

\noindent
In all of the cases above, ``a window for editing'' will view
the buffer that you most recently visited (either by reading in a file
using the Emacs command \ctlxctl{f} or by selecting the buffer using
\ctlx{b}).

\section{Using Program Files}

To process a file of Scheme programs, you can load the file into an Emacs
buffer using the Emacs command \ctl{X}\ctl{F}.  Then you can evaluate
the buffer with the \esc{O} command.  (That's the letter ``oh'', not
the number zero.)

Alternatively, if you do not want to
look at or edit the contents of the file, you can load the file
directly into Scheme using the Scheme \ide{load} procedure.
For example, evaluating the expression
\begin{scheme}
(load "ps1.scm")
\end{scheme}
\noindent
will load the file {\tt ps1.scm} from the default directory.

\subsection{Loading Problem Set Files}
\mainschindex{load problem set}

Most of your time in the laboratory will probably be spent working on
assigned problem sets.  Problem sets are distributed in printed form
during lecture, and you should read and understand these handouts
before coming into the laboratory to work on them.  Some of the
problem sets will include one or more program files to work with on
the Bobcat.  The Emacs command \esc{X load-problem-set} will help you
load a problem set.  Emacs will ask for the number of the problem set.
Depending on the problem set, Emacs may try to load code directly into
Scheme, write files onto your disk, or both.  The problem set
handout that instructs you to use the command will tell you what files
should be loaded or written in each case.

\section{Printing Transcripts of Scheme Sessions}
\mainindex{transcripts}

One easy way to get a printed copy of a Scheme session is to save the
{\tt *scheme*} buffer as a file, and then use the Emacs command
\escx{print-file}, which prints a file on the laser printer in the
6.003 lab.  You can also edit the {\tt *scheme*} buffer, move portions
of it to another buffer, and save and print that.

Another way to make a transcript is to use the Scheme procedures
\ide{transcript-on} and \ide{transcript-off}.  {\tt Transcript-on}
takes a file name as argument and causes all subsequent input and
output to be recorded in a file.  {\tt Transcript-off} stops the
recording.  After making the transcript you can edit and/or print the
file.  However, given the presence of the Emacs {\tt *scheme*} buffer, you
probably will not need to use the two transcript commands.

