Introduction

Retro is a small, minimalistic dialect of Forth.

The Retro language has a rich history going back to 1998 when it was first released as a 16-bit standalone Forth for x86 PC's. Since then it's evolved through use into its present form, which is a 32-bit implementation running on a portable virtual machine called Ngaro. Today Retro runs on all major operating systems, and thanks to a JavaScript implementation of the virtual machine, on any modern web browser.

The code and documentation for Retro are gifted to the public domain. You may use them freely and without restriction.

Platforms Supported

• Alpha
  • Linux
• ARM
  • iPhoneOS (iPhone, iPod Touch, 2.2.1; jailbroke)
• PowerPC
  • AIX
• x86
  • BeOS
  • BSD (DragonFly, FreeBSD, NetBSD, OpenBSD)
  • Haiku
  • Linux
  • MacOS X (10.5.x)
  • Windows (XP, Vista)
• x86-64
  • Linux
• Browsers
  • Chrome
  • FireFox (2 & 3)
  • Opera
  • Safari
  • Safari Mobile (using form-based I/O)
  • SongBird

Obtaining

Retro is generally distributed as source code and needs to be compiled before it can be used. The latest development snapshots and periodic stable release snapshots are provided at http://retroforth.org

Developers who want to keep up with the latest changes are encouraged to use Git. We have a repository at http://github.com/crcx/retro10 which is kept up to date.

Building (Unix-like host)

These instructions are for users of Linux, BSD, OS X, BeOS, AIX, etc. Windows users should see the next section.

You'll need a few things:

• GCC (4.x recommended)
• Binutils
• Make
• Curses (curses, ncurses, and pdcurses all work fine) and/or libSDL

Given these, try the following command:

make vm

Or, if you want the framebuffer backend to be used:

make fbvm

If you get any errors, check the vm/console/retro.c and vm/console/retro-fast.c and see if the LIBS line matches the Curses varient used on your system.

Building (Windows)

• Install Dev C++ (http://prdownloads.sourceforge.net/dev-cpp/devcpp-4.9.9.2 setup.exe)
• Install the Curses Devpack (http://devpaks.org/details.php?devpak=5)
• Create an empty project and add the following files from vm/console to it:
  • functions.h
  • disassemble.c
  • endian.c
  • loader.c
  • ngaro.c
  • devices.c
  • initial_image.c
  • vm.c
  • vm.h
• Go to Project -> Options and add the following to the Linker commands: -lcurses
• Compile everything

Starting Retro

Just run the retro (or, on Windows, the retro.exe) binary and Retro will start. If you built a command line configuration (the default), you can load files into Retro using a command line option:

--with filename

Use filename as an input source. You can include multiple files by specifying more than one --with, but you should be aware that the files are included in reverse order. E.g.,

./retro --with file-a --with file-b --with file-c

With this, file-c is included, then file-b, and finally file-a.

Interacting with Retro

Unlike most Forths, Retro does not buffer on a line by line basis. Input is parsed as it is typed, and words are executed when the spacebar is hit.

This is a significant source of confusion to users coming from other Forth systems. Just remember: only space is recognized by a default Retro system as a valid separator between words.

Tip:

Although input is parsed as it is typed, backspace does work on most systems, so you can correct the current word being typed if you make a mistake.

Leaving Retro

Just type bye and hit space.

Images

The Retro language is stored in an image file. When you start Retro, the VM looks for a retroImage file. If if can't find one, it uses a minimal image that is built in instead.

You can save your current Retro session to a retroImage by using the save word, and reload it later. All words/variables you have created will be kept and you can continue working without having to reload or retype everything.

You can also use the vector functionality in Retro to replace/alter most of the existing words to meet your needs.

Overview

Retro is not a standard-compliant Forth. It's significantly different in many areas. This section will help explain these differences and show how Retro works internally.

Threading Model

Retro uses subroutine threading with inline machine code for select words. This model has been used by Retro since 2001 as it is simple, clean, and allows for optimization to be done by the compiler if desired.

Taking a look at the subroutine threaded code generated by Retro:

: foo 1 2 + . ;

Will compile to:

lit 1
lit 2
+
call .
;

Simple operations that map to single instructions are inlined by the Retro compiler, saving some call/return overhead. Other optimizations are also possible.

Interpreting and Compiling

Retro has a very simple intepreter loop.

: listen  ( - )
  repeat ok 32 # accept search word? number? again ;

This displays a prompt (ok), accepts input until a space is encountered (ASCII 32). The dictionary is searched, and if the word is found, word? calls the class handler for the word. If not found, number? tries to convert it to a number. If this fails as well, an error is displayed. In any case, exection repeats until a fatal error arises, or until the user executes bye.

For simplicity sake, the number conversion code in Retro only supports decimal (base 10). No other base is supported at this time.

There is no separate compilation process. In Retro, the compiler is nothing more than a state variable that the word classes use to decide what to do with a word.

Word Classes

As mentioned above, the interpreter loop (listen) passes the words (and also data elements like numbers) to something called a word class.

This is another area in which Retro's implementation differs from standard Forths. The word class approach was created by Helmar Wodtke and allows for the interpreter and compiler to be extremely clean by allowing special words (class handlers) to handle different types of words.

This means that the interpreter loop does not need to be aware of the type a word has, or of any aspect of the system state.

The standard Retro language has five classes defined.

In addition to the five core classes, it is possible to create your own classes. As an example, we'll create a class for naming and displaying strings. Our class has the following behavior:

• If interpreting, display the string
• If compiling, lay down the code needed to display the string

Retro has a convention of using a . as the first character of a class name. In continuing this tradition, we'll call our new class .string

Tip:

On entry to a class, the address of the word or data structure is on the stack. The compiler state (which most classes will need to check) is in a variable named compiler.

A first step is to lay down a simple skeleton. Since we need to lay down custom code at compile time, the class handler will have two parts.

: .string  ( a—)
  compiler @ 0 =if ( interpret time ) ;; then ( compile time )
;

We'll start with the interpret time action. We can replace this with type, since the whole point of this class is to display a string object.

: .string ( a — )
  compiler @ 0 =if type ;; then ( compile time ) ;

The compile time action is more complex. We need to lay down the machine code to leave the address of the string on the stack when the word is run, and then compile a call to type. If you look at the instruction set listing, you'll see that opcode 1 is the instruction for putting values on the stack. This opcode takes a value from the following memory location and puts it on the stack. So the first part of the compile time action is:

: .string ( a — )
  compiler @ 0 =if type ;; then 1 , , ;

Tip:

Use , to place values directly into memory. This is the cornerstone of the entire compiler.

One more thing remains. We still have to compile a call to type. We can do this by passing the address of type to compile.

: .string ( a — )
  compiler @ 0 =if type ;; then 1 , , ['] type compile ;

And now we have a new class handler. The second part is to make this useful. We'll make a creator word called displayString: to take a string and make it into a new word using our .string class. This will take a string from the stack, make it permanent, and give it a name.

Tip:

New dictionary entries are made using create. The class can be set after creation by accessing the proper fields in the dictionary header. Words starting with d-> are used to access fields in the dictionary headers.

: displayString: ( "name" — )
  create ['] .string last @ d->class ! keepString last @ d->xt ! ;

This uses create to make a new word, then sets the class to .string and the xt of the word to the string. It also makes the string permanent using keepString. last is a variable pointing to the most recently created dictionary entry. The two words d->class and d->xt are dictionary field accessors and are used to provide portable access to fields in the dictionary.

We can now test the new class:

" hello, world!" displayString: hello
hello
: foo hello cr foo ;

Vectors

Vectors are another important concept in Retro.

Most Forth systems provide a way to define a word which can have its meaning altered later. Retro goes a step further by allowing all words defined using : or macro: to be redefined. Words which can be redefined are called vectors.

Vectors can be replaced by using is, or returned to their original definition with devector. For instance:

: foo 23 . ;
foo
: bar 99 . ;
' bar is foo
foo
devector foo
foo

There are also variations of is and devector which take the addresses of the words rather than parsing for the word name. These are :is and :devector.

Reading Stack Comments

Stack comments in Retro are a compact form, using short codes in place of actual words. These codes are listed in the next section.

A typical comment for a word that takes two arguments and leaves one will look like:

In a few cases, words may consume or leave a variable number of arguments. In this case, we denote it like:

There are two other modifiers in use. Some words have different compile-time and run-time stack use. We prefix the comment with C: for compile-time, and R: for run-time actions.

If not specified, the stack comments are for runtime effects. Words with no C: are assumed to have no stack impact during compilation.

Codes used in the stack comments:

List of Words by Class

MacOS X

The standard keymaps in the Terminal app don't report the normal ASCII codes for certain keys. This can be worked around with osx.retro. After building, extend your retroImage:

./retro --with osx.retro

Save your image, and you'll be able to use backspace in the future.

Browser

The JavaScript implementation of the Ngaro VM allows for some interaction with the browser. With a few simple words you can quickly take control of the browser (and the VM) by mixing JavaScript into your Forth code.

: toggle-html ( - ) 1 9998 out wait ;

When invoked, this will toggle the filtering of special characters by the console driver on and off. (By default the special characters are filtered. These include < > & and others). When the filter is off, you can use HTML to format the output in the console.

: js ( $- ) 2 9998 out wait ;

This is the more powerful of the two. It allows for passing a Retro string to the JavaScript eval() function. You can pass any valid JavaScript code and have it run. You can also access the variables and functions of the Ngaro VM using it.

Something simple to try:

: depth s" alert(sp);" js ;

Overview

While working with Retro, I've assembled a set of extensions that I personally find useful, but which don't need to be in the core.

Loading the Extensions

The extensions are provided in a single file named extend.retro. This can be found in the bin directory. Load it by doing:

./retro --with extend.retro

Save, and the extensions will remain present in future sessions.

The Words

The main words provided by extend.retro are covered in the list below. Some of the internal factors are not listed.

` wordname  =  ['] wordname compile
` wordname  =  ['] wordname execute

Block Editor

The core extensions also include a small block editor. This is based on a series of earlier editors, and has a few nice features:

• Blocks are stored in the image
• External tools allow extracting and moving blocks to a new image
• All editing words are vectors allowing more control over the editor

Tip:

Line and column numbers start at 0

Quick Reference: