From 65f99da932c4bd06c8d2bb1771de62feb1b4604e Mon Sep 17 00:00:00 2001 From: Eremey Valetov Date: Sun, 29 Mar 2026 04:58:29 -0400 Subject: [PATCH] Update Sphinx docs with string pool GC, remove string GC from limitations --- docs/architecture.md | 10 ++++++---- docs/development.md | 6 +++--- docs/index.md | 2 +- docs/language-reference.md | 22 ++++++++++++++++++++++ docs/roadmap.md | 6 +++++- 5 files changed, 37 insertions(+), 9 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index d73cbae..892f1c7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -50,15 +50,16 @@ HAL writes straight to stdout. | Sound engine | `sound.c` | — | | Virtual memory (PEEK/POKE) | `virmem.c` | — | | Hardware I/O ports | `portio.c` | — | +| String space pool + GC | `strpool.c` | GWEVAL.ASM (GETSPA/GARBAG) | | Platform abstraction | `hal_posix.c` | OEM*.ASM | ## Source Layout ``` -src/ — core interpreter (22 files) -include/ — headers (14 files) +src/ — core interpreter (23 files) +include/ — headers (15 files) platform/ — HAL backends (1 file) -tests/ — 71 automated test programs, 4 classic interactive programs, compat harness +tests/ — 72 automated test programs, 4 classic interactive programs, compat harness docs/ — Sphinx documentation ``` @@ -96,7 +97,8 @@ algorithms are reimplemented in idiomatic C with modern data structures. at the binary save/load boundary and for file I/O (CVI/CVS/CVD, MKI$/MKS$/MKD$), matching the original's on-disk format - **Dynamic memory allocation** — `malloc`/`free` instead of a 64KB segment layout -- **malloc'd strings** — instead of a compacting garbage collector +- **String space pool** — 32KB contiguous pool with compacting GC at statement + boundaries, matching the original's GETSPA/GARBAG approach - **`setjmp`/`longjmp`** — for error recovery, matching the original's stack reset behavior - **ANSI terminal** — TUI uses ANSI escape sequences and alternate screen buffer diff --git a/docs/development.md b/docs/development.md index 6a81cc1..2f49b54 100644 --- a/docs/development.md +++ b/docs/development.md @@ -18,11 +18,11 @@ | 0.12.0 | | BSAVE/BLOAD, TUI ANSI 16-color rendering, CGA graphics framebuffer PEEK/POKE, keyboard shift flags | | 0.13.0 | | VIEW/WINDOW/PALETTE graphics, PMAP function, MBF float format for CVS/CVD/MKS$/MKD$ | | 0.14.0 | | MBF binary file compatibility (IEEE↔MBF at save/load boundary), fix binary loader null-byte truncation, fix DRAW M/S/A bugs, add TA/=var;/X substring | -| 0.15.0 | | Hardware I/O simulator: OUT/INP/WAIT/MOTOR statements, port emulation (8253 PIT, PPI speaker, CGA mode/color, COM1, game port), continuous tone via PulseAudio. Fill remaining gaps: RESET, ENVIRON/ENVIRON$, ERDEV/ERDEV$, IOCTL/IOCTL$, LCOPY, DATE$/TIME$ assignment, CALL, COM | +| 0.15.0 | | Hardware I/O simulator: OUT/INP/WAIT/MOTOR, port emulation (PIT, PPI, CGA, COM1, game port), continuous tone. Gap-fill: RESET, ENVIRON, ERDEV, IOCTL, LCOPY, DATE$/TIME$ assign, CALL, COM (100% token coverage). String space pool with compacting GC | ## Tests -71 test programs in `tests/programs/`, plus 4 classic interactive programs in +72 test programs in `tests/programs/`, plus 4 classic interactive programs in `tests/classic/` (Hamurabi, Lunar Lander, Gunner, Diamond from David Ahl's *BASIC Computer Games*). @@ -32,7 +32,7 @@ Run the full automated suite: bash tests/run_tests.sh ``` -Each test has a 5-second timeout. 66 tests have `.expected` golden files +Each test has a 5-second timeout. 67 tests have `.expected` golden files for output regression detection. Tests without golden comparison: datetime, on_timer, timer_stop (timing-dependent), color_test (visual), play_music (audio duration). diff --git a/docs/index.md b/docs/index.md index e2b82be..8d01872 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,7 +27,7 @@ version is structured as modular C suitable for new feature development. - **Printer output** — `LPRINT`/`LLIST` to file or real hardware via `--lpt` - **Classic programs** — Hamurabi, Lunar Lander, Gunner, and Diamond from David Ahl's *BASIC Computer Games* (1978) run out of the box -- **71 test programs** with golden-file regression testing and DOSBox-X +- **72 test programs** with golden-file regression testing and DOSBox-X compatibility testing against real GWBASIC.EXE - **MIT License** diff --git a/docs/language-reference.md b/docs/language-reference.md index ed463ac..7803b1f 100644 --- a/docs/language-reference.md +++ b/docs/language-reference.md @@ -30,6 +30,12 @@ `EOF`, `LOC`, `LOF` +## Memory Functions + +- `FRE(x)` — free bytes in the string space pool. `FRE("")` triggers a + garbage collection pass before reporting; `FRE(0)` reports without collecting. +- `VARPTR(var)` / `VARPTR$(var)` — variable address (internal index) + ## Pseudo-variables `ERL`, `ERR`, `CSRLIN`, `INKEY$`, `DATE$`, `TIME$`, `TIMER`, `POS(0)` @@ -225,6 +231,22 @@ The file format is compatible with the original GW-BASIC: byte 0 = `0xFD`, bytes 1-2 = segment (LE), bytes 3-4 = offset (LE), bytes 5-6 = length (LE), followed by the raw data bytes. +## String Space and Garbage Collection + +All string data lives in a contiguous pool (default 32,768 bytes), matching +the original GW-BASIC's string space architecture. Allocation is a bump +pointer; dead strings are reclaimed by a compacting garbage collector that +runs automatically at statement boundaries when the pool is running low. + +``` +CLEAR ,8192 ' set string space to 8KB and clear variables +PRINT FRE("") ' trigger GC and print free bytes +``` + +`CLEAR n` (or `CLEAR ,n`) resizes the string space to *n* bytes and clears +all variables. `FRE("")` forces a garbage collection pass and returns the +free bytes; `FRE(0)` returns the current free count without collecting. + ## Hardware I/O (OUT / INP / WAIT) `OUT`, `INP`, and `WAIT` provide access to emulated IBM PC I/O ports, enabling diff --git a/docs/roadmap.md b/docs/roadmap.md index f2b2d65..65a2813 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -25,6 +25,11 @@ Also in v0.15.0: filled remaining statement/function gaps — `RESET`, `DATE$`/`TIME$` assignment, `CALL`/`CALLS`, `COM`. All 144 defined tokens are now handled (100% token coverage). +String space pool with compacting garbage collector (`strpool.c`), +replacing individual `malloc`/`free`. 32KB default pool, bump-pointer +allocation, compaction at statement boundaries. `FRE()` returns actual +free space; `CLEAR n` resizes the pool. + ## Next Up *(Looking for the next major feature — see IDE and Notebook Integration below.)* @@ -45,7 +50,6 @@ tokens are now handled (100% token coverage). ## Known Limitations -- String garbage collection not implemented (uses `malloc`/`free` instead) - Maximum 256 variables, 64 arrays, 16 FOR nesting, 24 GOSUB nesting, 16 WHILE nesting - `CALL`/`CALLS` (machine code execution) raises Illegal function call