BASIC Interpreter

A Rust interpreter for classic GW-BASIC-style programs, developed as an educational project for studying language implementation, parsing, runtime execution, and compatibility with historical BASIC dialects.

The syntax shape is guided by the MINDSET GW-BASIC Reference Manual. The project is not affiliated with Microsoft, Mindset, or any original BASIC vendor.

Project Status

This interpreter can tokenize, parse, and execute many GW-BASIC commands, statements, functions, file operations, screen-oriented statements, event statements, and compatibility stubs. It is intended for learning and experimentation, not for production workloads or for running untrusted BASIC programs.

Some implemented features approximate host behavior where direct hardware, screen, sound, joystick, printer, serial-port, memory, or DOS semantics are not available on modern systems. Compatibility work is ongoing.

Important Notice

This software is provided for educational use only.

The software is made available as is, without warranties of any kind, express or implied. See the MIT License section and the LICENSE file for the full legal terms.

Do not run BASIC programs from untrusted sources. Supported language features include file-system operations and host command execution through statements such as SHELL, which can affect the local machine when used by a BASIC program.

Features

• Line-numbered BASIC program execution
• Numeric and string expressions
• Scalar variables and arrays
• User-defined DEF FN functions
• Control flow with IF, GOTO, GOSUB, RETURN, FOR/NEXT, WHILE/WEND, ON ... GOTO, ON ... GOSUB, and error/event syntax
• Console input and output
• Sequential and random-access file syntax
• Many GW-BASIC string, numeric, date, time, and conversion functions
• Screen, graphics, sound, object, joystick, timer, port, and memory-oriented statements with host-compatible approximations or safe stubs where direct hardware behavior is not available
• BASIC smoke-test files for recently implemented compatibility areas

Requirements

• Rust toolchain with edition 2024 support
• Cargo

The project currently has no external Rust crate dependencies.

Building

Build a debug executable:

cargo build

Build an optimized release executable:

cargo build --release

The executable is generated at:

• Windows: target/release/basic.exe
• Linux/macOS: target/release/basic

Downloading Compiled Artifacts

Prebuilt executables are generated by GitHub Actions for each push and pull request. Open the latest successful Build workflow run and download the artifact for your operating system:

• Windows executable artifact (basic-windows-x64)
• Linux executable artifact (basic-linux-x64)
• macOS executable artifact (basic-macos-x64)

GitHub stores workflow artifacts on each individual run, so the links above point to the Build workflow run list rather than a single permanent binary URL.

Running

Run a BASIC file through Cargo:

cargo run -- test_print.bas

Run the compiled executable directly:

target/release/basic test_print.bas

On Windows:

target\release\basic.exe test_print.bas

Example

10 REM SIMPLE LOOP
20 FOR I = 1 TO 5
30 PRINT "COUNT"; I
40 NEXT I
50 END

Testing

Run the Rust test suite:

cargo test

Run Clippy:

cargo clippy

Several .bas files in the repository are smoke tests for specific language features. After building, they can be executed with:

target/release/basic test_file.bas

On Windows:

target\release\basic.exe test_file.bas

Continuous Integration

GitHub Actions builds the interpreter automatically on pushes and pull requests. The workflow:

• runs cargo test
• runs cargo clippy
• builds a release executable
• uploads the generated executable as a workflow artifact

Tagged releases matching v* also build release artifacts.

Repository Layout

src/
  main.rs         Entry point
  lexer.rs        BASIC lexer
  parser.rs       BASIC parser and AST
  interpreter.rs  Runtime interpreter

*.bas             BASIC smoke-test programs and examples
Cargo.toml        Rust package manifest
LICENSE           MIT license

Safety Notes

This interpreter is designed to model a classic local BASIC environment. Some language features are inherently powerful:

• SHELL can execute host operating-system commands.
• File commands can create, overwrite, rename, or remove files and directories.
• Compatibility stubs may accept syntax without reproducing exact historical hardware behavior.

Use this project in a controlled workspace and avoid untrusted BASIC source files.

License

This project is licensed under the MIT License.

Copyright (c) 2026 Demerson Andre Polli

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.