HOW TO RUN SCHEME

				  by

			   Gary T. Leavens
	Department of Computer Science, Iowa State University
		  File $Date: 1999/01/08 23:35:58 $

This document gives basic ways to use Scheme on the Com S department
machines and on Project Vincent,
and ways to use Scheme from within emacs.
It also describes how to get Scheme for other computers.

1. STARTING SCHEME ON HP-UX

The default for this course is to run the SCM interpreter for Scheme
on the Com S department HP-UX servers.  MIT Scheme is another interpreter
that is also available on these machines.

(The interpreters are found in /usr/unsup/bin, so you must have this
directory in your shell PATH for the interpreters to work.  But this
is the default on the Com S department HP-UX servers, so you shouldn't
have to do anything special to set this up.)

1.1 STARTING CHEZ SCHEME

Log in to your Com S account.  Then type (at the shell's prompt, %)
	scheme
and then hit the ``return'' (or enter) key.
Be sure your input is in lower case (NOT CAPITALIZED).
You will see something like the following.

    Chez Scheme Version 6.0a
    Copyright (c) 1998 Cadence Research Systems
    
    > 

with the prompt ``> '' indicating that Chez Scheme is waiting for your input.

Now type your input, followed by a return.
(Try typing 
	(+ 2 3)
and then ``return'' for starters.)

1.2 STARTING SCM

Log in to your Com S account.  Then type (at the shell's prompt, %)
	scm
and then hit the ``return'' (or enter) key.
Be sure your input is in lower case (NOT CAPITALIZED).
You will see something like the following.

    SCM version 5b4, Copyright (C) 1990, ..., 1997 Free Software Foundation.
    SCM comes with ABSOLUTELY NO WARRANTY; for details type `(terms)'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `(terms)' for details.
    ;loading /usr/unsup/scheme/scm/slib/require
    ;done loading /usr/unsup/scheme/scm/slib/require.scm
    ;loading /usr/unsup/scheme/scm/Transcen
    ;done loading /usr/unsup/scheme/scm/Transcen.scm
    > 

with the prompt ``> '' indicating that SCM is waiting for your input.

Now type your input, followed by a return.
(Try typing 
	(+ 2 3)
and then ``return'' for starters.)


2. STARTING CHEZ SCHEME ON VINCENT

Log in to your Vincent account.  Then type (at the shell's prompt, %)
	add scheme
and then hit the ``return'' (or enter) key.  Be sure your input is in
lower case (NOT CAPITALIZED).  You will see something like the following.

             You have added Chez Scheme version 4.1

You can put the add scheme command in your .startup.tty
file to have it automatically executed each time you log in.

Now just type
	scheme
and hit ``return''. You will see the following:

	Chez Scheme Version 4.1
	Copyright (c) 1991 Cadence Research Systems
	
	> 

with the prompt ``> '' indicating that Chez Scheme is waiting for your input.

Now type your input, followed by a ``return''.


3. WORKING WITH SCHEME

3.1 EXITING SCHEME

To exit any of the scheme interpreters (SCM, MIT Scheme, or Chez Scheme) type
	(exit)
or type a control-d (hold down the ``control'' key and at the same time
type a ``d'', without the quotes.).

3.2 MAKING A TRANSCRIPT

To record your session with a Scheme interpreter in a file named
``trans.out'' (without the quotes), that is to put your inputs and its
outputs in the file ``trans.out'', type the following to Scheme
	(transcript-on "trans.out")
This must be typed exactly as above, with the double quotes (").
To make a transcript in some other file, write that name
instead of trans.out.

3.3 LOADING FILES

It is very convenient to put your code for Scheme programs in files,
and have Scheme read those files.  A standard way to have Scheme read
a file is to use the load procedure.  The advantage of this is that
load can be called from a program; for example, you can have one file
that loads several others.  Another advantage is that you can use load
after you have already started Scheme.  An example of using load after
starting Scheme is as follows.  (Suppose that ``> '' is the Scheme
prompt, you don't type that.)

	> (load "foo.scm")

If your files have errors you will see an error message; for example,

        Error in read: unexpected end-of-file at line 2, char 1 of ./foo.scm.

is an error message (from Chez Scheme) that means that foo.scm is missing
one or more right parentheses (a common mistake).

In Chez Scheme and SCM, you can also load files by simply listing the
files you want to load on the command to start Scheme.  For example,
using scm to read in files named ``foo.scm'' and ``bar.scm,'' you
would type at the operating system prompt:

	scheme foo.scm bar.scm

We will use this trick to load some files by default whenever you start
a Scheme interpreter.  A standard way to do this is part of setting up your
account for this course.

(Should you need to make such a script for yourself, you
could proceed as follows. Make a shell script, say ~/bin/scm342,
containing the following line.
       exec scheme file-I-always-load.scm $*

The line says to start Scheme and load the file
``file-I-always-load.scm'' and then any other files you specify on the
command line.  Be sure that there is a newline following this line.
That is, if emacs asks you if you want one, answer yes.  Remember to
change the Unix file mode (permissions) on the shell script file you
just created to make it executable.  Suppose you called the shell
script scheme342 (don't call it scm or scheme!), then you would execute
the following:
	chmod +x ~/bin/scheme342

To check that this has been set up properly, try the following from
the Unix shell.
	rehash
	which scheme342
	echo ~/bin/scheme342
The responses to the last 2 commands should be the same.
Note, this will not affect any scheme interpreters that you already have
running.)

3.4 SCHEME ADVANCED TOPICS

The ``Revised^5 Report on The Algorithmic Language Scheme'' is available
on-line.  You can find it from the URL
	http://swissnet.ai.mit.edu/~jaffer/r5rs_toc.html
with your favorite WWW browser.  Or you can read it locally either:

  * from the URL http://www.cs.iastate.edu/~leavens/ComS342/html/r5rs_toc.html
  * by using the Unix program ``info'' or the info mode of emacs (M-x info).
    (To do this, select ``Unsupported'' from the first menu,
     then select ``R5rs''.)

There is an internet newsgroup for Scheme: comp.lang.scheme.
You might also want to look into the WWW for the Scheme home page:
	http://www-swiss.ai.mit.edu/scheme-home.html
and the Internet Scheme repository:
	http://www.cs.indiana.edu/scheme-repository/home.html

See the Unix manual page for details about the particular Scheme interpreters.
These will tell you how to do such things as compiling files and
saving your session so you can start where you left off.
For example, to see the manual page for SCM type the following to Unix.
	man scm
To see the manual page for Chez Scheme on Vincent type:
	man scheme
(This will show one screenful; to see more type a space.)
Chez Scheme doesn't currently have a manual page.
But even better, it has a detailed user's guide,
which you can browse from your favorite web browser using the URL:

     file:///usr/local/csv6.0/csug/index.html

You can look around at the source directories for Chez Scheme and SCM
for other interesting information.

The source directory for Chez Scheme is

	/usr/local/csv6.0

The source directory for SCM is

	/usr/unsup/scheme/scm

See the file MANUAL in that directory for more information.
SCM also comes with a library of scheme code, called SLIB.
You can read about it using the info program or the info mode of emacs.

4. EDITING SCHEME FILES

4.1 EDITING SCHEME FILES WITH EMACS

Of the standard Unix editors, emacs has the best support for Scheme
programming (and for other programming languages also).  In addition
to matching parentheses (when you type ``)'' it shows which ``(''
matches it) for you, emacs knows how to indent Scheme programs to make
them look good.  But before emacs will do this for you, it must know
that you are editing a Scheme program.  The best way to tell emacs
that you are editing a Scheme program is to use the customizations
found in the file.

	/home/course/cs342/public/docs/sample-.emacs

Either copy that into your file ``~/.emacs'', or edit the relevant lines
into your file ``~/.emacs''.

With the relevant customization of your file ``~/.emacs'',
when you are editing a file whose name ends in ``.scm'' (or ``.ss'')
then that is a Scheme file.

Be sure that all your Scheme file names end in ``.scm'' (or ``.ss'')!
For example ``member.ss'' is a good name, but not ``homework''.

To find out about scheme-mode in emacs, edit a scheme file and then
type C-h m (that is, control-h and then ``m'').  You will see a table
of commands that looks like the following (which has been simplified;
what you see in emacs by typing C-h m is the truth).

What you type	What it does
=============   =============================
RET		newline-and-indent
LFD		newline
DEL		backward-delete-char-untabify
TAB		scheme-indent-line

C-c C-l		scheme-load-file
C-c C-z		switch-to-scheme
C-c C-c		scheme-compile-definition-and-go
C-c C-r		scheme-send-region
C-c C-e		scheme-send-definition

C-x C-e		scheme-send-last-sexp

ESC C-x		scheme-send-definition
ESC C-q		scheme-indent-sexp

C-c ESC r	scheme-send-region-and-go
C-c ESC e	scheme-send-definition-and-go

For example, if you type C-x C-e (control-x and then control-e),
it sends the previous s-expression (a parentheses balanced thing you typed)
to the Scheme process.

2.2 INTERACTING WITH SCHEME FROM EMACS

To run Scheme from within Emacs, start emacs, and then use the command
M-x run-scheme.  (That is, type ESC, then ``x'' then at the prompt
``run-scheme''.  This will put you in ``inferior scheme mode'' in a
buffer called *scheme*.  You will soon see the scheme system starting,
just as if you had run it directly from the project vincent shell.
(The name of the command run is given by the Emacs variable
``scheme-program-name''.)  You can type expressions at the prompt, and
then by typing ``return'', you will see them evaluated.  To find out
about inferior scheme mode in emacs, from the *scheme* buffer type C-h
m.  You will see a table of commands that includes those in the table
above, and some additional ones.

What you type	What it does
=============   =============================
C-h		backward-delete-char-untabify
TAB		scheme-indent-line
C-d		comint-delchar-or-maybe-eof
RET		comint-send-input

C-x C-e		scheme-send-last-sexp

C-c C-l		scheme-load-file
C-c RET		comint-copy-old-input
C-c C-\		comint-quit-subjob
C-c C-z		comint-stop-subjob
C-c C-c		comint-interrupt-subjob
C-c C-u		comint-kill-input

ESC C-q		scheme-indent-sexp
ESC C-x		scheme-send-definition
ESC p		comint-previous-input

The basic addition is that when you type a return (RET),
what you typed is sent to the Scheme interpreter.  You can edit the input using
emacs commands, but note that whatever is on a line at the time you
type return (RET) is sent to Scheme, and is not affected by
further editing.  However you can go back up in the buffer and
send an edited expression again by placing your cursor just to the right
of the last right parentheses, and typing return.

You do not need to separately exit Scheme and emacs,
as exiting emacs will kill Scheme.  (However, if you use MIT Scheme, it's
best to exit Scheme first, otherwise it leaves a core dump.)

The scheme running under emacs does not automatically know about changes
you make to Scheme code files or other emacs Scheme buffers.
You have to either explicitly load the file (use load-file in Scheme
as described above), or use a scheme-send command (such as C-x C-e)
in the buffer where you are editing your code.
(Note that these have to be in the same emacs process,
if you are on a workstation and you can move two emacs windows independently,
they are not the same.)

2.3 EDITING SCHEME WITH VI (BZZT!)

If you don't already know how to use vi, please don't learn it.
The vi editor does not know how to format Scheme code (or for that matter C++).
If you must use vi, invoke it with the ``-l'' option,
which will make it match parentheses for you.

You can also use your vi keystrokes in emacs.
To do this, simply execute
	M-x viper-mode RET
when in emacs.  See also the emacs help by typing
        M-x help-for-help i
and then select the topic ``Viper Mode'' for more information.
This allows you to use vi's editing commands, but all the features of emacs.
It also allows you to use the mouse in this emulation, something you
can't really do in vi.

If you decide you want to use viper-mode in emacs all the time,
put the following line in your .emacs file.
	(viper-mode)


3. OTHER SCHEMES

The following information is included for completeness.  You probably
don't need it, unless you have a home computer.  If so,
read the frequently-asked-questions (FAQs) posted to the newsgroup
comp.lang.scheme or from the following URL for more information about
scheme for your computer.

	ftp://ftp.cs.indiana.edu/pub/scheme-repository/doc/misc/scheme_2.faq