Semigraphics drawn with SET on the 128x48 grid — programs/demos/demo_graphics.bas.
The simulated 64x16 screen: answer MEM 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, and a program
can write or KILL files only inside the directory it was started in (an
absolute path or a .. component is ?FD ERROR there; reading is not
confined, and names you type at the READY prompt are your own).
-
Why awk??
A. It's funny. It's stupid. It's unique.
B. I wanted to see if Claude could deal with such a ridiculous request. Its first pass included everything I had initially 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 on macOS (iTerm2); the test suite also runs on Linux in CI on every push. No Windows support right now, but that'll be added at some point.
- Embedded machine language.
USRroutines 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.
SYSTEMis the Level II monitor:*?takes the name of a SYSTEM tape or a /CMD load module (a host file, asCLOADreads listings),/runs it at its entry address,/nnnnnanywhere. 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
PEEKandPOKE: the tokenized program at 42E9H, display memory, the system variables and pointers, the BREAK and driver vectors, andVARPTRstring aliasing for the magazine string-packing tricks. - Tokenized images load directly.
CLOAD,LOADand./basic IMAGE.BASread 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;@TOKENSpins 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,memory,spaced,renum,ext,man,help,version,exit. - Man pages.
man PRINTgives 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.77408runs a game at the Model I's clock rate. - Disk BASIC file I/O, sequential and random-access.
- Batch mode for scripts.
./basic prog.baspiped, or--batch, readsINPUTfrom stdin, puts BASIC errors on stderr and exits 0, 1 or 2. At a terminal the same command plays the program on the screen.
None of these is needed to run programs. Arguments are documented under
Python tools and, for run_examples.sh,
Commands and arguments.
| script | what it does |
|---|---|
tools/detok.py |
converts a tokenized cassette or disk image into a text listing you can read or edit |
tools/tok.py |
converts a text listing back into a tokenized image; --round-trip checks that a conversion loses nothing |
tools/make_userguide.py |
regenerates the keyword reference in docs/USER_GUIDE.md from support/manpages.txt, so the guide matches man |
programs/examples/run_examples.sh |
runs every example program and compares its output with the checked-in transcript |
programs/tests/run_all.sh |
runs the whole test suite with one exit status, as CI does on every push |
programs/tests/transcripts.sh |
runs the READY-prompt transcripts programs/tests/t*.txt and compares each with its checked-in .out (part of run_all.sh) |
programs/tests/ollama_stub.sh |
returns canned Ollama replies, so OLLAMA programs run without a server (via TRS80_OLLAMA_CURL) |
programs/tests/z80_stub.py |
a minimal stand-in for the Z80 core that the USR protocol tests run against |
- GNU awk 5.0 or later (
gawk). Theawkthat ships with macOS and many Linux distributions is not GNU awk:brew install gawk, orapt install gawk. - macOS or Linux with the standard
sh,stty,dd,odandls(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:
| dependency | needed for | without it |
|---|---|---|
python3 (standard library only) |
the Z80 core and the scripts in tools/ |
no USR execution; no tools |
timeout (GNU coreutils; brew install coreutils on macOS) |
programs/examples/run_examples.sh, and the timeout 30 tip under Workflow |
every example reports FAIL |
a checkout of trs80_z80_core beside this repo |
running USR machine code |
USR returns its argument, and the run ends with a stderr line naming the routines that did not execute |
a sound player: ffplay (part of FFmpeg), else ffmpeg on macOS, aplay or pw-play |
hearing machine-code sound live (sound on) |
no live sound; sound wav out.wav still records it |
curl and a running Ollama server with a model pulled |
the OLLAMA channel |
reading a reply raises ?FD |
| a terminal font with the Unicode "Symbols for Legacy Computing" block | semigraphics drawn as sextants | set TRS80_GFX=braille or TRS80_GFX=ascii |
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 exit (or BYE, EXIT) to leave
programs/examples/run_examples.sh # ~15s — 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 and exits: at a
terminal (stdin and stdout both) it is played on the screen with the live
keyboard and no MEM SIZE?, and when the program ends its last screen
stays up until you press a key; piped, or with --batch, it runs
non-interactively. Without a file, starts the interactive prompt. An option that takes a
value also accepts --option=value. Writes: nothing of its
own, only what the program or your settings name (see Undo / recovery). Whatever the BASIC program OPENs, CSAVEs or SAVEs lands relative to
your current directory, not the repo.
| argument | default | what it does | when you'd use it |
|---|---|---|---|
program.bas |
none (interactive) | LOAD + RUN it, then exit 0/1/2. At a terminal it is played on the screen (EXT): the grid, the live keyboard, no MEM SIZE?; at the end the last screen stays up until a key, and any error is said again on the terminal once the screen is gone; piped, or with --batch, it is a batch run |
playing a listing straight from the shell; scripting, tests, piping INPUT answers from stdin |
game.cmd |
EXT: a /CMD load module is SYSTEM, its name, /: loaded and run at its entry address (machine code needs the Z80 core). At a terminal it is played on the screen with the live keyboard and no MEM SIZE?, and the last screen stays up until a key; piped, or with --batch, it is a batch run. Either way it exits 0/1/2 when the code ends (READY, or an error such as ?FC at a ROM call the core does not serve) |
starting a machine-code game straight from the shell | |
--seed N |
time-based | N is an integer (negative allowed); seeds the random generator, so RND and every RANDOM repeat run to run (each RANDOM draws a fresh 0-127 seed byte from it, as the machine's 7-bit R register does) |
repeatable runs, transcripts you can diff |
--memsize N |
65535 | answers MEM SIZE? with N (17280-65535), in batch and at the prompt; cannot be combined with --memory host |
a program that only ran on a 16K machine: it POKEs an address byte it made signed (IF H>127 THEN H=H-256), which is ?FC above 32767 on the hardware too; --memsize 32767 is that machine |
--clear N |
none (string space stays 50 bytes) | types CLEAR N before RUN (after LOAD in batch, at the first READY at the prompt); N is 0-32767, or any count with --memory host |
a listing that stops with ?OS ERROR: it was written for a machine where CLEAR 1000 had been typed before RUN, outside the listing. The program's own CLEAR n still wins, and FRE("") reports the space |
--memory host |
rom (the machine) |
EXT: lifts the machine's capacity limits at once: the 64K behind MEM/?OM, CLEAR n string space (?OS), the 255-character string and its counts (?LS), subscripts, DIM bounds and CLEAR counts past 32767, the 255-byte INPUT# cut and the 240-byte piped line; and every character of a variable name counts (SUM and SU are two variables, where the machine folds them into one). PEEK, POKE, VARPTR and USR keep the 64K machine. Also TRS80_MEMORY=host, the memory metacommand, or REM META: memory host under ext on |
new code written for this interpreter rather than for the machine: a program whose tables or prose would never fit a TRS-80 |
--steps N |
none (no limit) | EXT: stops the program file's run after N BASIC statements (every one dispatched, the typed RUN and a statement behind THEN or ELSE included, and a USR routine's time in the core at a statement per 1,000 cycles, so a routine that never returns stops too), with STEP LIMIT IN n on stderr and exit 3. The run ends at the same statement every time, whatever the machine's speed or load; no program can see the count |
comparing the output of a program that never halts (a demo, an attract loop) from run to run, where a wall-clock timeout cuts it at a different place each time |
--steps-report FILE |
none | EXT: when the run ends (any exit), writes the number of statements it ran to FILE, one line, written fresh; with --steps the count stops at N. The program's output is untouched; FILE is checked before the run, and one that cannot be written is exit 2 |
measuring a run's path: a change that sends a program another way and prints the same text moves the count |
--clock steps |
host (the host's clock) |
EXT: TIME$ and the clock bytes 4041H-4046H (PEEK(16449)-PEEK(16454)) read the machine's own time from the statement count: 01/01/80 00:00:00 at the RUN, then a second per 1,774 statements (1,000 cycles a statement at 1.77408 MHz; a USR routine's cycles count as --steps counts them). Needs a program file |
a program that times itself or waits for the clock (a benchmark, a clock display) prints the same on every run |
--batch |
off | run the file as a batch run even at a terminal | a test or a transcript taken at a terminal |
--screen |
off | keep the TRS-80 cursor/screen control codes in batch output | capturing what the 64x16 screen looked like rather than a text transcript |
-- |
end of options | a program file whose name starts with - |
|
-h, --help |
usage and exit status meanings | ||
--version |
prints the release, trs80basic v2.4.0, and in a git checkout the exact build behind it (v2.4.0-3-gabcdef0, -dirty with edits) |
pinning which interpreter a program or a test baseline was built against; the version metacommand says the same at the prompt |
Exit status: 0 clean run, 1 uncaught BASIC error (also printed to
stderr as ?SN ERROR IN 40), 2 bad invocation, an unreadable file, or
a source line the loader skipped (?FD ERROR - FILE LINE n): the program
does not run, 3 the --steps limit stopped the run.
Behind two of those errors batch mode adds one basic: line on stderr:
?OS with string space never CLEARed names --clear, and ?OV at a
CLEAR MEM-n on the 64K map names --memsize 32767; and behind a limit
that --memory host lifts (?OM, a subscript or DIM past 32767, ?LS,
a string count past 255) the note names that option. The message, the
output and the exit status are the machine's; the prompt shows the
message alone.
Running out of stdin while a program is at INPUT stops the run
(?BATCH: END OF INPUT, exit 1). Batch mode also has no raw keyboard:
INKEY$ takes one line of stdin at a time and hands it out one character
per call, then CHR$(13) for the ENTER; an INPUT reads the next line
whole and drops what INKEY$ left of its line. A menu that is an INKEY$
loop can therefore be scripted (printf 'AB\nC\n' | ./basic game.bas),
but when stdin runs out inside such a loop the run ends silently with
exit 0, which a test can mistake for a clean finish (TRS80_REACH_DIAG=1
adds a stderr note). To play such a program with live keys, run it at a
terminal without --batch.
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:
| variable | default | what it does | when you'd use it |
|---|---|---|---|
TRS80_GFX |
Unicode sextants | braille or ascii for the semigraphics glyphs |
your terminal font lacks the "Symbols for Legacy Computing" block |
TRS80_DUMB |
unset | 1 (or any value but 0) forces plain streamed output even on a terminal |
logging a session, or a terminal that can't do the 64x16 grid |
TRS80_MHZ |
full speed | throttle execution to a period-correct feel (also speed metacommand) |
games that are unplayable at modern speed |
TRS80_PRINTER |
unset (discard) | file that LPRINT/LLIST append to; a path that cannot be written is ?FD at the first one |
you want the printer output |
TRS80_EXT |
0 |
1 (or any value but 0, as for TRS80_DUMB) accepts a few forms real Level II rejects (INPUT "prompt",var, a prompt expression such as INPUT "A"+B$;X, text typed at a no-variable INPUT) and lets a program's REM META: remarks fire (speed, fullscreen, memory, spaced); also ext on |
running listings that use those idioms; leave off to keep strict ?SN behavior |
TRS80_MEMORY |
unset (rom) |
host lifts the machine's capacity limits, as --memory host does (EXT); --memory overrides it, and the memory metacommand switches it at the prompt |
new code written for this interpreter rather than for the machine |
TRS80_SPACED |
unset | 1 (or on) makes LIST and LLIST show a blank around each keyword, FOR I=1 TO 3 where the machine lists the stored FORI=1TO3; display only, also the spaced metacommand |
reading a compressed listing loaded from a tokenized image |
TRS80_MANFILE |
support/manpages.txt next to basic |
where man reads its text |
only if you relocate the file |
TRS80_OLLAMA_MODEL |
none | default model for OPEN "OLLAMA" when the name gives none |
every OLLAMA program without a hard-coded model |
TRS80_OLLAMA_HOST |
localhost:11434 |
the Ollama server | Ollama on another machine |
TRS80_OLLAMA_TIMEOUT |
300 |
seconds to wait for a reply | slow models |
TRS80_OLLAMA_THINK, TRS80_OLLAMA_KEEPALIVE |
unset | defaults for the @THINK / @KEEPALIVE directives |
thinking models; keeping a model loaded between calls |
TRS80_OLLAMA_CURL |
unset | replaces the curl command (test hook) |
deterministic tests with programs/tests/ollama_stub.sh |
TRS80_KMHOLD |
100 ms at a terminal; 4 polls in batch |
how long one keypress "holds" its key on the keyboard matrix (PEEK of 14336-15359, machine code) on a terminal that sends no key-up events; milliseconds when gawk's time extension loads, polls otherwise |
a period game reads your taps as too long or too short |
TRS80_KPSTUCK |
2 s |
under the key-release protocol, how long with no keyboard event at all before every held key is let go (a release that never arrived: the window lost focus mid-hold) | the pty test stretches it on a slow CI runner; otherwise leave it |
TRS80_KBPROTO |
on at a terminal | 0 turns off the key-release protocol. On a terminal that implements the kitty keyboard protocol (iTerm2, kitty, WezTerm, Ghostty, foot) the matrix gets real key-down and key-up: a key is held exactly as long as your finger, chords work, and there is no gap before auto-repeat. 1 keeps it on under TRS80_DUMB |
a game misbehaves and you want the plain byte-stream keyboard back |
TRS80_USR |
unset | strict makes every USR call raise ?FC instead of returning its argument |
a sweep that must fail visibly on machine code it cannot run |
TRS80_USR_TRACE |
unset | 1 prints one stderr line per USR call (USR slot=0 entry=28672 arg=42); 2 adds the memory frame sent to the core (the whole map the first time, the changed bytes after) |
finding out why a routine did not do what you expected |
TRS80_Z80 |
a core beside this checkout, else none | the command that runs the companion Z80 core; USR routines then execute (see PROTOCOL.md). Unset, the launcher uses ../trs80_z80_core/core.py when it exists; empty (TRS80_Z80=) means no core. An assignment prefix (FOO=1 python3 core.py) or a compound command (cd /x && ...) works too; a hung core behind a compound command can outlive the session |
running listings with embedded machine code, or keeping them off |
TRS80_Z80_TIMEOUT |
5000 |
milliseconds to wait for each reply from the core before giving up on it | a slow machine, or debugging the core |
TRS80_SOUND |
unset | player command for the machine-code sound a USR routine makes on port 255, fed raw 16-bit mono PCM by the core; auto picks the first installed player: ffplay, then ffmpeg on macOS, aplay, pw-play; also sound on |
hearing a sound routine as the machine played it |
TRS80_SOUND_WAV |
unset | file the core writes that audio to, emulated time only; also sound wav <path>. The file starts over with each session and each sound wav, and carries on across the core restarts inside one (speed, sound on) |
keeping a recording, or checking pitch without speakers |
TRS80_SOUND_RATE |
22050 |
the sample rate for both | 44100 for a finer file |
TRS80_WINNATIVE |
probed (COMSPEC set and SHELL not) |
0/1 overrides the native-Windows detection that routes system() calls to cmd.exe (test hook) |
exercising the other platform's branches |
TRS80_REACH_DIAG |
unset | 1 adds a batch stderr note when a run ends at a key poll on exhausted stdin — a clean exit whose END was never reached (test hook for reachability sweeps) |
telling those runs apart in a sweep |
(One internal variable, which the interpreter sets for the core, is 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.
| argument | default | what it does | when you'd use it |
|---|---|---|---|
--update |
off | regenerate the transcripts instead of checking them | after a deliberate change to an example or to output formatting — read the diff first |
Pipes each programs/tests/tN.txt into the READY prompt from the repo root,
with --seed 1, plain output and the OLLAMA and Z80 stubs, and diffs what it
printed (its exit status last) against tN.out; the ls -l line that dir
prints is cut to the file name. Every t1 to tN must exist. Writes:
the files the transcripts themselves create and remove, and nothing else,
unless --update, which rewrites the .out files.
| argument | default | what it does | when you'd use it |
|---|---|---|---|
--update |
off | regenerate the .out files instead of checking them |
after a deliberate change to a transcript or to output — read the diff first |
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, exit (or BYE) to leave. The screen is
the real 64x16 grid; long output pages with PgUp/PgDn. A letter you type
reaches a running program's INKEY$ and INPUT in the machine's case: an
unshifted key is upper case and SHIFT+letter is lower, as the Model I
keyboard sent them, so a period menu that tests IF K$="Q" answers the
plain key. The READY prompt keeps what you type.
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 clockTRS80_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 fifteen documented ROM entry points
(01C9H CLS, 0A7FH argument to HL, 0A9AH HL to result, 1A19H
READY, 002BH keyboard scan, 0049H wait for a key, 0060H delay,
01D3H RANDOM, 14C9H RND, 05D9H line input, 0033H and 033AH
a character on the screen as PRINT puts it, 2B05H WRA1 to DE, and
RST 08H and RST 18H through their vectors at 4000H and 4006H); a call
anywhere else in ROM space is a ?FC with the address on stderr, since
no ROM is shipped. With no core (none beside the checkout, or TRS80_Z80=
set empty) 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, renum
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 editTalk 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:
| program | shows |
|---|---|
hilo.bas |
INPUT from stdin and --seed (a contradictory answer ends it with ERROR 1, exit 1) |
logbook.bas |
sequential files: OPEN "O"/"E"/"I", PRINT#, LINE INPUT#, EOF, KILL; ON ERROR for a missing file |
starfile.bas |
random-access files: FIELD, LSET, PUT/GET, MKI$/CVI, LOF |
life.bas |
SET/RESET/POINT on the 128x48 grid (run it interactively to watch) |
palette.bas |
color semigraphics, SET(x,y,c) — an extension; color shows only in the interactive grid |
oracle.bas |
the OLLAMA channel with @TOKENS steering the reply |
trapper.bas |
ON ERROR GOTO, ERR, ERL, RESUME, ERROR n |
demo_showcase.bas |
a tour of the math, string and PRINT functions |
tiny_if.bas |
a small text adventure: DATA tables, string parsing, a command loop |
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
--updateon 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.--checkfirst 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?SNonINPUT "prompt",varor on text typed at a no-variableINPUT. 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.basfile; actually it resolves against your current directory, because the interpreter never changes directory. Run from where the program's data is, or callbasicby absolute path. - Batch output has no graphics, and no color anywhere but the grid. You
might expect
SETto show up in./basic prog.basoutput; actually only printed text is streamed, because the screen grid is not rendered without a terminal.--screenkeeps the control codes; interactive mode shows the picture.SET(x,y,c)color renders only in the interactive grid, andPOINTreports lit/unlit regardless of color. - Printing scrolls the picture. You might expect
POINTto read back whatSETdrew; actually anyPRINTthat reaches the bottom line scrolls the whole screen, pixels included — read before you print, or usePRINT@to place text. - A keyword inside a name ends the name. You might expect
TOTAL=5orSCORE=5to work; actually they are?SN ERROR, because the machine reads every letter against its keyword table andTOTALisTO TAL,SCOREisSC OR E. The same rule is what makesFORX=1TO10andIFA=1THEN100run. Blanks inside a name are nothing, also as on the machine:A Bis the variableAB, andPRINT A Bprints one value.detok.py -sspaces a listing out for reading; the interpreter does not need it. - String space is 50 bytes until
CLEAR n. You might expect strings to grow without limit; actually a program that builds more than 50 bytes of strings without aCLEAR nstops with?OS ERROR, as it did on the machine, andFRE("")says how much is left. Literals in program lines take none of it. The Level II manual's rule (under CLEAR): the amount cleared must equal or exceed the most characters held in string variables during execution. Many period listings assumed you typedCLEAR 1000atREADYbeforeRUN, outside the listing;--clear 1000types it for you, and a batch run that stops with?OSsays so on stderr. A listing whose ownCLEAR nis too small fails the same way on the machine, and no option helps: the program'sCLEARwins. - Numbers have the machine's three types. You might expect
PRINT 1000000to print 1000000; actually it prints1E+06, because a literal up to 7 digits is a single and a single prints to 6 digits, as on the machine. An 8-digit literal, a D exponent or a#makes a double, which prints 16 digits with a D exponent; an E exponent makes a single at any length.A#=1/3holds the single quotient (.3333333432674408) because1/3is single division; write1#/3for a double one. Singles are 24 bits, soFOR X=0 TO 1 STEP .1makes 10 passes, as the machine does. A double is the machine's too: a 56-bit mantissa, with the ROM's own add, subtract, multiply and divide, so2#/3#prints.6666666666666667and the machine's quirks come with it (1D16-.2#is above1D16;man CDBL). CLEAR MEM-nis a 16K or 32K listing. You might expect it to run anywhere; actually on the 64K mapMEMexceeds 32767 andCLEAR's count is an integer, so it is?OV ERROR, as it would be on a 48K machine.--memsize 32767is the machine it was written for, and the batch run says so on stderr.- New code can have the host's memory. You might expect
DIM A(100000)or a 2,000-character string to work on a modern machine; actually they are?OVand?LS, because the default is the TRS-80's limits, so a period listing behaves as it did.--memory host(orTRS80_MEMORY=host, thememory hostmetacommand,REM META: memory hostunderext on) lifts them all at once for a program written for this interpreter: no?OM,?OSor?LS, any subscript orCLEARcount, file lines read whole, and every character of a variable name counts (the machine keeps two:SUMisSU, and so it is here by default, because period listings rely on it).MEMandFREstill count what the program uses, against a 2 GB top.PEEK,POKE,VARPTRandUSRkeep the 64K machine, so a long string shows a length byte of 255 there. A batch run that hits one of those limits says so on stderr. - A statement ends at a colon, or the line does. You might expect
X=1ENDorX=1 Y=2to run both parts; actually they are?SN ERROR, because the machine tests the byte behind every completed statement and takes only:or the end of the line.END X,STOP XandRETURN Xare?SNfor the same reason. Two tails are never looked at, also as on the machine: what follows aGOTO's line number, and what follows aGOSUB's, whichRETURNskips over. - Metacommands are lowercase.
dir,man,help,fullscreenare metacommands;DIRorMANreach BASIC and give?SN ERROR. This keeps the two namespaces apart. LOFcounts 256-byte records, on a sequential file as on a random one (a 440-byte file is 2):man LOF.ERRis not the error code. As on the real machine,ERR/2+1is the code (1 = NF, 2 = SN, 11 = /0, 54 = FF: the file errors carry Disk BASIC's own numbers, 51-70).man ERRlists them.- A program can disable BREAK, as on the real machine, with
POKE 16396,23(or 175, 165);POKE 16396,201re-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;exit,byeorBYEleaves. - A named OLLAMA thread persists.
OPEN "O",1,"OLLAMA:llama3.2:story"writesstory.ollamain 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 you or a program tell
it to: OPEN "O"/"E"/"R", CSAVE, SAVE, KILL and OLLAMA thread
files, always under your current directory; and the TRS80_PRINTER file
and the sound wav file, wherever you point them. 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.basscripts anyINPUT; a heredoc does the same for many../basic prog.bas > run.txt 2> errors.txtseparates the transcript from BASIC errors.help <text>searches the keyword documentation;manneeds the exact word.speed 1.77(orTRS80_MHZ=1.77) slows a game to the original machine's pace.sound onplays aUSRroutine's cassette-port sound through the core;sound wav f.wavrecords it.TRS80_GFX=asciiworks on every terminal, including the raw Linux console.- The interactive grid needs a terminal of at least 64x20.
- Machine code without the companion core.
USRroutines run only with the Z80 core,trs80_z80_core, checked out beside this repo or named byTRS80_Z80(PROTOCOL.mdis the contract). Without itUSRreturns its argument, and a run that calledUSRends 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=strictturns 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, where it should behave as on Linux (not tested here).
- 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.
| argument | default | what it does | when you'd use it |
|---|---|---|---|
-o DIR, --outdir DIR |
stdout | write one .bas per input into DIR; refused (exit 2, nothing written) when an output would be one of the inputs or two inputs share a name |
converting more than one file |
-s, --space-keywords |
off | re-separate keywords the ROM ran together (FORX=1TOR → FOR X=1 TO R) |
for reading; the interpreter reads FORX as FOR X, as the machine does |
--check |
off | parse only, report problems, write nothing | finding out whether a file is really a tokenized image |
--raw-newlines |
off | keep CR/LF inside strings and REMs byte-for-byte | archival fidelity only; the result will not reload |
--table TSV |
tools/level2_tokens.tsv |
alternate token table | never, unless you are studying another ROM |
The inverse: a text listing back to a tokenized image. Writes: DIR/<name>.bas
with -o, else stdout.
| argument | default | what it does | when you'd use it |
|---|---|---|---|
-o DIR, --outdir DIR |
stdout | write one image per input; refused as for detok when an output would be an input or two inputs share a name | producing files for a real machine or emulator |
--round-trip |
off | detokenize each image, re-tokenize, compare bytes; writes nothing | checking that a conversion is lossless |
--base ADDR |
0x42E9 |
load address for the line pointers | matching a specific machine's memory layout |
-v |
off | show every mismatch in --round-trip |
when a round trip fails |
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.
| argument | default | what it does | when you'd use it |
|---|---|---|---|
--check |
off | exit 1 if the guide is stale, write nothing | CI, or before committing a manpages change |
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. While it runs the interpreter writes only what you or your program ask
for: the files a BASIC program opens, saves or KILLs and an .ollama
thread (in the working directory), the file named by TRS80_PRINTER, and
the WAV named by sound wav or TRS80_SOUND_WAV.
| path | what it holds |
|---|---|
trs80basic.awk |
the whole interpreter, one file — generated from src/, never edited directly |
src/p*.awk |
the interpreter's source modules, concatenated in name order; edit these |
basic |
launcher: finds gawk, the manpages and a Z80 core checked out beside it, loads gawk's time extension when it has one, runs gawk with -b (strings are bytes), passes flags and the build id through, and at a terminal restores the tty if gawk dies |
support/manpages.txt |
text behind man and help; plain format, edit freely |
programs/demos/ |
interactive demos (tictactoe, demo_graphics) — INKEY$-driven, so run them at the READY prompt, not in batch |
programs/examples/ |
feature examples with .in inputs and .out transcripts (tiny_if the text adventure, demo_showcase, hilo, life, …); the transcripts regenerate with run_examples.sh --update |
programs/tests/t*.txt |
interactive-mode input scripts for regression checks (t1–t33) |
programs/tests/*.bas, programs/tests/*.sh |
self-checking fixtures and shell suites: VARPTR, string aliasing, INP, the system variable window, the BREAK and driver vectors, USR, image truncation, the Z80 protocol (z80.sh), POKEd and string-packed routines through the real core (z80core.sh, skips without it), CLOAD of a tokenized image (tokload.sh), the trs-80.com tips tally |
programs/tests/ollama_stub.sh |
canned Ollama replies; oracle, t13 and t29 run against it |
programs/tests/z80_stub.py |
the reference Z80 core stand-in that z80.sh and t32 run against |
programs/tests/run_all.sh |
the whole suite in one exit status: the generated file, t1–t33, every fixture and suite, the tool tests |
.github/workflows/tests.yml |
runs run_all.sh on GitHub on every push and pull request |
PROTOCOL.md |
the USR coprocess protocol between the interpreter and the Z80 core; mirrored into the core repo |
tools/detok.py, tools/tok.py, tools/level2_tokens.tsv |
image ↔ listing converters and the Level II token table |
tools/test_*.py |
their tests (python3 -m unittest discover -s tools) |
tools/DETOK.md |
the token format and conversion notes |
docs/USER_GUIDE.md |
the full user manual; Part V is generated by tools/make_userguide.py |
*.ollama in your working directory |
an OLLAMA conversation thread, written by a program that names one; KILL or rm forgets the conversation |
RELEASE_NOTES.md |
keyword inventory and documented deviations from Level II |
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.

