A complete implementation of Microsoft BASIC-80 5.21 (CP/M era) with an interactive interpreter and TWO compiler backends (Z80/8080 + JavaScript), written in Python.
About MBASIC: MBASIC was a BASIC interpreter originally developed by Microsoft in the late 1970s. This is an independent, open-source reimplementation created for educational purposes and historical software preservation. See MBASIC History for more information.
📄 Want the full story? See MBASIC Project Overview for a comprehensive feature showcase.
Status: Full MBASIC 5.21 implementation complete with 100% compatibility in interpreter and both compiler backends.
- ✅ 100% Compatible: All original MBASIC 5.21 programs run unchanged
- ✅ Modern Extensions: Optional debugging commands (BREAK, STEP, WATCH, STACK)
- ✅ Multiple UIs: CLI (classic), Curses, Tk (GUI), Web (browser)
- ✅ Full REPL: Interactive command mode with RUN, LIST, SAVE, LOAD, etc.
- ✅ 100% Feature Complete: ALL compilable MBASIC 5.21 features implemented
- ✅ Generates CP/M Executables: Produces native .COM files for 8080 or Z80 CP/M systems
- ✅ Efficient Runtime: Optimized string handling with O(n log n) garbage collection
- ✅ Hardware Access: Full support for PEEK/POKE/INP/OUT/WAIT
- ✅ Machine Language: CALL/USR/VARPTR for assembly integration
- ✅ 100% Feature Complete: All MBASIC 5.21 features except hardware access
- ✅ Generates JavaScript: Produces standalone .js files for Node.js and browsers
- ✅ Cross-Platform: Same code runs in browsers and Node.js
- ✅ Full File I/O: localStorage in browser, fs module in Node.js
- ✅ Standalone HTML: Optional HTML wrapper for browser deployment
See Implementation Status section below for details, Extensions for modern features, Compiler Features for compiler information, and PROJECT_STATUS.md for current project health and metrics.
# Minimal install - CLI backend only (zero dependencies)
pip install mbasic
# With full-screen terminal UI (curses backend)
pip install mbasic[curses]
# With graphical UI (tkinter - included with Python)
pip install mbasic[tk]
# With all UI backends
pip install mbasic[all]
# For development
pip install mbasic[dev]Building from source: See Linux Mint Developer Setup for complete system setup including all required packages, compiler tools, and development dependencies.
Note: Tkinter is included with most Python installations. If missing:
- Debian/Ubuntu:
sudo apt-get install python3-tk - RHEL/Fedora:
sudo dnf install python3-tkinter - macOS/Windows: Reinstall Python from python.org
For end users (interpreter only): See INSTALL.md for detailed installation instructions.
For developers (full development environment including compiler): See Linux Mint Developer Setup for comprehensive system setup with all packages and tools.
System Requirements (Debian/Ubuntu/Mint only):
# REQUIRED for virtual environments:
sudo apt install python3-venv
# OPTIONAL for Tkinter GUI backend:
sudo apt install python3-tkQuick install:
# Clone the repository
git clone https://github.com/avwohl/mbasic.git
cd mbasic
# Create and activate a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies (optional - only needed for non-CLI UIs)
pip install -r requirements.txt
# Run the interpreter
python3 mbasicpython3 mbasic --list-backendsThis shows which UI backends are available on your system.
✓ Complete MBASIC 5.21 implementation
- 100% parser coverage for valid MBASIC programs
- All core language features (math, strings, arrays, control flow)
- Sequential and random file I/O (OPEN, CLOSE, FIELD, GET, PUT, etc.)
- Error handling (ON ERROR GOTO/GOSUB, RESUME)
- Interactive command mode (REPL)
- File execution mode
✓ Complete language support
- Variables with type suffixes ($, %, !, #)
- Arrays with DIM
- Control flow (IF/THEN/ELSE, FOR/NEXT, WHILE/WEND, GOSUB/RETURN, GOTO, ON GOTO/GOSUB)
- All arithmetic, relational, and logical operators
- 50+ built-in functions (SIN, COS, CHR$, LEFT$, MKI$/CVI, etc.)
- User-defined functions (DEF FN)
- DATA/READ/RESTORE
- INPUT and PRINT with formatting (including PRINT USING)
- Sequential file I/O (OPEN, CLOSE, PRINT#, INPUT#, LINE INPUT#, WRITE#, EOF)
- Random file I/O (FIELD, GET, PUT, LSET, RSET, LOC, LOF)
- Binary file I/O (MKI$/MKS$/MKD$, CVI/CVS/CVD)
- Error handling (ON ERROR GOTO/GOSUB, RESUME, ERL, ERR)
- File system operations (KILL, NAME AS, RESET)
- Non-blocking keyboard input (INKEY$)
- Execution tracing (TRON/TROFF)
✓ Interactive mode
- Line-by-line program entry
- Direct commands (RUN, LIST, SAVE, LOAD, NEW, DELETE, RENUM)
- Immediate mode expression evaluation
- Compatible with classic MBASIC workflow
python3 mbasic myprogram.baspython3 mbasicThe curses screen editor (default) provides a full-screen terminal interface:
- Visual line editor with auto-numbering
- Status indicators for breakpoints and errors
- Automatic syntax checking (marks parse errors with '?')
- Calculator-style line number editing
- Automatic line sorting
- Split-screen output window
- Optimized paste performance (instant display)
- Smart line number parsing (preserves pasted line numbers)
- Edge-to-edge display (clean copy/paste without borders)
Features:
Ctrl+R- Run programCtrl+S- Save programCtrl+O- Open programCtrl+B- Toggle breakpoint on current lineCtrl+D- Delete current lineCtrl+E- Renumber all lines (RENUM)Ctrl+H- HelpTab- Switch between editor and output- Arrow keys, Page Up/Down for navigation
- Auto-numbering with smart collision avoidance
- Fast paste operations with automatic formatting
Debugger:
Ctrl+G- Continue execution (from breakpoint)Ctrl+T- Step (execute one line)Ctrl+X- Stop execution
See Curses Editor Documentation for complete guide.
python3 mbasic --ui cliThen enter your program:
MBASIC 5.21 Interpreter
Ready
10 PRINT "Hello, World!"
20 FOR I = 1 TO 10
30 PRINT I
40 NEXT I
50 END
RUN
LIST
SAVE "hello.bas"MBASIC includes TWO fully-featured compilers:
- Z80/8080 Compiler - Generates C code and compiles to native CP/M executables for 8080 or Z80 processors
- JavaScript Compiler - Generates portable JavaScript for browsers and Node.js
Both compilers are 100% feature-complete - every MBASIC 5.21 feature that can be compiled is now implemented!
To use the Z80/8080 compiler features, you need:
-
z88dk (required) - 8080/Z80 C compiler
- Must have
z88dk.zccin your PATH - Installation: snap, source build, or docker
- Must have
-
tnylpo (optional) - CP/M emulator for testing
- Must have
tnylpoin your PATH - Installation: build from source
- Must have
None! The JavaScript compiler is built into MBASIC with zero external dependencies. Just use mbasic --compile-js.
# Check if Z80/8080 compiler tools are installed
python3 utils/check_compiler_tools.py# Compile BASIC to C, then to CP/M .COM file
cd test_compile
python3 test_compile.py program.bas
# This generates:
# program.c - C source code
# PROGRAM.COM - CP/M executable (runs on 8080 or Z80 CP/M systems)# Compile to JavaScript for Node.js
mbasic --compile-js program.js program.bas
node program.js
# Or compile to standalone HTML for browsers
mbasic --compile-js program.js --html program.bas
# Open program.html in any browser!
# This generates:
# program.js - JavaScript code
# program.html - Standalone HTML wrapper (if --html used)Core Language (100%)
- All data types: INTEGER (%), SINGLE (!), DOUBLE (#), STRING ($)
- Variables, arrays with DIM, multi-dimensional arrays
- All operators: arithmetic, relational, logical (AND/OR/NOT/XOR)
- Control flow: IF/THEN/ELSE, FOR/NEXT, WHILE/WEND, GOTO, GOSUB/RETURN, ON...GOTO/GOSUB
- DATA/READ/RESTORE, SWAP, RANDOMIZE
Functions (100%)
- Math: ABS, SGN, INT, FIX, SIN, COS, TAN, ATN, EXP, LOG, SQR, RND
- String: LEFT$, RIGHT$, MID$, CHR$, STR$, SPACE$, STRING$, HEX$, OCT$, LEN, ASC, VAL, INSTR
- Conversion: CINT, CSNG, CDBL
- Binary data: MKI$/CVI, MKS$/CVS, MKD$/CVD (for file formats)
- User-defined: DEF FN
- Memory: FRE(), VARPTR()
- Hardware: PEEK(), INP()
- Machine language: USR()
I/O Operations (100%)
- Console: PRINT, INPUT, PRINT USING (formatted output), TAB(), SPC()
- Sequential files: OPEN, CLOSE, PRINT#, INPUT#, LINE INPUT#, WRITE#, KILL, EOF(), LOC(), LOF()
- Random files: FIELD, GET, PUT, LSET, RSET (database-style records)
- File system: RESET (close all), NAME AS (rename), LPRINT (printer output)
Advanced Features (100%)
- Error handling: ON ERROR GOTO, RESUME, RESUME NEXT, RESUME line, ERR, ERL, ERROR
- Hardware access: PEEK/POKE (memory), INP/OUT (I/O ports), WAIT (port polling)
- Machine language: CALL (execute ML routine), USR (call ML function), VARPTR (get address)
- String manipulation: MID$ assignment (substring replacement)
Optimized Runtime (Z80/8080)
- Custom string library with O(n log n) garbage collection
- Only 1 malloc (string pool initialization) - everything else uses the pool
- In-place GC (no temp buffers)
- Efficient memory usage optimized for CP/M's limited RAM
JavaScript Runtime
- Leverages JavaScript's built-in garbage collection
- Clean, readable output code
- Dual runtime for Node.js and browser environments
- Virtual filesystem (localStorage) and real filesystem (fs module)
What Works in Z80/8080 Compiler But Not Interpreter
- PEEK/POKE - Direct memory access (hardware-specific)
- INP/OUT/WAIT - I/O port operations (hardware-specific)
- CALL/USR/VARPTR - Machine language integration
- These generate proper 8080/Z80 assembly calls in Z80/8080 compiled code!
What Works in Both Compilers
- All core MBASIC 5.21 language features
- Sequential and random file I/O
- Error handling
- String manipulation
- Program chaining (CHAIN)
For detailed setup instructions and compiler documentation, see:
docs/help/common/compiler/index.md- Compiler guide for both backendsdocs/dev/COMPILER_SETUP.md- Z80/8080 compiler setup guidedocs/dev/COMPILER_STATUS_SUMMARY.md- Z80/8080 full feature list and statusdocs/dev/JS_BACKEND_REMAINING.md- JavaScript compiler feature listdocs/dev/TNYLPO_SETUP.md- CP/M emulator installation (for Z80/8080 testing)
mbasic/
├── mbasic # Main entry point (interpreter)
├── src/
│ ├── lexer.py # Tokenizer (shared by interpreter & compilers)
│ ├── parser.py # Parser - generates AST (shared)
│ ├── ast_nodes.py # AST node definitions (shared)
│ ├── tokens.py # Token types (shared)
│ ├── semantic_analyzer.py # Type checking and analysis (compilers)
│ ├── codegen_backend.py # Code generation to C (Z80/8080 compiler)
│ ├── codegen_js_backend.py # Code generation to JavaScript (JS compiler)
│ ├── runtime.py # Runtime state management (interpreter)
│ ├── interpreter.py # Main interpreter
│ ├── basic_builtins.py # Built-in functions (interpreter)
│ ├── interactive.py # Interactive REPL
│ └── ui/ # UI backends (cli, curses, tk, web)
├── test_compile/
│ ├── test_compile.py # Compiler test script
│ ├── mb25_string.h/.c # String runtime library for compiled code
│ └── test_*.bas # Compiler test programs
├── basic/
│ ├── dev/ # Development and test programs
│ │ ├── bas_tests/ # BASIC test programs
│ │ ├── tests_with_results/ # Self-checking BASIC tests
│ │ └── bad_syntax/ # Programs with parse errors
│ ├── games/ # Game programs
│ ├── utilities/ # Utility programs
│ └── ... # Other categorized programs
├── tests/
│ ├── regression/ # Automated regression tests
│ ├── manual/ # Manual verification tests
│ └── run_regression.py # Test runner
├── docs/
│ ├── user/ # User documentation
│ ├── dev/ # Developer documentation (includes compiler docs)
│ └── help/ # In-UI help system content
└── utils/ # Development utilities
- Curses Screen Editor - Full-screen terminal editor (default UI)
- Quick Reference - Command reference
- Installation Guide - Detailed installation instructions
- Compiler Status Summary - Complete feature list (100% complete!)
- Compiler Setup - z88dk installation and configuration
- CP/M Emulator Setup - tnylpo installation for testing
- Linux Mint Developer Setup - Complete system setup guide (all packages & tools)
- Parser Implementation - How the parser works (shared by interpreter & compiler)
- Interpreter Architecture - Interpreter design overview
- Interpreter Implementation - Interpreter implementation details
- Compiler Architecture - Code generation and optimization
See the docs/ directory for complete documentation.
MBASIC has a comprehensive test suite with automated regression tests and BASIC program tests.
Run all regression tests:
python3 tests/run_regression.pyRun tests in a specific category:
python3 tests/run_regression.py --category lexer
python3 tests/run_regression.py --category interpretertests/
├── regression/ # Automated regression tests
│ ├── commands/ # REPL commands (RENUM, LIST, etc.)
│ ├── debugger/ # Debugger functionality
│ ├── editor/ # Editor behavior
│ ├── integration/ # End-to-end tests
│ ├── interpreter/ # Core interpreter features
│ ├── lexer/ # Tokenization and case handling
│ ├── parser/ # Parsing and AST generation
│ ├── serializer/ # Code formatting
│ └── ui/ # UI-specific tests
├── manual/ # Manual verification tests
└── run_regression.py # Test runner script
- regression/ - Automated tests (deterministic, repeatable)
- manual/ - Tests requiring human verification
- debug/ - Temporary debugging tests (not tracked in git)
Test BASIC programs live in basic/dev/bas_tests/:
# Run any BASIC test program
python3 mbasic basic/dev/bas_tests/test_operator_precedence.basSelf-checking tests verify correctness and report results:
python3 mbasic basic/dev/tests_with_results/test_operator_precedence.bas
# Result: All 20 tests PASSTest files must:
- Start with
test_prefix - Use
src.prefix for imports (from src.lexer import Lexer) - Exit with code 0 on success, 1 on failure
- Include clear assertion messages
Example test structure:
#!/usr/bin/env python3
import sys
import os
# Add project root to path (3 levels up from tests/regression/category/)
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../..'))
from src.lexer import Lexer
def test_feature():
lexer = Lexer("10 PRINT \"Hello\"")
tokens = lexer.tokenize()
assert len(tokens) > 0, "Should tokenize code"
print("✓ Feature works")
if __name__ == "__main__":
try:
test_feature()
print("\n✅ All tests passed")
sys.exit(0)
except AssertionError as e:
print(f"\n❌ Test failed: {e}")
sys.exit(1)See tests/README.md for complete testing guide.
✓ All statement types (FOR, WHILE, IF, GOSUB, etc.) ✓ All built-in functions (ABS, INT, LEFT$, etc.) ✓ All commands (RENUM, LIST, LOAD, SAVE, etc.) ✓ Edge cases and error handling ✓ Settings system ✓ Help system ✓ Editor features (case/spacing preservation)
- ✓ Runtime state management
- ✓ Variable storage (all type suffixes)
- ✓ Array support with DIM
- ✓ Line number resolution
- ✓ GOSUB/RETURN stack
- ✓ FOR/NEXT loops
- ✓ WHILE/WEND loops
- ✓ ON GOTO/ON GOSUB (computed jumps)
- ✓ DATA/READ/RESTORE
- ✓ Expression evaluation
- ✓ All operators
- ✓ 50+ built-in functions
- ✓ User-defined functions (DEF FN)
- ✓ Sequential file I/O (OPEN, CLOSE, PRINT#, INPUT#, LINE INPUT#, WRITE#, EOF)
- ✓ Random file I/O (FIELD, GET, PUT, LSET, RSET, LOC, LOF)
- ✓ Binary file I/O (MKI$/MKS$/MKD$, CVI/CVS/CVD)
- ✓ Error handling (ON ERROR GOTO/GOSUB, RESUME, ERL, ERR)
- ✓ File system operations (KILL, NAME AS, RESET)
- ✓ Non-blocking input (INKEY$)
- ✓ Execution tracing (TRON/TROFF)
- ✓ PRINT USING with all format types
- ✓ SWAP statement
- ✓ MID$ assignment
- ✓ Line entry and editing
- ✓ RUN command
- ✓ LIST command (with ranges)
- ✓ SAVE/LOAD commands
- ✓ NEW command
- ✓ DELETE command
- ✓ RENUM command
- ✓ Immediate mode
- ✓ Error recovery
- ✓ CONT (continue after STOP or Ctrl+C)
- ✓ EDIT command (line editor)
Both interpreter and compiler are 100% feature-complete!
Interpreter Mode:
- All core MBASIC 5.21 features work perfectly
- Hardware features (PEEK/POKE/INP/OUT) generate warnings (not applicable in modern environment)
- LPRINT works (outputs to console)
Compiler Mode:
- EVERYTHING works - including hardware features!
- PEEK/POKE - Direct memory access (generates real 8080/Z80 memory operations)
- INP/OUT/WAIT - I/O port operations (generates real 8080/Z80 port operations)
- CALL/USR/VARPTR - Machine language integration
- Generates native CP/M .COM executables for 8080 or Z80 processors
What's Not Applicable:
- Graphics/sound (not part of MBASIC 5.21 core spec)
- Interpreter commands in compiler (LIST, LOAD, SAVE - these are for interactive mode only)
- CHAIN/COMMON (program chaining - requires interpreter/loader infrastructure)
See PROJECT_STATUS.md for complete project metrics and health information, and docs/dev/COMPILER_STATUS_SUMMARY.md for detailed compiler feature list.
10 REM Factorial calculator
20 INPUT "Enter a number"; N
30 F = 1
40 FOR I = 1 TO N
50 F = F * I
60 NEXT I
70 PRINT "Factorial of"; N; "is"; F
80 END10 INPUT "Enter a number"; N
20 IF N < 2 THEN PRINT "Not prime" : END
30 FOR I = 2 TO SQR(N)
40 IF N MOD I = 0 THEN PRINT "Not prime" : END
50 NEXT I
60 PRINT "Prime!"
70 END10 INPUT "How many numbers"; N
20 A = 0
30 B = 1
40 FOR I = 1 TO N
50 PRINT A;
60 C = A + B
70 A = B
80 B = C
90 NEXT I
100 ENDThese features work in the compiler and generate real 8080/Z80 machine code:
10 REM Hardware access example - works in compiled code!
20 REM Memory operations
30 A = PEEK(100) ' Read byte from memory address 100
40 POKE 100, 42 ' Write byte 42 to address 100
50 REM Port I/O
60 B = INP(255) ' Read from I/O port 255
70 OUT 255, 1 ' Write 1 to I/O port 255
80 WAIT 255, 1 ' Wait until port 255 bit 0 is set
90 REM Machine language interface
100 ADDR = VARPTR(A) ' Get address of variable A
110 RESULT = USR(16384) ' Call machine code at address 16384
120 CALL 16384 ' Execute machine code routine
130 ENDCompile this with:
cd test_compile
python3 test_compile.py hardware.bas
# Generates hardware.com - runs on 8080 or Z80 CP/M systems!-
Lexer & Parser (October 2025)
- Complete MBASIC 5.21 tokenizer
- Full recursive descent parser
- 60+ AST node types
- 100% parsing success on corpus
- Shared infrastructure for both interpreter and compiler
-
Interpreter (October 2025)
- Runtime state management
- All built-in functions
- Statement execution
- Expression evaluation
- Bug fixes (GOSUB/RETURN, FOR/NEXT)
- File I/O (sequential and random)
- Error handling (ON ERROR GOTO, RESUME)
-
Interactive Mode (October 2025)
- Full REPL implementation
- All direct commands
- Save/load functionality
- Immediate mode
- Multiple UI backends (CLI, Curses, Tk, Web)
-
Z80/8080 Compiler (October-November 2025)
- Semantic analyzer with type checking
- C code generator (Z88dk backend)
- Custom string runtime (O(n log n) GC)
- Memory optimization (zero malloc design)
- Complete file I/O (sequential, random, binary)
- Error handling implementation
- Final push (November 11, 2025):
- Hardware access (PEEK/POKE/INP/OUT/WAIT)
- Machine language interface (CALL/USR/VARPTR)
- File management (RESET/NAME/LPRINT/CHAIN)
- 100% feature complete!
-
JavaScript Compiler (November 2025)
- JavaScript code generator
- Dual runtime (Node.js + browser)
- Virtual filesystem (localStorage)
- Complete file I/O (sequential, random, binary)
- Error handling implementation
- Final push (November 13, 2025):
- Random file access (FIELD/LSET/RSET/GET/PUT)
- Program chaining (CHAIN)
- 100% feature complete!
Original Language: MBASIC 5.21 was created by Microsoft Corporation (1970s-1980s). See MBASIC History for the historical context and Microsoft's role in creating BASIC interpreters.
This Implementation:
- Every line of code written by CLAUDE.ai Supervised by pet human Aaron Wohl (2025)
- Independent, open-source project
- Not created, endorsed, or supported by Microsoft
- Based on published MBASIC 5.21 specifications and documentation
- Created for educational purposes and historical software preservation
Credit Distribution:
- Language design and historical implementation: Microsoft Corporation
- This Python reimplementation: Andrew Wohl and contributors
- Any bugs or issues in this implementation: Our responsibility, not Microsoft's
- Quality of the original language design: Credit to Microsoft's team
GPLv3 License - see LICENSE file for details.
This project is an independent implementation created for educational and historical preservation purposes. It is not affiliated with, endorsed by, or supported by Microsoft Corporation. MBASIC and Microsoft BASIC are historical products of Microsoft Corporation.
- 80un - Unpacker for CP/M compression and archive formats (LBR, ARC, squeeze, crunch, CrLZH)
- cpmdroid - Z80/CP/M emulator for Android with RomWBW HBIOS compatibility and VT100 terminal
- cpmemu - CP/M 2.2 emulator with Z80/8080 CPU emulation and BDOS/BIOS translation to Unix filesystem
- ioscpm - Z80/CP/M emulator for iOS and macOS with RomWBW HBIOS compatibility
- learn-ada-z80 - Ada programming examples for the uada80 compiler targeting Z80/CP/M
- mbasic2025 - MBASIC 5.21 source code reconstruction - byte-for-byte match with original binary
- mbasicc - C++ implementation of MBASIC 5.21
- mbasicc_web - WebAssembly MBASIC 5.21
- mpm2 - MP/M II multi-user CP/M emulator with SSH terminal access and SFTP file transfer
- romwbw_emu - Hardware-level Z80 emulator for RomWBW with 512KB ROM + 512KB RAM banking and HBIOS support
- scelbal - SCELBAL BASIC interpreter - 8008 to 8080 translation
- uada80 - Ada compiler targeting Z80 processor and CP/M 2.2 operating system
- ucow - Unix/Linux Cowgol to Z80 compiler
- um80_and_friends - Microsoft MACRO-80 compatible toolchain for Linux: assembler, linker, librarian, disassembler
- upeepz80 - Universal peephole optimizer for Z80 compilers
- uplm80 - PL/M-80 compiler targeting Intel 8080 and Zilog Z80 assembly language
- z80cpmw - Z80 CP/M emulator for Windows (RomWBW)