RetroForth is a compact, easy to learn, and quite useful implementation of the Forth programming language. It is based on the Rx Core, which provides most of the essential Forth words, but not an interactive environment. The RetroForth code extends the Rx Core to provide an interpreter, editor, and many additional words.

This Handbook is an expanded version of the Rx Handbook, Revision 1.1.


The concept of a was derived from HelFORTH. Traditionally, RetroForth followed the cmForth model of having two dictionaries, one for immediate words and one for normal words. With version 8.2, released in the later months of 2005, the internal model shifted to support word classes.

Word classes are a way to group related words, based on their compilation and execution behaviors. A special word, called a is defined to handle an execution token passed to it on the stack. The compiler uses a variable named to set the default class when compiling a word. We'll take a closer look at later. The Rx Core provides RetroForth with several primary classes with differing behaviors:

The class mechanism is not limited to these classes. You can write custom classes at any time. On entry the custom handler should take the XT passed on the stack and do something with it. Generally the handler should also check the compiler state to determine what to do in either interpretation or compilation. As a simple example, let's take a look at the hander, written in Forth:

When writing programs in RetroForth, you will need to set the class of each word you write. There are numerous ways to do this. A look at the example below will show how each method appears in source. We'll use the class in the examples, but the same approach applies to all of the classes.

Because changing the default class will be done regularly, the main classes also have wrapper functions provided. These wrappers are given a class of and are listed below. In general, it's recommended to use these wrappers to set the default class for readability reasons.

There is a single dictionary consisting of a linked list of headers. The current form of a header is shown in the chart below. Pay special attention to the accessors. Each of these words corresponds to a field in the dictionary header. When dealing with dictionary headers, it is recommended that you use the accessors to access the fields since it is expected that the exact structure of the header will change over time.

Word names are stored in the dictionary as packed strings. Use to obtain a counted string from it. In memory, a packed string looks like:

Because of the use of a single byte for the count, word names are limited to 255 characters.

The most recently created header can be accessed by using a variable named . To access a specific header, you can use to get the header that points to a specified XT. A special variable named is also updated by find each time a word is looked up in the dictionary. This variable always points to the entry of the most recently found word.

Given only a single dictionary, it might seem limiting, however both vocabularies and lexical scope have been implemented on top of it. We will look at each of these now.


There will be often be times you would like to "hide" some words that you only use once or twice to build other words. In Rx, the ability to do this is provided by the lexical scoping words and

A typical use looks like:

As you can see in the example above, when a lexically scoped definition is closed, the headers for all words inside the scoped region are removed. Only words explicitly revealed are kept in in the global dictionary. Also, as is shown in the example, you can nest lexically scoped sequences. Nesting is possible up to four levels deep.

Lexical scopes are used frequently by the developers of Rx and RetroForth and allow a good level of factoring without polluting the actual dictionary with words that are not needed outside a select few definitions.


We recognize that there will be times when you want to be able to hide words from the main dictionary, but still access them later. This is where vocabularies come into the picture. RetroForth provides a single word which can be used to create a named vocabulary. A simple example of a vocabulary in use is shown below.

Notice that you need specify the vocabulary once per line when you wish to create a new word inside the vocabulary. When you wish to use words from inside a vocabulary in a definition, specify the vocabulary inside the definition. When you use a vocabulary in a definition, words defined in the main dictionary after the vocabulary was defined are not visible. To close the vocabulary (and reveal words defined after it), use a word called . This is shown in the example below.

By default, the RetroForth reports syntax errors with a short error message. This behavior can be changed at any time by replacing a special vectored word named . is the "last chance" error handler. When the interpreter obtains a token it tries to process it in a defined order:

You can extend this or simply report errors by changing to point to a new definition. As a vectored word, this is easily done. A simple example is shown below.

This replaces the default definition of with a new handler that displays a nice error message.

Of course it is possible to write significantly more flexible error handlers. For instance, you could write a handler for entering floating point numbers, say , and hook that into to allow the user to enter floating point numbers directly at the interpreter.


Many words in RetroForth are defined as vectored words. These are similar to, but more flexible than, deferred words in ANS Forth. A vectored word will have as the first word in its definition. This is the only step necessary to make a word vectorable. Two words are provided for altering and resetting vectored definitions. These are and .

The word is used to set a vector to a new XT. In use it takes the new XT on the stack and parses for the name of the vectored word to change. If the specified name does not exist, it creates a new vectored word with a default definition calling the specified XT. To reset a changed vector to the original definition, the word is used. This parses ahead for the name of the word to remove the vector from. What these three words allow is the changing of existing definitions. As a simple example, try the code below.

While a bit simplistic, this does show how to use vectors. Vectors can also be used with lexically scoped sequences to make revealing multiple words cleaner:

Learning to use vectored words will allow you to explore new options in your programming.


Most of the words provided by RetroForth are listed here. Some, which are platform specific, are not.

Many words in the bootstrap code for Rx are written using raw opcodes for various instructions. This has been a cause of much confusion, so we'd like to take the time now to document what each word actually compiles to. Due to the little-endian nature of the x86, the opcodes in the source are in reverse order. These listings have the normal order.