Skip to content

compatibility.md

Latest commit

 

History

History
99 lines (77 loc) · 4.33 KB

compatibility.md

File metadata and controls

99 lines (77 loc) · 4.33 KB

GW-BASIC Compatibility Guide

This project is a modern C++20 rewrite, not a byte-for-byte clone of the original GW-BASIC runtime. The goal is to preserve common source-level behavior while keeping the implementation portable and testable.

Running Programs

gwbasic --file ./examples/snake.bas
gwbasic --headless --file ./examples/snake.bas
gwbasic --check --file ./examples/snake.bas

Run without arguments to enter the interactive prompt.

Supported Language Core

Area Supported
Program model Line-numbered stored programs, immediate statements, RUN, LIST, NEW, CLEAR
Assignment LET, implicit assignment, scalar numeric/string variables
Expressions Numeric and string literals, variables, arrays, user DEF FN calls, unary +/-/NOT, arithmetic including ^, integer division \, MOD, comparisons, AND, OR
Control flow IF ... THEN ... ELSE, line-target IF, GOTO, GOSUB, RETURN, ON ... GOTO, ON ... GOSUB
Loops FOR ... TO ... STEP / NEXT, WHILE / WEND
Error handling ON ERROR GOTO, RESUME, RESUME NEXT, RESUME <line>, ERROR, ERR, ERL
Data DATA, READ, RESTORE
Arrays DIM, ERASE, OPTION BASE 0/1, one- and multi-dimensional numeric/string arrays
User functions DEF FNname(args)=expression for numeric and string expressions
Numeric functions ABS, INT, FIX, CINT, CLNG, CSNG, CDBL, SGN, SQR, SIN, COS, TAN, ATN, EXP, LOG, RND
String functions LEN, VAL, LEFT$, RIGHT$, MID$, CHR$, ASC, STR$, SPACE$, STRING$, INSTR, UCASE$, LCASE$, LTRIM$, RTRIM$, HEX$, OCT$, DATE$, TIME$
Time/random TIMER, RANDOMIZE, RND
Default typing DEFINT, DEFSTR, DEFSNG, DEFDBL

Supported I/O and Files

Area Supported
Console PRINT, WRITE, INPUT, LINE INPUT, INKEY$, INPUT$
Cursor/color CLS, LOCATE, WIDTH, COLOR, KEY ON/OFF
Sequential files OPEN ... FOR INPUT/OUTPUT/APPEND, CLOSE, INPUT#, LINE INPUT#, PRINT#, WRITE#, EOF, LOF, LOC
Random files OPEN ... FOR RANDOM LEN=, FIELD, LSET, RSET, GET#, PUT#
Filesystem Text SAVE, text LOAD, FILES, KILL, NAME ... AS, MKDIR, CHDIR, RMDIR

Supported Graphics and Sound Surface

Area Supported
Screen SCREEN, headless canvas, aspect-preserving Direct3D presenter on Windows, aspect-preserving X11/OpenGL presenter on Linux
Drawing PSET, graphics LINE, CIRCLE, PAINT, DRAW
View transforms VIEW, WINDOW, PMAP, POINT
Blocks Graphics GET / PUT, PSET, PRESET, AND, OR, XOR modes
Palette PALETTE, PALETTE USING
Sound BEEP, stubbed SOUND, stubbed PLAY

Memory Compatibility

POKE and PEEK are implemented against an isolated 64 KiB virtual memory buffer. They never write to native process memory. Addresses outside 0..65535 raise a runtime error and can be handled with ON ERROR.

Known Differences

  • Numeric behavior uses modern double; it does not emulate 8087 or Microsoft BASIC floating-point quirks exactly.
  • SOUND and PLAY currently produce bell-style output rather than PC speaker synthesis.
  • WIDTH tracks internal text width for the portable text/graphics layer; it does not resize the host terminal.
  • Binary tokenized .BAS files are not decoded yet; SAVE and LOAD currently use text BASIC source.
  • DOS drive/device semantics are only approximated through portable filesystem operations. FILES supports simple * and ? wildcards, not the full DOS device/path model.
  • The original GW-BASIC editor experience is not reproduced.

Test Coverage

CTest currently includes:

  • Lexer unit tests.
  • Parser/AST unit tests.
  • Interpreter compatibility golden-output tests.
  • Smoke coverage for files, graphics, arrays, input, palette, and runtime flow.

Optional CI targets also include static analysis and a libFuzzer smoke target for lexer/parser robustness.

Generated API Documentation

The repository can build Doxygen HTML documentation with:

cmake -S . -B build-docs -DGWBASIC_BUILD_DOCS=ON
cmake --build build-docs --target docs

Pull requests build this documentation as a check. Pushes to main publish the generated HTML through GitHub Pages.