org.rigwit.forth.words

Class WordSet

java.lang.Object

org.rigwit.forth.words.WordSet

Direct Known Subclasses:

CoreWords, DoubleWords, TestWords, ToolWords

public class WordSet
extends java.lang.Object

The superclass for Java primitive classes.

Java primitive classes provide additional system primitives — our equivalent of code words. Such classes must extend this class. The WordList.loadJava() method will only load Java classes if they extend this class.

To be recognised as a primitive the Java method must have the signature:

public void method(XT);

All such methods will be reflected in the current word list with the Forth name method. When the Forth word is executed, the associated Java method is executed, with the invoking XT as the argument.

All other Java methods will not be reflected in the Forth word list but are available to the Java primitive.

Three fields are provided to allow the java primitives access to the current virtual machine, they are:

• vm – The current virtual machine.
• data – The data (parameter) stack of the current virtual machine.
  This is nothing more than a short cut for vm.data.
• mem – The user memory area of the current virtual machine.
  This is a abbreviation for vm.memory.

Template Class

The following is an empty Java primitive class file template:

 import org.rigwit.forth.XT;
 import org.rigwit.forth.annotation.*;

 public class ExampleWords extends WordSet {
     // ... Java primitive definitions go here ...
 }

Annotations

To change the default handling of the primitive method a number of annotations are provided:

@Primitive("<name>")

The Java method is reflected in the Forth word list with the given <name> rather than the method name. This allows the Forth name to contain characters that are not valid in Java method names.

@Immediate

Marks the method as immediate, the method will be called at compile time rather than run time.

@Stack("<description>")

The method has the given stack description.

This is currently an optional annotation intended for documentation, but it is our intention to make this a mandatory annotation in the future.

@Environment[("<name>")]

The Java method is added to the list of environmental queries, with the key <name>. If the <name> is not given, the name of the method is used.

High Level Definitions

High-level definitions may be embedded in the class file with the @Forth annotation. The annotation may be attached to a class, field or method definition.

As the Java annotation system does not allow an annotation to be attached to a definition more than once, the @Interpret annotation has been provided to allow for a collection of @Forth annotations. Thus making it possible to attach multiple forth statement to a definition. The @Forth annotations within an @Interpret group are processed in the order they are written.

 @Interpret({
     @Forth("DECIMAL"),
     @Forth("32 CONSTANT BL")
 })
 public class ExampleWords extends WordSet { ... }

The annotations are interpreted after the primitive definitions in the class have been loaded. The annotations are processed in the following order:

1. Class Definition.
2. Field Definitions.
   The annotations are processed in the order given, but all of the annotations attached to field definitions are processed before any annotations attached to a method definition.
3. Method Definitions.
   The annotations are processed in the order given.

Naming Conventions

A naming convention is in place for providing additional classes of word. Let us consider the standard value definition (6.2.2405).

The value primitive is given as follows:

 @Stack("x '<spaces>name' -- ")
 public void value(XT xt) {
     xt = vm.create();                // Create user definition
     xt.setHandler(this, "valueDef"); // Change XT handler
     Object item = data.popObj();     // Pop item from data stack
     mem.addCell(item);               // Place item in dictionary
 }

Note that the vm.create() method returns the XT for the definition it has created.

The handler for the XT is changed to the valueDef method of this class. The name of the handler method must end with "Def".

When the new XT is executed the handler for the XT (valueDef(XT)) will be invoked with the XT as its argument. The address of the next cell after the calling XT is on the top of the data stack.

The handler method must be public and take an XT as an argument. It should return an integer which is added to the current IP so that it can skip over the data associated with the XT (a single cell value in this case). The valueDef method is:

 @Stack("a-addr -- x")
 public int valueDef(XT xt) {
     int addr = data.popAddr();         // Address of next cell
     Object value = mem.getCell(addr);  // Fetch cell
     data.pushObj(value);               // Push cell
     return VM.CELL;                    // Skip one cell
 }

TO Words

The general modifier word TO (6.2.2405) is used to modify the value returned by a value definition. This will parse the next word in the input stream and determine that the word is a user definition. It will then look up the words handler (valueDef in our case) and replace the "Def" with "To". As with the handler method, the modifier method must be public and take the XT of the definition to be modified as its argument.

Thus when TO is used on a value definition, the java method valueTo(XT) is invoked with the XT of the definition as its argument. The valueTo method is:

 @Stack("x -- ")
 public int valueTo(XT xt) {
     Object item = data.popObj();
     mem.setCell(xt.here, item);
     return 0;
 }

Note that xt.here holds the address of the data field of the original valueDef definition.

By making the method return an integer value, we ensure it is not reflected in the Forth word list when the primitive file is loaded, although the return value is ignored.

See Also:

Forth Virtual Machine (VM), eXecution Token (XT)

Field Summary

Fields

Modifier and Type	Field and Description
protected TypedStack	data The data stack for the current virtual machine.
protected Memory	mem The user memory area for the current virtual machine.
protected VM	vm The current virtual machine.

Constructor Summary

Constructors

Constructor and Description
WordSet()

Method Summary

Methods

Modifier and Type	Method and Description
void	setVirtualMachine(VM machine) Set the virtual machine to reflect the vm the wordset has been loaded into.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

vm

protected VM vm

The current virtual machine.

data

protected TypedStack data

The data stack for the current virtual machine. This is nothing more than an abbreviation for vm.data.

mem

protected Memory mem

The user memory area for the current virtual machine. This is nothing more than an abbreviation for vm.memory.

Constructor Detail

WordSet

public WordSet()

Method Detail

setVirtualMachine

public void setVirtualMachine(VM machine)

Set the virtual machine to reflect the vm the wordset has been loaded into.

Parameters:

machine - the Forth Virtual Machine these words effect.