Java Forth

`JavaForth.jar`	[ Download ]	[ JavaDoc ]	[ Change Log ]
`test.forth`	[ Download ]

Interpreter

This is a very early attempt at a Forth package for Java. It is a fairly traditional ITC based Forth compiler with primitives written in Java. It uses a 32-bit (aligned) cell with a 16-bit character.

You can run the console based interpreter directly from the command line:

java -jar JavaForth.jar

The interpreter has a number of command line arguments:

-d <size>: Set the size of the data stack, <size> is the number of cells required. The default is 2048 cells.
-r <size>: Set the size of the return stack, <size> is the number of entries required. The default is 2048 entries.
-e <word>: Execute the given forth <word>. If you wish to execute more than a single word, simply place the expression between double quotes. For example, if you do not want the system to enter into console mode after processing a file, simply add "-e bye" as the last argument.
<filename>: Interpret the <filename> as forth source. The preferred file name extension is .forth, but the following extensions are supported: .forth, .fth, .fs, and .fh.
-: Interpret the standard input as forth source file. This will stop processing the input stream when it is exhausted, and return to the console. This allows the interpreter to read source code from a pipe or filter. Note that the normal prompt is disable while reading from the standard input in this manner.

All other parameters are passed to the Forth application via the non-standard next-arg word.

So, to run the interpreter on the test suite, give the command:

java -jar JavaForth.jar test

This will run the test suite and then prompt for further input. The prompt will display the current input line number and "OK" followed by an indication of the data stack depth.

Words

The following word sets are currently implemented:

Core

All 182 of the 200x Core and Core Ext words have been implemented.

Note: The Java terminal interface is line based and does not support single key entry. Thus the word KEY must read a whole line from the terminal, which must be terminated with the <return> or <enter> key. Only the first character of this line is returned by KEY.

In effect KEY is defined as:

: KEY ( -- char )
  HERE DUP 1 ACCEPT DROP C@
;

This can be resolved by using an application specific console, another item for the todo list.

The following non-standard word is provided:

JavaForth ( -- n ): Returns the compiler version. This can be used by a program to detect it is running on the JavaForth system. Where n is a number with the version, revision and release numbers of the current system encoded into a single value. Thus the value 10203 (decimal) corresponds to version 1.2.3 (version 1, revision 2, release 3).
Since version 0.5.1.

Block

Not implemented yet.

Double

Just enough words to run the core test suite: 2VARIABLE and DU<.

Exception

Not implemented yet.

Facility

Not implemented yet.

File

Not implemented yet.

Float

Not implemented yet.

Locals

Not implemented yet.

Memory

Not implemented yet.

Tools

The words necessary to run the core test suite: [IF], [ELSE] and [THEN].
A few words to help in the development: BYE, .S, ? and DUMP.

The following non standard words have also been defined:

/** ( -- ): Read a multi-line comment terminated with the character sequence "*/".
next-arg ( -- c-addr u ): Returns the next argument from the command line.
Return 0 0 if there not arguments left.

Search

Not implemented yet.

String

Not implemented yet.

Xchar

Not implemented yet.

API

The Jar can also be used as a Forth interpreter package. The following Java program uses the package to implement a simple Forth Interpreter:

import org.rigwit.Forth;
import java.io.*;
public class Sample {
    public static void main(String[] args) throws IOException {
        Forth forth = new Forth();
        forth.interpret(".( Free Memory: ) unused 1024 / 1 U.R .( Kb) CR");
        File file = new File("test.forth");
        forth.interpret(file);
        forth.interpret();
    }
}

Let's take this a line at a time:

6.	`Forth forth = new Forth();`
	Creates a new Forth interpreter. A program may have as many different interpreters as it requires.
7.	`forth.interpret(".( Free Memory: ) unused 1024 / 1 U.R .( Kb) CR");`
	Interpret a string of forth source code.
10.	`forth.interpret(file);`
	Read and interpret the file as forth source. This may throw an `IOException` if the file is not found, or if there is a problem reading the file.
12.	`forth.interpret();`
	Enter into the standard interpret loop: Prompt the user for input. Read a line of input from the terminal Interpret the line. The system will return from this method when the `BYE` word is executed by the forth system.

The full details of the API can be found in the Java Doc for the Forth class.

Peter J Knaggs
pjk@bcs.org.uk