trs80basic

Semigraphics drawn with SET on the 128x48 grid — programs/demos/demo_graphics.bas.

The simulated 64x16 screen: answer MEMORY SIZE?, type a program, RUN it.

A TRS-80 Model I/III LEVEL II BASIC interpreter — the 1978 Radio Shack dialect, with its 64x16 screen and semigraphics, cassette (CLOAD/CSAVE as text files, SYSTEM for object files), Disk BASIC file I/O, and an OLLAMA channel for talking to a local LLM from BASIC. It runs .bas listings interactively at a READY prompt or non-interactively from a script. It is a single GNU awk script with no build step; it writes only the files your BASIC program tells it to.

• Why awk??
  A. It's funny, and there's an inside joke about it.
  B. I wanted to see if Claude could deal with such a ridiculous request. Its first pass included everything I had asked for, which was probably around 90% of BASIC.

• Does it run Dancing Demon?
  Yes, including the embedded machine language and sound.

• What platforms are supported?
  Developed and tested on MacOS (iTerm2), untested but probably works fine under Linux. No Windows support right now, but that'll be added at some point.

• Embedded machine language. USR routines execute for real through the companion Z80 core, whether POKEd into memory, packed into strings, or carried as fake BASIC lines in a tokenized image. Video they write appears as they run, the keyboard is live, and their cassette-port sound plays (sound on) or records to a WAV file.
• Whole machine-language programs. SYSTEM is the Level II monitor: *? takes the name of a SYSTEM tape or a /CMD load module (a host file, as CLOAD reads listings), / runs it at its entry address, /nnnnn anywhere. The program owns the screen and keyboard until it returns or jumps back to READY. The core's assembler writes both formats.
• A memory map programs can PEEK and POKE: the tokenized program at 42E9H, display memory, the system variables and pointers, the BREAK and driver vectors, and VARPTR string aliasing for the magazine string-packing tricks.
• Tokenized images load directly. CLOAD, LOAD and ./basic IMAGE.BAS read the binary files most archives hold, keeping every byte.
• Ollama integration. OPEN "O",1,"OLLAMA:llama3.2" turns a file channel into a conversation with a local LLM; @TOKENS pins the reply's first line to one of a list of words so a program can branch on it; named threads persist between runs.
• Metacommands, lowercase so they never collide with BASIC: dir, cat, history, speed, sound, fullscreen, ext, man, help.
• Man pages. man PRINT gives the syntax and an example for any BASIC keyword; help <text> searches them.
• Shell-style line editing. Left/right arrows move through the line, up/down recall history, Ctrl-A/Ctrl-E/Ctrl-U work as in a shell, TAB completes filenames, and PgUp/PgDn page long output.
• The 64x16 screen with semigraphics drawn in Unicode sextants (braille or ASCII if your font lacks them), plus optional color for SET.
• Period pacing. speed 1.77408 runs a game at the Model I's clock rate.
• Disk BASIC file I/O, sequential and random-access.
• Batch mode for scripts. ./basic prog.bas reads INPUT from stdin, puts BASIC errors on stderr and exits 0, 1 or 2.

None of these is needed to run programs. Arguments are documented under Python tools and, for run_examples.sh, Commands and arguments.

• GNU awk 5.0 or later (gawk). The awk that ships with macOS and many Linux distributions is not GNU awk: brew install gawk, or apt install gawk.
• macOS or Linux with the standard sh, stty, dd, od and ls (interactive mode uses them for the raw keyboard and TAB completion), and a terminal of at least 64x20 for the screen grid.

Everything else is optional, needed only for the feature named:

gawk --version | head -1                        # needs GNU awk >= 5.0 (and python3 for the optional Z80 core)
./basic --seed 1 programs/examples/hilo.bas < programs/examples/hilo.in   # <1s — runs a program, prints its screen text
./basic                                         # interactive READY prompt; type BYE to leave
programs/examples/run_examples.sh               # ~5s — every example against its checked-in transcript, all "ok"

Inside the interpreter, man <keyword> documents any BASIC word (e.g. man PRINT), help meta lists the metacommands, and help keys the key bindings. docs/USER_GUIDE.md is the full manual — the extensions (color, OLLAMA, the simulated machine) live there.

Runs the interpreter. With a file, LOADs and RUNs it non-interactively and exits; without one, starts the interactive prompt. Writes: nothing on its own. Whatever the BASIC program OPENs, CSAVEs or SAVEs lands relative to your current directory, not the repo.

Exit status: 0 clean run, 1 uncaught BASIC error (also printed to stderr as ?SN ERROR IN 40), 2 bad invocation or unreadable file. Running out of stdin while a program is at INPUT is a BASIC error (?BATCH: END OF INPUT). Batch mode also has no raw keyboard: INKEY$ reads whole lines from stdin instead of single keypresses, so a program whose menu is an INKEY$ loop cannot be played with ./basic game.bas — your keys echo and it never leaves the loop. Play it interactively instead: ./basic, then CLOAD "game.bas" and RUN.

Note: --screen and the fullscreen metacommand are near-opposites despite the similar names — --screen keeps the 64x16 grid's control codes in batch output, while fullscreen on abandons the grid for streamed output.

Environment variables the interpreter reads:

(A couple of development-only variables are deliberately undocumented here.)

Runs every programs/examples/*.bas with --seed 1 and its .in file, in a scratch directory, against the OLLAMA stub, and diffs against the checked-in .out. Writes: nothing, unless --update, which rewrites the .out files.

Start with the User Guide. It is the full manual: keys and metacommands, loading and batch mode, the extensions (color graphics, Disk BASIC files, the OLLAMA channel, the simulated machine), every place this interpreter differs from the ROM, and a reference entry for each BASIC keyword. What follows here is the short version.

Run a listing. ./basic game.bas. Text the program prints appears on stdout; BASIC errors on stderr; the exit status says how it ended. Feed INPUT from stdin (printf '5\n10\n' | ./basic game.bas). A good result is exit 0 and the transcript you expected. Wrap in timeout 30 if the program might loop forever — there is no built-in guard.

Work interactively. ./basic with no file gives the READY prompt. Type BASIC directly, CLOAD "game.bas" to load one (LOAD is the Disk BASIC spelling; LOAD "f",R also runs it and keeps file channels open), RUN, Ctrl-C to break, CONT to resume, BYE to leave. The screen is the real 64x16 grid; long output pages with PgUp/PgDn.

Run with the Z80 core. A listing whose USR routines matter needs the companion core, trs80_z80_core, checked out beside this repo. The launcher finds it there by itself, so this is enough:

git clone https://github.com/davidscan/trs80_z80_core ../trs80_z80_core   # once, beside this checkout
TRS80_MHZ=1.77408 ./basic game.bas          # paced to the Model I clock

TRS80_Z80 names the core command explicitly when it lives elsewhere (TRS80_Z80="python3 /path/to/core.py"), and TRS80_Z80= (empty) runs without a core even when one is beside the checkout. Set TRS80_MHZ, or the speed metacommand, or a long routine runs as fast as Python goes. A routine's sound, the cassette-port pulses the machine played through an amplifier, is heard with sound on at the prompt (or TRS80_SOUND) and kept with sound wav out.wav; it is machine code only, so BASIC's own OUT 255 stays silent. The routine then executes against the same memory PEEK and POKE see, video it writes appears while it runs, the keyboard matrix is live, and Ctrl-C still breaks. The core serves three documented ROM entry points (01C9H CLS, 0A7FH argument to HL, 0A9AH HL to result); a call anywhere else in ROM space is a ?FC with the address on stderr, since no ROM is shipped. Without the variable nothing changes: USR is the argument-returning stub described under "Not supported".

Load an archived program. Most TRS-80 programs found online are tokenized images (binary, first byte 0xFF). Since 2026-09-12 CLOAD, LOAD, MERGE and ./basic IMAGE.BAS read them directly: every line's original bytes are kept and imaged at 42E9H exactly as the file holds them, so a machine-language payload stored as fake BASIC lines survives intact, while LIST shows the detokenized text. The loader is one-way — CSAVE and SAVE write text — and a line you retype, DELETE, NAME or overwrite with a text MERGE becomes text again. detok.py remains the tool for reading an image outside the interpreter:

./basic IMAGE.BAS                              # runs the image as it is
python3 tools/detok.py --check IMAGE.BAS       # is it tokenized?
python3 tools/detok.py -s -o listings/ IMAGE.BAS   # a text copy to read or edit

Talk to a model. This needs a running Ollama server with a pulled model on your machine — installing and managing those is outside this project. OPEN "O",1,"OLLAMA:llama3.2" opens a chat channel; PRINT #1 lines build the prompt, LINE INPUT #1 sends it and reads the reply line by line until EOF(1). programs/examples/oracle.bas is a complete program; man OLLAMA has the directives (@TOKENS, @THINK, @KEEPALIVE).

Worked example — the examples directory. Each program demonstrates one area and runs as a fixture:

run_examples.sh prints ok per program. If one prints FAIL and a diff, either the interpreter's behavior changed or the example did; decide which before --update.

• Before --update on the examples: read the diff. The transcripts are the specification of current behavior; updating them silently accepts a change.
• After detok.py: skim the listing for ?-marked bytes or lines that do not start with a number. --check first tells you whether the file is an image at all; a plain-text file passed to detok is not damage, it is already a listing.
• TRS80_EXT: leave it off unless a listing fails with ?SN on a bare INPUT or a DIM of a scalar. Turning it on makes the interpreter accept what real Level II would not.

• Relative paths belong to the program. You might expect OPEN "I",1,"DATA.TXT" to look next to the .bas file; actually it resolves against your current directory, because the interpreter never changes directory. Run from where the program's data is, or call basic by absolute path.
• Batch output has no graphics, and no color anywhere but the grid. You might expect SET to show up in ./basic prog.bas output; actually only printed text is streamed, because the screen grid is not rendered without a terminal. --screen keeps the control codes; interactive mode shows the picture. SET(x,y,c) color renders only in the interactive grid, and POINT reports lit/unlit regardless of color.
• Printing scrolls the picture. You might expect POINT to read back what SET drew; actually any PRINT that reaches the bottom line scrolls the whole screen, pixels included — read before you print, or use PRINT@ to place text.
• FORX is an identifier. You might expect FORX=1TO10 to work as on the real machine; actually it is one variable name, because this interpreter lexes text greedily. detok.py -s inserts the spaces from the token stream.
• Metacommands are lowercase. dir, man, help, fullscreen are metacommands; DIR or MAN reach BASIC and give ?SN ERROR. This keeps the two namespaces apart.
• LOF is for random files only. On a sequential channel it raises ?BM; use LOC(n) for lines read or written.
• ERR is not the error code. As on the real machine, ERR/2+1 is the code (1 = NF, 2 = SN, 11 = /0, 54 = FF: the file errors carry Disk BASIC's own numbers, 51-70). man ERR lists them.
• A program can disable BREAK, as on the real machine, with POKE 16396,23 (or 175, 165); POKE 16396,201 re-enables it. Press Ctrl-C three times in a row to break anyway.
• Ctrl-C is BREAK, not exit. It stops the program and returns to READY; BYE leaves.
• A named OLLAMA thread persists. OPEN "O",1,"OLLAMA:llama3.2:story" writes story.ollama in the current directory and reloads it as conversation context next time; KILL "story.ollama" forgets it.

There is no undo. The interpreter only writes what a program tells it to (OPEN "O"/"E"/"R", CSAVE, SAVE, KILL, OLLAMA thread files), always under your current directory. KILL deletes without confirmation. Run unfamiliar programs from a scratch directory. run_examples.sh --update overwrites .out files; git diff shows exactly what changed.

• printf 'ANSWER\n' | ./basic prog.bas scripts any INPUT; a heredoc does the same for many.
• ./basic prog.bas > run.txt 2> errors.txt separates the transcript from BASIC errors.
• help <text> searches the keyword documentation; man needs the exact word.
• speed 1.77 (or TRS80_MHZ=1.77) slows a game to the original machine's pace.
• sound on plays a USR routine's cassette-port sound through the core; sound wav f.wav records it.
• TRS80_GFX=ascii works on every terminal, including the raw Linux console.
• The interactive grid needs a terminal of at least 64x20.

• Machine code without the companion core. USR routines run only with the Z80 core, trs80_z80_core, checked out beside this repo or named by TRS80_Z80 (PROTOCOL.md is the contract). Without it USR returns its argument, and a run that called USR ends with one stderr line naming the entry addresses that were not executed, so a routine that silently did nothing is never mistaken for one that worked (TRS80_USR=strict turns the calls into ?FC).
• Native Windows (cmd/PowerShell) — not yet: the no-install Windows package returns once it can be tested on a local Windows machine. Meanwhile run it under WSL + Windows Terminal, which is fully compatible, semigraphics included.
• Reading OCR-damaged listings — that is a different problem (repair, not conversion) and lives in a separate project.

Standalone helpers for program files and the documentation; the interpreter itself does not need them.

Converts tokenized cassette/disk images (binary, first byte 0xFF) into the text listings this interpreter reads. Writes: DIR/<name>.bas per input with -o; otherwise to stdout.

The inverse: a text listing back to a tokenized image. Writes: DIR/<name>.bas with -o, else stdout.

Regenerates Part V of docs/USER_GUIDE.md from support/manpages.txt, so the guide's keyword reference always matches what man shows. Run it after any manpages edit. Writes: the region between the generated-reference markers in docs/USER_GUIDE.md; nothing else.

Three things here are generated and should never be hand-edited: trs80basic.awk (rebuild with cat src/p*.awk > trs80basic.awk), Part V of docs/USER_GUIDE.md (python3 tools/make_userguide.py) and the .out transcripts under programs/examples/ (run_examples.sh --update). The rest is source. The only file the interpreter writes into your working directory while it runs is an .ollama thread.

Copyright (c) 2026 David Forbis. GNU General Public License v3.0 — see LICENSE. Distributed WITHOUT ANY WARRANTY.

This is an independent, from-scratch reimplementation of LEVEL II BASIC's behavior. The language follows the published Radio Shack LEVEL II BASIC Reference Manual (1978) and the TRSDOS & Disk BASIC Reference Manual, used as functional specifications. Machine-level details (memory addresses, system variables, the RND generator) come from period ROM reference books and magazines, trs-80.com, and a published ROM disassembly (for the RND generator); period program listings served as test cases. The repository contains no ROM code, no disassembly text, no Microsoft or Tandy source, and no text of the manuals. TRS-80, Radio Shack and Tandy are trademarks of their respective owners, used only to describe compatibility; this project is not affiliated with or endorsed by them. Programs under programs/ are original to this project.