FORTH on the Atari: Stacks, New Words, Disk Screens and Hardware Control

FORTH arrived on the Atari early and found a loyal following. It is compact, it compiles to code that runs many times faster than Atari BASIC, and it lets you build the language up yourself, one new word at a time. Antic's "Forth Factory" column ran from 1982, game programmers used it for arcade-speed projects, and at least half a dozen commercial and APX versions competed for buyers. This guide covers the period systems, the core ideas you need to start, how FORTH stores programs on disk, how to reach the Atari's sound, colour and joystick hardware, and what to run today.

What you'll learn: the stack and postfix arithmetic, defining words with : and ;, loops and conditions, disk screens (LIST, LOAD, FLUSH), direct hardware access with C@ and C!, and the differences between Atari FORTHs.

What you need: an Atari or emulator (Altirra or atari800) and a FORTH disk image, such as APX Extended fig-FORTH, valFORTH, X-FORTH or volksFORTH. The examples use only core words that behave the same way in fig-FORTH and its successors. Where implementations differ, the guide says so.

1. The Atari FORTHs

Charles Moore invented FORTH and first used it to control telescopes at the Kitt Peak observatory. Most Atari FORTHs are built on fig-FORTH, the model implementation distributed by the FORTH Interest Group (FIG) of San Carlos, California.

System Publisher, year Notes
QS FORTH Quality Software, 1981 By James Albanese; one of the first two Atari FORTHs on the market
pns-FORTH Pink Noise Studios Used by Antic's first "Forth Factory" turtle-graphics series (1982); includes PLOT and DRAWTO words
Extended fig-FORTH APX, 1981 By Patrick L. Mullarky; tape and disk (APX-10029/20029). A second version signs on as fig-FORTH 1.1
valFORTH Valpar International, 1982 Based on fig-FORTH, by Evan Rosen and Stephen Maguire; sold in modules, with Atari-specific words, a screen editor, a character set editor and player graphics support
ES-FORTH English Software (UK), 1984 Tape and disk
fig-FORTH Pulsar Software (UK), 1988 A late British release

APX also sold FORTH Turtle Graphics Plus, and Atari's own coin-op division used an in-house FORTH. A column reprinted in The Creative Atari (1983, edited by David and Sandy Small) found QS FORTH hard to follow and more generic than Atari-specific, and praised valFORTH for its commands designed for the Atari's hardware. That difference still matters: core words are portable, Atari words are not.

2. The stack and postfix arithmetic

FORTH keeps its working numbers on a stack. Typing a number pushes it; an operator pops its inputs and pushes the result. The word . (dot) pops the top number and prints it. Type this at the ok prompt and press RETURN:

2 3 + 4 * .

FORTH prints 20. The 2 and 3 are pushed, + replaces them with 5, 4 is pushed, * leaves 20, and . prints it. This is reverse Polish notation, so there are no brackets: (3+5)×(4−2)−7 becomes 3 5 + 4 2 - * 7 -.

Numbers on the stack are 16-bit cells. A handful of words rearrange the stack:

Word Stack effect Meaning
DUP ( n -- n n ) copy the top item
DROP ( n -- ) discard it
SWAP ( a b -- b a ) exchange the top two
OVER ( a b -- a b a ) copy the second item to the top
ROT ( a b c -- b c a ) rotate the third item to the top

The notation in brackets is the standard way to document a word: what it expects before the --, and what it leaves after. Get into the habit of writing it as a comment, because in FORTH ( is itself a word that skips text up to the next ). It needs a space after it.

3. Defining new words

A colon definition adds a word to the dictionary:

: SQUARE ( n -- n*n )  DUP * ;
7 SQUARE .

That prints 49. : starts compiling, SQUARE is the new word's name, and ; ends the definition. From then on SQUARE is as much a part of the language as +. Words can use other words, and that's how FORTH programs grow: small, testable pieces combined into bigger ones.

Loops and decisions only work inside definitions:

: STARS ( n -- )  0 DO 42 EMIT LOOP ;
5 STARS

DO takes a limit and a starting index. Here it counts from 0 up to, but not including, 5. EMIT prints the character with code 42, which is *. Inside a loop, I pushes the current index:

: COUNTUP ( n -- )  1+ 1 DO I . LOOP ;
5 COUNTUP

That prints 1 2 3 4 5. Comparisons such as =, < and > leave a flag (non-zero for true), which IF ... ELSE ... THEN consumes. fig-FORTH also accepts ENDIF for THEN. BEGIN ... UNTIL repeats until a flag is true.

Constants and variables. 10 CONSTANT TEN creates a word that pushes 10. A variable pushes its address. You read it with @ and write it with !. Here is a portability trap: in fig-FORTH and the systems based on it, VARIABLE takes an initial value from the stack (0 VARIABLE SCORE). Newer systems may define it differently, so check your FORTH's glossary.

Mistakes. Redefining a word just makes the new version win; FORTH may warn "not unique". FORGET name removes a word and everything defined after it.

4. Talking to the hardware

The words C@ (fetch a byte) and C! (store a byte) give you the equivalent of BASIC's PEEK and POKE, at machine speed. They work in every Atari FORTH, so they are the safest way to reach the hardware. Two examples you can type straight in:

0 710 C!
632 C@ .

Location 710 is COLOR2, the background colour of the text screen, so the first line turns it black. Location 632 is STICK0, the first joystick. It reads 15 when the stick is centred and other values for the eight directions.

A sound example from Antic (July 1983) shows how much clearer this gets once you name things. It waits for the START key, then sweeps a tone:

: WAIT  BEGIN 53279 C@ 6 = UNTIL ;
: TONE  168 53761 C!  201 10 DO I 53760 C! LOOP ;
: SWEEP  WAIT TONE ;

53279 is CONSOL, which reads 6 when only START is held. 53761 is AUDC1: 168 means pure tone (distortion 10) at volume 8. 53760 is AUDF1, the pitch of voice 1, here stepped from 10 to 200. The loop runs so fast that the sweep is hard to hear. Put a delay inside the loop to hear it properly, and silence the voice afterwards with 0 53761 C!. (For the meaning of these sound registers, see POKEY Sound Basics.)

Atari-specific words. Most Atari FORTHs added words like GR., SETCOLOR, PLOT, DRAWTO and SOUND, but their stack order varies. In one implementation documented in FORTH on the Atari: Learning by Using (1983), PLOT takes x, y and colour, and SETCOLOR takes luminance, hue and register in an order unlike BASIC's. Read the glossary of the FORTH you're using before borrowing graphics code from a book or magazine.

5. Screens: how FORTH stores programs

Classic FORTHs don't save named files. Instead the disk is treated as numbered screens (also called blocks), each holding one page of source text: 16 lines. The line width depends on the implementation. The 1983 book above uses 32-character lines, while Extended fig-FORTH's screens are wider. You edit a screen in the FORTH's screen editor, then compile it.

Word Use
n LIST show screen n
n LOAD compile screen n into the dictionary
--> at the end of a screen: continue loading with the next screen
FLUSH write changed screens back to disk
n1 n2 INDEX show the first line of each screen in the range

By convention, line 0 of each screen is a comment naming the contents, the date and the author, so INDEX gives you a catalogue. The editor itself is usually loaded from screens too. On Extended fig-FORTH, for example, it's 21 LOAD. Each system's editor commands differ, so keep its manual handy.

Screens live in raw disk sectors, not DOS files, and the fig-FORTH systems have no way to read DOS files into screens. Keep separate disks for FORTH screens and DOS files. Some later systems, such as X-FORTH and volksFORTH, can also compile ordinary DOS text files with INCLUDE" D1:MYFILE.FS".

6. FORTH today

  • Emulators: load a FORTH ATR in Altirra or atari800. You can paste text into the emulator to enter long definitions, which saves a lot of retyping of old magazine listings.
  • Collections: the AtariAge user cas gathered all the known Atari FORTH systems, with disk images and their source screens, on wiki.strotmann.de. The Forth page on atariwiki.org also has an extensive collection.
  • X-FORTH and volksFORTH are the two modern systems most often recommended. X-FORTH is the leaner of the two; volksFORTH adds multitasking, a transient assembler and heap management, and both can read DOS files.
  • Cross-editing: forum users have written small scripts that pack a modern text file into a fig-FORTH screen disk, so you can write in a PC editor and LOAD on the Atari.
  • Learning: Leo Brodie's Starting FORTH is still the best introduction. Thom Cherryhomes also recorded a series of fig-FORTH video tutorials on the Atari.

Troubleshooting

  • ? or "not found" after a word. You typed it before defining it, or misspelled it. FORTH words are space-delimited: 2 3+ is not the same as 2 3 +.
  • "Stack empty" or strange numbers. A word consumed more than you pushed, or left extra items behind. Test each word on its own and check its stack comment.
  • Loop words rejected at the prompt. DO, IF and BEGIN are compile-only in most FORTHs. Wrap them in a : ... ; definition.
  • Edits lost after a reboot. You didn't FLUSH the screens to disk.
  • Graphics code from a book does nothing. Its PLOT/SETCOLOR stack order is for a different FORTH. Rewrite it with that system's words, or use C! to the hardware directly.

Further reading

  • Leo Brodie, Starting FORTH (Prentice-Hall).
  • E. Floegel, FORTH on the Atari: Learning by Using (Ing. W. Hofacker / ELCOMP, 1983).
  • Antic, "Forth Factory" column, from August 1982, including Gordon Smith's two-part turtle graphics series; Thomas McNamee, "Why Go Forth?", Antic, July 1983.
  • David Small, Sandy Small and George Blank (eds.), The Creative Atari (1983), chapter "Atari Languages".
  • On this site: POKEY Sound Basics, Atari Logo Basics for turtle graphics.

Credits