JScheme User manual



13 April 2002

This manual is in preparation










Downloading JScheme

Downloading the jscheme.jar file

The simplest way to access Jscheme is just to download the jscheme.jar file and put it on your classpath.

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:

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









The JScheme Command Line

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 
    > (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 specified after the "-main" argument. That is, this is equivalent to:
    % java jscheme.REPL
    > (load "test.scm")
    > (rundemo a "this is a test" 123)









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:









The JScheme Applet

If you download the source distribution, then you can visit the file
   
src/contrib/jswebapp/jscheme/demo/JSchemeEvaluator.html
which provides an applet for writing and running Scheme code.








Calling JScheme from Java







Using a Single Static JScheme Evaluator

Jscheme can be called from Java using the JS class which evaluate expressions in a single statically defined JScheme evaluator.

For example, you can:

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))
   







Using an Independent JScheme Evaluator

A better approach is to use the new jscheme.JScheme class which allows you to create an independent JScheme evaluator that can use used just as the static JS class above....

  jscheme.JScheme js = new jscheme.JScheme();

  js.eval("....")
  js.call(a, b,c,d,e);
  ...