JScheme User manual

13 April 2002

This manual is in preparation

Downloading Jscheme
- downloading the jar file
- downloading and compiling the source code
The JScheme Shell
The JScheme compiler
The JScheme Applet
Calling JScheme from Java

Downloading JScheme

Downloading the jscheme.jar file

The simplest way to access Jscheme is just to download the jscheme.jar or jscheme.zip file and put it on your classpath.
(This is usually down with a shift-click or right-click or some other operating-system/browser dependent click variant on the jscheme.jar or jscheme.zip link.)

Once jscheme.jar is downloaded, you can put it in your classpath, and run it as an interpreter:

  % java jscheme.REPL
  > (* 12345679 8)
  98765432
  > (exit)
  %

or as a Scheme->Java compiler:

  % cat > Hello.scm
  (display "Hello World") (newline)
  ^D
  % java jsint.Compile Hello.scm
  % javac Hello.java
  % java Hello
  Hello World
  %

Downloading the source distribution from the CVS server

If you want the entire source distribution, then you can use the anonymous CVS download facilities at sourceforge.net to download and build Jscheme. Jscheme sourceforge site You can download the source code directly using anonymous CVS as follows:

  % cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jscheme login
   (when prompted for a password for anonymous, simply press the Enter key)
  % cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jscheme co jscheme

Occasionally, Sourceforge changes the name of the cvs host (its happened twice so far). If the above instructions don't work, try the official sourceforge instructions. You can then build jscheme.jar from the source as follows:

Under Linux or Mac OS X:
Run the src/build/bootstrap script from the toplevel of the jscheme folder, after making sure that the JDK has been installed on your system:
```
  % cd jscheme
  % src/build/bootstrap
  %
  % java -cp lib/jscheme.jar jscheme.REPL
  > (java.util.Date.)
  Mon Jan 07 14:53:23 EST 2002
  > ....
 
```
Under Windows:
Run the build/bootstrap.bat script from the toplevel of the jscheme folder, after making sure that the JDK has been installed on your system:
```
  % cd jscheme
  % src\build\bootstrap.bat 
  %
  % java -cp lib/jscheme.jar jscheme.REPL
  ....
```

This creates a file jscheme.jar in the jscheme folder.

The JScheme Shell

Assuming that jscheme.jar is on your classpath, you can invoke a Scheme interpreter using

    % java jscheme.REPL file1 file2 file3 ... '(expr1)' '(expr2)'
    > ...

Jscheme can also be supplied command line arguments that will load several files (file1, file2, ...) and evaluate several expressions ( (expr1) (expr2) ...). The files and expressions are loaded or evaluated in the order they appear on the command line. Thus the following command

    % java jscheme.REPL file1 '(expr1)' file2 '(expr2)' file3 ...
    >

is equivalent to

    % java jscheme.REPL file1 '(expr1)' file2 '(expr2)' file3 ...
    > (load "file1")
    > (expr1)
    > (load "file2")
    > (expr2)
    > (load "file3")
    > ...

Finally, you can make pass command line arguments to a Scheme procedure using the "-main" argument to specify the procedure name and the sequence of arguments, as follows:

    % java jscheme.REPL test.scm -main rundemo a "this is a test" 123
    >

The arguments are passed as an array of strings to the procedure whose name is specified after the "-main" argument.

The JScheme compiler

The JScheme compiler provides one way of compiling a Scheme program Prog.scm into a Java class, Prog.java The compiled program can be loaded into another program using
(packagename.Prog.load)
which behaves exactly the same as
(load "packagepath/Prog.scm")
You can also specify a main procedure in the Scheme program which will get compiled into a main method of the Java program. We now give an example to illustrate this process.
First we create a test file to compile. Note that the compiler requires you to explicitly import all classes, even the java.lang classes (you could also use the full name java.lang.System.out$). Also note that you can access the command line args by writing a procedure main with one paramter args. This will be compiled into the public static void main method of the class and provides a way of accessing the argument array.

  % cd demo/test
  % cat > Prog.scm
    (import "java.lang.System")
    (import "java.lang.reflect.Array")
    (define (main args)
      (.println System.out$ (java.util.Date.))
      (.println System.out$ (Array.get args 0))
      (System.exit 0)
     )
    ^D
  % cd ../..

Now we compile the program (using the -p switch to set the package and the -v switch to specify verbose output). After compiling to java, we compile the java to byte codes and then run the program

  % java jsint.Compile -v -p demo.test Prog.scm
  % javac Prog.java
  % java demo.test.Prog "Hello, World"
    Sat Apr 13 10:42:25 EDT 2002
    Hello, World
  %

Compiler switches:

"-p PACKAGE" is the switch for setting the package name for the compiled Jscheme program.
"-v" ... verbose mode

The JScheme Applet

If you download the source distribution, then you can visit the file

   jscheme/src/demo/jlib/Demorunner.html

which provides an applet for writing and running Scheme code. (Note this currently only works with Java 1.2 enabled browsers such as Netscape 6.*).

You can also run Jscheme as a Java Web Start application but this assumes you have already downloaded and installed Java Web Start (it is an easy download/install)

Calling JScheme from Java

Jscheme can be called from Java using the JS class

For example, you can:

Initialize an application by loading Scheme expressions from a file:
```
      JS.load(new java.io.FileReader("app.init"));
    
```
Run the Scheme procedure (describe) to describe the current object like this:
```
    JS.call("describe", this);
    
```
If you need to call a procedure with more than three arguments use apply().

Evalute a string as an expression:

    String query = "(+ (expt (Math.sin 2.0) 2) (expt (Math.cos 2.0) 2))";
    System.out.println(query + " = " + JS.eval(query));

Unit test:

   (assert (equal? (+ 2 3) (JS.eval '(+ 2 3))))
   (assert (= (+ 2 3) (JS.eval "(+ 2 3)")))
   (assert (= (+ 2 3) (JS.call "+" 2 3)))
   (assert (= (+ 2 3) (JS.call + 2 3)))
   (assert (= (+ 2 3) (JS.apply "+" (JS.list 2 3))))
   (JS.load "(define (f x) (+ x (g x))) (define (g x) (* x 3))")
   (assert (= (f 3) 12))