go-basic

A cross-platform interpreter for classic, line-numbered BASIC, written in Go. It targets Microsoft 8K BASIC behavior and is continuously exercised against all 112 byte-distinct original BASIC programs in the pinned BASIC Computer Games corpus.

Why go-basic?

• Run classic BASIC programs on Linux, macOS, and Windows.
• Get actionable source, BASIC-line, and runtime diagnostics.
• Reproduce programs with controlled random seeds and statement limits.
• Depend on a small Go codebase with no third-party runtime dependencies.
• Verify compatibility against every distinct source in a pinned historical corpus.

Quick start

Download a checksummed archive from the latest release, or build from source with Go 1.26.6 or newer:

git clone https://github.com/scottdensmore/go-basic.git
cd go-basic
make build
./bin/go-basic test/scripts/test.bas

Expected output:

Hello World
 1   1 
 2   4 
 3   9 
 4   16 
 5   25 

Documentation

Guide	What it covers
Getting started	Installation, CLI options, input, reproducibility, and errors
How it works	Source preparation, lexing, parsing, evaluation, and package boundaries
Language reference	Supported syntax, statements, operators, functions, and extensions
Compatibility	Pinned corpus, acceptance tiers, results, and known upstream exception
Contributing	Development workflow, testing expectations, and pull requests
Security	Supported versions, private reporting, trust boundaries, and limitations
Code of Conduct	Expected behavior and reporting options for project spaces

Continuous integration

PRs and pushes to main run formatting, vet, the full race-enabled test suite with the existing 80% coverage gate, both bounded fuzz targets, the pinned 112-variant corpus smoke tier, and CLI builds for Linux, macOS, and Windows. Tests execute on Linux; the macOS and Windows outputs are cross-compiled. CI selects an existing hosted Go toolchain and disables automatic toolchain and module downloads. The corpus fetch downloads only the pinned BASIC test data. No tools are installed, and no release archives, tags, or publishing jobs are produced or run. The separate golangci-lint and govulncheck commands require additional tool installation and are outside this workflow's coverage. Only failure logs are retained, for three days.

Supported at a glance

go-basic supports numeric and string values, arrays, arithmetic and 16-bit logical operators, subroutines and loops, interactive input and formatted printing, DATA/READ, user-defined numeric functions, and the common Microsoft BASIC numeric and string function set.

The language reference is the source of truth for the implemented language surface. Passing the external corpus is strong compatibility evidence, not a claim of universal support for every BASIC dialect or hardware-specific feature.

License

go-basic is available under the MIT License.