-*-Indented-Text-*-

This is the directory for the Gambit implementation of Thomas, a
compiler written at Digital Equipment Corporation's Cambridge Research
Laboratory.  Thomas compiles a language compatible with the language
described in the book "Dylan(TM) an object-oriented dynamic language" by
Apple Computer Eastern Research and Technology, April 1992; the file
DIFFERENCES lists the known differences.

We have made every effort to minimize the differences between Thomas and
Dylan(TM), and to remove bugs, but help from others would be greatly
appreciated.  The original development team consisted of:

          Matt Birkholz (Birkholz@crl.dec.com)
          Jim Miller (JMiller@crl.dec.com)
          Ron Weiss (RWeiss@crl.dec.com)

In addition, Joel Bartlett (Bartlett@wrl.dec.com), Marc Feeley
(Feeley@iro.umontreal.ca), Guillermo Rozas (Jinx@zurich.ai.mit.edu) and
Ralph Swick (Swick@crl.dec.com) contributed time and energy to the initial
release.

                                * * *

                             INSTALLATION

To install this version of Thomas you must already have Gambit 1.8
or later.  Gambit can be obtained by anonymous FTP from
trex.iro.umontreal.ca.  If you do not have access to FTP, send electronic
mail to Feeley@iro.umontreal.ca to discuss other arrangements.

The implementation of Thomas is largely in IEEE standard Scheme and resides
in ../src/.  Some generic utilities are available as IEEE standard packages
independent of Thomas and reside in ../portable/.  A small amount of code
is Gambit-specific and resides in this directory.  The src/ subdirectory of
this directory contains symbolic links to all the various pieces needed to
produce a working Thomas in Gambit.

The rest of these instructions assume you already know how to use Gambit.

1) There are three ways to use Thomas: as a compiler, as a runtime
   execution environment, or as an interactive environment.  Each is
   described below.

   a) Compiler: Load the file "load-compiler".  This provides two
      main procedures:

        (THOMAS <file-name> . expressions) compiles the Thomas EXPRESSIONS
      and puts the resulting Scheme expression into <FILE-NAME>.

        (THOMAS->SCHEME input output) compiles the INPUT file consisting of
      Thomas expressions, generating a single Scheme expression into the
      OUTPUT file.

   b) Runtime Execution: Load the file "load-runtime".  This provides a
      Scheme environment into which the output of the Thomas compiler can
      be loaded for execution.

   c) Interactive Environment: Load the file "load-thomas".  This gives you
      two procedures:

        (THOMAS-REP) starts a read-eval-print (REP) loop which works like
      an ordinary Gambit REP loop, but uses a Thomas evaluator instead
      of a Scheme evaluator.  Errors that are not trapped by your Thomas
      code will invoke another Gambit (NOT Thomas) REP loop.  Exiting from
      this REP loop will take you back to the top-level, beyond the simple
      Thomas-REP.  You must apply thomas-rep to restart the Thomas-REP.

         (EMPTY-THOMAS-ENVIRONMENT!) forgets about previously defined
      module variables created by (THOMAS-REP).  This is the only way
      (short of restarting Scheme) to clean out the Thomas environment if
      things become messed up.

2) While Thomas can run fully interpreted, it will be considerably faster
   if you compile it.  The file "compile" is provided to assist you in
   doing this.  It includes a useful declaration at the beginning of every
   file to be compiled, and invokes the compiler with an appropriately
   sized heap.  Note that we were not able to run all of dylan-examples.dyl
   with a compiled Thomas system.  (There appears to be a problem at
   garbage collection time.)  To run the compiled system:

        csh> ~/gsi -- -h10000 -c2000
	Gambit (v1.8)

	: (load "load-thomas")
	Loading common
	Loading support
	.
	.
	.

	Loading rep

	Apply thomas-rep to start a Thomas read-eval-print loop.
	"load-thomas.O"

	: (thomas-rep)

	Entering Thomas read-eval-print-loop.
	Exit by typing "thomas:done"

	? (define x 5)

	Value: x
	? (define-method double ((n <number>)) (+ n n))

	Value: double
	? (define-method double ((s <string>)) (concatenate s s))

	Value: double
	? (double x)

	Value: 10
	? (double "foo")

	Value: "foofoo"
	? (double '(1 2))

	*** ERROR -- generic-dispatch -- no applicable methods ...

	1: ,t

	: (exit)

                                * * *

                         Language Extensions

The Gambit Scheme version of Thomas includes three additional predefined
methods:
     (PP <object>) calls the Scheme pretty printer.
     (SCHEME-VARIABLE <symbol>) returns the value of a Scheme variable
       that is visible from the normal user interaction environment.
       This can be used to access any Scheme object, but results are
       unpredictable unless the object has a type that corresponds to
       one of the non-procedural Thomas types.  Common types that can
       be accessed this way are booleans, symbols, strings, numbers,
       the empty list, as well as vectors or lists composed of these.
     (SCHEME-PROCEDURE <symbol>) also returns the value of a Scheme
       variable that is visible from the normal user interaction
       environment.  It assumes (without checking) that it is
       applicable and converts it to a Thomas method.  From within
       Thomas it will appear to take an arbitrary number of arguments,
       but will issue an error if the number supplied doesn't match
       the number expected by the Scheme procedure.

$Id: gambit_README,v 1.3 1992/09/25 16:44:15 birkholz Exp $
