js/games/nluqo.github.io/
"""Workaround to allow running single test cases directly""" try: from __init__ import init, Fake, OK, raise_ok except: from test import init, Fake, OK, raise_ok

<HTML>
<HEAD>
<TITLE>Simply Scheme Appendix A: Running Scheme</TITLE>
</HEAD>
<BODY>
<CITE>Simply Scheme</CITE>:
<CITE>Introducing Computer Science</CITE> 2/e Copyright (C) 1999 MIT
<H2>Appendix A</H2>
<H1>Running Scheme</H1>

<TABLE width="100%"><TR><TD>
<IMG SRC="../simply.jpg" ALT="cover photo">
<TD><TABLE>
<TR><TD align="right"><CITE><A HREF="http://www.cs.berkeley.edu/~bh/">Brian
Harvey</A><BR>University of California, Berkeley</CITE>
<TR><TD align="right"><CITE><A HREF="http://ccrma.stanford.edu/~matt">Matthew
Wright</A><BR>University of California, Santa Barbara</CITE>
<TR><TD align="right"><BR>
<TR><TD align="right"><A HREF="../pdf/ssch27.pdf">Download PDF version</A>
<TR><TD align="right"><A HREF="../ss-toc2.html">Back to Table of Contents</A>
<TR><TD align="right"><A HREF="../ssch26/preview.html"><STRONG>BACK</STRONG></A>
chapter thread <A HREF="appendix-cl.html"><STRONG>NEXT</STRONG></A>
<TR><TD align="right"><A HREF="http://mitpress.mit.edu/0262082810">MIT
Press web page for <CITE>Simply Scheme</CITE></A>
</TABLE></TABLE>

<HR>

<P>The precise incantations needed to start Scheme depend on the particular
version you're using and the model of computer and operating system you have.
It's beyond the scope of this book to teach you the first steps in using a
computer; we assume you've already used other programs, if not Scheme.
But in this appendix we suggest a few general ideas and point out some
knotty details.

<P>One thing that beginners often forget is that a computer generally has many
different programs available, and each one has its own capabilities and its
own method of operation.  If you think of yourself as interacting with &quot;the
computer,&quot; you're likely to try to use a command suitable for one program
when you're actually using a different program.  In learning to program in
Scheme, you'll probably use at least three programs: Scheme itself, the
operating system's <EM>shell</EM> (which is callled <EM>finder</EM> on the
Macintosh and <EM>explorer</EM> on Windows), and a text editor.  (The text
editor may be part of the Scheme package or it may be an entirely separate
program.)  The shell allows you to run other programs, such as a printing
utility or an electronic mail reader.

<P>If you say <CODE>(+ 2 3)</CODE> to your text editor, it won't respond by printing
<CODE>5</CODE>.  Instead, it will insert the seven characters that you typed into
the file that you're editing.  If you type the same thing to Scheme, it will
evaluate the expression.

<P><H2>The Program Development Cycle</H2>

<P>Scheme is an interactive language:  You can write a program by typing
its definition directly into the Scheme interpreter.  This ability
to interact with Scheme is a great advantage for one-time
calculations and for exploratory work, but it's not the best
approach for the systematic development of a large program.

<P>There are two issues to consider.  First, when writing a large program, you
generally don't get it perfect the first time.  You make both typing errors
and program logic errors, and so you must be able to revise a definition.
Typing directly to Scheme, the only way to make such a revision is to retype
the entire definition.  Second, Scheme does not provide a mechanism to save
your work in a permanent file.

<P>For these reasons, programs are generally typed into another program, a text
editor, rather than directly at the Scheme prompt.  As we'll explain in the
next section, there are several ways in which an editing program can be <EM>integrated</EM> with Scheme, so that the work you do in the editor can be
communicated easily to Scheme.  But the distinction between Scheme and the
editor is easiest to understand if we start by considering the worst possible
situation, in which the two are not integrated.

<P>Imagine, therefore, that you have two separate programs available on
your computer.  One program is a Scheme interpreter.  When you start
Scheme, you may see some initial message, and then you see a prompt,
which is a signal from Scheme that it's ready for you to type
something.  In this book we've used the character &quot;<CODE>&gt;</CODE>&quot; as the
prompt.  Then, as we explain in the text, you can type an
expression, and Scheme will compute and print the value:

<P><PRE>&gt; (+ 2 3)
5
</PRE>

<P>Your other program is a text editor.  This might be a
general-purpose word processing program, with facilities for
fancy text formatting, or it might be an editor intended
specifically for computer programs.  Many editors &quot;know&quot; about
Lisp programs and have helpful features, such as automatic
indentation, selection of complete expressions, and showing you the
matching open parenthesis when you type a close parenthesis.

<P>To write a program, you use the editor.  Although you are typing
Scheme expressions, you're not talking to Scheme itself, and so the
expressions are not evaluated as you type them.  Instead, they just
appear on the screen like any other text.  When you're ready to try
out your program, you tell the editor to save the text in a file.
(The command to save the program text is the same as it would be for
any other text; we assume that you already know how to use the
editor on your computer.)  You can give the file any name you want,
although many people like to use names like <CODE><EM>something</EM></CODE><CODE>.scm</CODE> to make it easy to recognize files that contain Scheme
programs.

<P>Now you switch from the editor to Scheme.  To read your program file into
Scheme, you enter the expression

<P><PRE>(load &quot;<EM>something</EM>.scm&quot;)
</PRE>

<P>This tells Scheme to read expressions from the specified
file.<A NAME="text1" HREF="appendix-running.html#ft1">[1]</A>

<P>Once Scheme has read the program definitions from your file, you
can continue typing expressions to Scheme in order to test your
program.  If this testing uncovers an error, you will want to
change some definition.  Instead of typing the changed definition
directly into Scheme, which would only make a temporary change in
your program, you switch back to the editor and make the change in
your program file.  Then switch back to Scheme, and <CODE>load</CODE> the
corrected file.

<P>This sequence of steps&mdash;edit a file, make changes, save the
file, switch to Scheme, load the file, test the program, find an
error&mdash;is called a &quot;development cycle&quot; because what comes
after &quot;find an error&quot; is editing the file, beginning another
round of the same steps.

<P><H2>Integrated Editing</H2>

<P>The development process can become much more convenient if Scheme and the
editor &quot;know about&quot; each other.  For example, instead of having to reload
an entire file when you change one procedure definition, it's faster if your
editor can tell Scheme just the one new definition.  There are three general
approaches to this integration:  First, the editor can be in overall charge,
with the Scheme interpreter running under control of the editor.  Second,
Scheme can be in charge, with the editor running under Scheme's
supervision.  Third, Scheme and the editor can be separate programs, both
running under control of a third program, such as a window system, that
allows information to be transferred between them.

<P>If you're using a Unix system, you will be able to take a
separate editor program and run Scheme from within that editor.
The editor can copy any part of your program into the running
Scheme, as if you had typed it to Scheme yourself.  We use Jove,
a free, small, fast version of EMACS.  Most people use the more
featureful GNU version of EMACS, which is installed on most Unix
systems and available at <CODE>ftp://prep.ai.mit.edu/pub/gnu/</CODE> and
many mirror sites for download.

<P>If you're using a Macintosh or Windows version of Scheme, it will probably
come with its own text editor and instructions on how to use it.  These
editors typically provide standard word-processing features such as cut and
paste, search and replace, and saving files.  Also, they typically have a
way to ask Scheme to evaluate an expression directly from the editor.

<P>If you're using SCM under DOS, you should read the section &quot;Editing
Scheme Code&quot; in the <CODE>README</CODE> file that comes with the SCM
distribution.  It will explain that editing can be done in different
ways depending on the precise software available to you.  You can
buy a DOS editor that works like the Unix editors, or you can ask
SCM to start a separate editor program while SCM remains active.

<P>Finally, if you're running Scheme under Windows or another windowing
operating system (like X or the Macintosh Finder), you can run any editor in
another window and use the cut and paste facility to transfer information
between the editor and Scheme.  

<P><H2>Getting Our Programs</H2>

<P>This book uses some programs that we wrote in Scheme.  You'll want these
files available to you while reading the book:

<P><TABLE>
<TR><TD><CODE>simply.scm</CODE>
<TD>extended Scheme primitives
<TR><TD><CODE>functions.scm</CODE>&nbsp;&nbsp;&nbsp;
<TD>the <CODE>functions</CODE> program of Chapters 2 and 21
<TR><TD><CODE>ttt.scm</CODE>
<TD>the tic-tac-toe example from Chapter 10
<TR><TD><CODE>match.scm</CODE>
<TD>the pattern matcher example from Chapter 16
<TR><TD><CODE>spread.scm</CODE>
<TD>the spreadsheet program example from Chapter 24
<TR><TD><CODE>database.scm</CODE>
<TD>the beginning of the database project
<TR><TD><CODE>copyleft</CODE>
<TD>the GNU General Public License (see Appendix D)
</TABLE><P>

In particular, the file <CODE>simply.scm</CODE> must be loaded into Scheme to allow
anything in the book to work.  Some Scheme systems allow you to load such a
&quot;startup&quot; file permanently, so that it'll be there automatically from then
on.  In other versions of Scheme, you must say

<P><PRE>(load &quot;simply.scm&quot;)
</PRE>

<P>at the beginning of every Scheme session.

<P>There are three ways to get these program files:

<P><P><TABLE><TR><TH align="right" valign="top">&bull;<TD>&nbsp;&nbsp;&nbsp;&nbsp;<TD valign="top">If you have access to the Internet, 
the most recent versions of all these files can be found at
<CODE>ftp://anarres.cs.berkeley.edu/pub/scheme/</CODE>

</TABLE>
<P><TABLE><TR><TH align="right" valign="top">&bull;<TD>&nbsp;&nbsp;&nbsp;&nbsp;<TD valign="top">If you know someone who already has these files, you may copy them
and distribute them freely.  (The programs are copyrighted but are provided
under a license that allows unlimited redistribution on a nonprofit
basis; see Appendix D.)
</TABLE><TABLE><TR><TH align="right" valign="top">&bull;<TD>&nbsp;&nbsp;&nbsp;&nbsp;<TD valign="top">If you're stranded on a desert island with nothing but a computer and a
copy of this book, you can type them in yourself; complete listings for all 
six programs, plus the GNU Public License, appear in the text of the book.

</TABLE><P>

<P><H2>Tuning Our Programs for Your System</H2>

<P>Almost all of the programs we distribute with this book will work
without modification in the popular versions of Scheme.  We've
included &quot;defensive&quot; procedures that allow our programs to work
even in versions that don't conform to current Scheme standards
in various ways.  However, there are a few details that we
couldn't make uniform in all versions.

<P>1.  Many versions of Scheme include a <CODE>random</CODE> procedure to generate
random numbers, but the standard does not require it, and so we've provided
one just in case.  If your Scheme includes a primitive <CODE>random</CODE>, it's
probably better than the one we provide, because we have no way to choose
a different starting value in each Scheme session.

<P>Before loading <CODE>simply.scm</CODE> into Scheme, do the following experiment:

<P><PRE>&gt; (random 5)
</PRE>

<P>If you get an error message, do nothing.  If you get a random
number as the result, edit <CODE>simply.scm</CODE> and remove the definition of
<CODE>random</CODE>.

<P>2.  Do the following experiment:

<P><PRE>&gt; (error &quot;Your error is&quot; &quot;string&quot;)
</PRE>

<P>If the message you get doesn't include quotation marks around the
word <CODE>string</CODE>, then do nothing.  But if you do see <CODE>&quot;string&quot;</CODE> with
quotation marks, edit <CODE>simply.scm</CODE> and change the definition of
<CODE>error-printform</CODE> to

<P><PRE>(define (error-printform x) x)
</PRE>

<P>3.  Although the Scheme standard says that the <CODE>read</CODE>
procedure should not read the newline character following an
expression that it reads, some old versions of Scheme get this wrong.

<P>After loading <CODE>simply.scm</CODE>, do the following experiment:

<P><PRE>&gt; (read-line)
</PRE>

<P>End the line with the <CODE>return</CODE> or <CODE>enter</CODE> key
(whichever is appropriate in your version of Scheme) as usual,
but don't type a second <CODE>return</CODE> or <CODE>enter</CODE> yet.  If
Scheme prints <CODE>()</CODE> right away, skip this paragraph; your
version of Scheme behaves correctly.  If, on the other hand,
nothing happens, type another <CODE>return</CODE> or <CODE>enter</CODE>.  In
this case you must edit <CODE>functions.scm</CODE> and remove the
invocation of <CODE>read-line</CODE> on the first line of the body of
the <CODE>functions</CODE> procedure.

<P>4.  There is a substantial loss of efficiency in treating strings of
digits as numbers in some contexts and as text in other contexts.  When
we're treating 1024 as text, we want to be able to take its <CODE>butfirst</CODE>,
which should be 024.  But in Scheme, <CODE>024</CODE> is the same as <CODE>24</CODE>, so
instead <CODE>butfirst</CODE> returns a string:

<P><PRE>&gt; (butfirst 1024)
&quot;024"
</PRE>

<P>Yet we want to be able to do arithmetic on this value:

<P><PRE>&gt; (+ 3 (butfirst 1024))
27
</PRE>

<P>To accomplish this, we redefine all of Scheme's arithmetic
procedures to accept strings of digits and convert them to numbers.  This
redefinition slows down all arithmetic, not just arithmetic on strange
numbers, and it's only rarely important to the programs we write.
Therefore, we've provided a way to turn this part of the package off and on
again.  If your programs run too slowly, try saying

<P><PRE>&gt; (strings-are-numbers #f)
</PRE>

<P>If you find that some program doesn't work because it tries to do
arithmetic on a digit string and gets an error message, you can say

<P><PRE>&gt; (strings-are-numbers #t)
</PRE>

<P>to restore the original behavior of our programs.  We recommend
that you leave <CODE>strings-are-numbers</CODE> true while exploring the first few
chapters, so that the behavior of the word data type will be consistent.
When you get to the large example programs, you may want to change to false.

<P><H2>Loading Our Programs</H2>

<P>Scheme's <CODE>load</CODE> procedure doesn't scan your entire disk looking for the
file you want to load.  Instead, it only looks in one particular directory
(DOS/Unix) or folder (Macintosh/Windows).  If you want to load our programs,
you have to make sure that Scheme can find them.

<P>The first way to accomplish this is to give the full &quot;path&quot; as part of the
argument to <CODE>load</CODE>.  Here are some examples:<A NAME="text2" HREF="appendix-running.html#ft2">[2]</A>

<P><PRE>UNIX-SCHEME&gt; (load &quot;/usr/people/matt/scheme-stuff/simply.scm&quot;)

WINDOWS-SCHEME&gt; (load &quot;c:\\scheme\\simply.scm&quot;)

MAC-SCHEME&gt; (load &quot;Hard Disk:Scheme Folder:simply.scm&quot;)
</PRE>

<P>Under Unix, directories in a path are separated by forward slash
characters.  Under Windows and DOS, directories are separated by backward slash
characters, which have a special meaning to
Scheme.  So you must use double
backslashes as in our example above.  On a Macintosh, you separate the parts of
a path with colons.  (However, most versions of Scheme for the Macintosh
or Windows
have a load command in one of the menus that opens a standard file
selection dialog box, so you can use that instead.)

<P>The other possibility is to put the files in the place where your version of
Scheme looks for them.  In many versions of Scheme, <CODE>load</CODE> looks
for files in the folder that contains the Scheme program itself.  Put our
files in that folder.

<P>On Unix, the default loading directory is whatever directory you're in at
the moment.  If you want to work on different projects in different
directories, there's no way to make it so that <CODE>load</CODE> will always find
our files.  (But see our suggestion about writing <CODE>book-load</CODE>.)

<P><H2>Versions of Scheme</H2>

<P>There are lots of them, both free and commercial.  Three places to
look for pointers are

<P><PRE>http://swissnet.ai.mit.edu/scheme-home.html
http://www.schemers.org
http://www.cs.indiana.edu/scheme-repository
</PRE>

<P>In general, there are four things you should be sure to learn about
whatever version of Scheme you choose:

<P><P><TABLE><TR><TH align="right" valign="top">&bull;<TD>&nbsp;&nbsp;&nbsp;&nbsp;<TD valign="top">Most versions of Scheme include a <EM>debugger</EM> to help you find
program errors.  If you call a primitive with an argument not in
its domain, for example, Scheme will start the debugger, which will have
features to let you find out where in your program the error occurred.
These debuggers vary greatly among versions of Scheme.  The first thing
you should learn is how to <EM>leave</EM> the debugger, so you can get
back to a Scheme prompt!

</TABLE><TABLE><TR><TH align="right" valign="top">&bull;<TD>&nbsp;&nbsp;&nbsp;&nbsp;<TD valign="top">Many versions of Scheme will read an <EM>initialization file</EM> if
you create one.  That is, when you start Scheme, it will look for a file
of a particular name (something like <CODE>init.scm</CODE>, but not usually
exactly that), and if there is such a file, Scheme will <CODE>load</CODE> it
automatically.  You can copy our <CODE>simply.scm</CODE> file to the proper
filename for your version, and you'll have our added primitives available
every time you start Scheme.

</TABLE><TABLE><TR><TH align="right" valign="top">&bull;<TD>&nbsp;&nbsp;&nbsp;&nbsp;<TD valign="top">Most versions of Scheme provide a <CODE>trace</CODE> capability, but the
format of the trace results are quite different from one version to
another.

</TABLE><TABLE><TR><TH align="right" valign="top">&bull;<TD>&nbsp;&nbsp;&nbsp;&nbsp;<TD valign="top">If you are using a Macintosh, one thing to watch out for is that some
versions of Scheme expect you to use the ENTER key at the end of an
expression, while others expect you to use the RETURN key.

</TABLE>

<P><H2>Scheme Standards</H2>

<P>The Web sites listed above will provide the latest version of the <EM>Revised<SUP><SMALL><I>n</I></SMALL></SUP> Report on the Algorithmic Language Scheme.</EM>  You can
get the document in either Postscript or HTML format.

<P>IEEE Standard 1178-1990, <EM>IEEE Standard for the Scheme Programming
Language,</EM> may be ordered from IEEE by calling 1-800-678-IEEE or
908-981-1393 or writing IEEE Service Center, 445 Hoes Lane, P.O. Box 1331,
Piscataway, NJ 08855-1331, and using order number SH14209 ($28 for IEEE
members, $40 for others).  ISBN 1-55937-125-0.

<P>
<HR>
<A NAME="ft1" HREF="appendix-running.html#text1">[1]</A> If you see an error message about &quot;end of file&quot; or &quot;EOF,&quot; it
probably means that the file you are trying to load contains unbalanced
parentheses; you have started an expression with a left parenthesis, and the
file ended before Scheme saw a matching right parenthesis.<P>
<A NAME="ft2" HREF="appendix-running.html#text2">[2]</A> Suggestion for
instructors: when we teach this class, we define a procedure like

<P><PRE>(define (book-load filename)
  (load (string-append &quot;/usr/cs3/progs-from-book/&quot; filename)))
</PRE>

<P>so that students can just say

<P><PRE>(book-load &quot;functions.scm&quot;)
</PRE><P>
<P><A HREF="../ss-toc2.html">(back to Table of Contents)</A><P>
<A HREF="../ssch26/preview.html"><STRONG>BACK</STRONG></A>
chapter thread <A HREF="appendix-cl.html"><STRONG>NEXT</STRONG></A>

<P>
<ADDRESS>
<A HREF="../index.html">Brian Harvey</A>, 
<CODE>bh@cs.berkeley.edu</CODE>
</ADDRESS>
</BODY>
</HTML>