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
• Java
  • Console
  • MIDP
• .NET (console)
• Adobe AIR

Obtaining

Retro can be obtained as either source code or as a precompiled binary.

For those who just want to get started quickly, the binaries are recommended. They are already built and confirmed to work. The most recent binaries can be obtained from http://retroforth.org/binaries

Those wanting a bit more control, or who use a platform binaries are not offered for will need to build from source. The latest source snapshots (both development and stable) can be found 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

If you get any errors, check the vm/console/retro.c and make sure the LIBS line matches the curses varient on your system.

If you are using NetBSD, you can either change the LIBS to -lcurses or use the following command to build against ncurses:

make LIBRARY_PATH="/usr/pkg/lib" vm

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

Building (Java)

There are two Java implementations. The first, a console based implementation, should work on all common Unix-like OSes. (Due to poor console API support in Java, it does not work on Windows) To build this port, ensure that you have the JDK installed and do:

make java

The second implementation is for MIDP compatible devices. You'll need Ant, the MPP SDK, and the JDK to build it.

cd vm/midp
ant

Before building the MIDP version, you should adjust the paths in build.xml to match your systems configuration.

Building (.NET)

The build process is only tested under Unix-like OSes running Mono. You will likely need to make some changes in the Makefiles to use Microsoft's C# compiler.

make dotnet

Starting Retro

How to start depends on which platform you build for. Enter the bin directory and try one of the following:

# Console
./retro

# .NET
mono retro.exe

# Java
java retro

If you are using the console targets, you can use some command line arguments:

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

The console, java, and mono targets also support one other argument:

--endian

This will convert the image to the host endian format. It may be necessary if you are using an image provided by someone else, or when moving from a java target to one of the others.

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.

By default, cr, lf, and tab are remapped to be identical to space. This can be disabled by typing:

whitespace off

To turn it back on:

whitespace on

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.

Tip:

The JavaScript implementation does not support saving images at this time.

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.

I/O Devices

Retro runs on a portable virtual machine. This machine provides a few I/O devices that can be accessed.

• keyboard
• text display
• graphical canvas
• mouse

Please note that the only target currently supporting the canvas and mouse is javascript.

When talking to an I/O device, set the stack as instructed, then write a value to the port using out. You then wait, and, depending on the device, may read a value back.

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 library/os-specific/osx.retro

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

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.

Tip:

Download a precompiled image from http://retroforth.org/binaries to get all of these preloaded.

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 library/standard/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

Introduction

Retro ships with 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

To load it:

./retro --with library/standard/editor.retro --with library/standard/extend.retro

Tip:

Line and column numbers start at 0

The Words

Introduction

Retrospect is a debugging aid. It provides a decompiler, memory dumper, and other tools that may prove useful in better understanding your code and the compiler.

To load it:

./retro --with library/standard/retrospect.retro --with library/standard/extend.retro

Retrospect requires the extend.retro package to be loaded before it will work.

The Words