diff --git a/docs/architecture.md b/docs/architecture.md index 1c801a3..d73cbae 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -58,7 +58,7 @@ HAL writes straight to stdout. src/ — core interpreter (22 files) include/ — headers (14 files) platform/ — HAL backends (1 file) -tests/ — 70 automated test programs, 4 classic interactive programs, compat harness +tests/ — 71 automated test programs, 4 classic interactive programs, compat harness docs/ — Sphinx documentation ``` diff --git a/docs/development.md b/docs/development.md index 3bf3556..6a81cc1 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 | +| 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 | ## Tests -70 test programs in `tests/programs/`, plus 4 classic interactive programs in +71 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. 65 tests have `.expected` golden files +Each test has a 5-second timeout. 66 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 1cfb5c3..e2b82be 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 -- **70 test programs** with golden-file regression testing and DOSBox-X +- **71 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 d066981..ed463ac 100644 --- a/docs/language-reference.md +++ b/docs/language-reference.md @@ -54,13 +54,15 @@ type suffixes (`%`, `!`, `#`) | Event trapping | `ON TIMER(n) GOSUB`, `TIMER ON`/`OFF`/`STOP`, `ON KEY(n) GOSUB`, `KEY(n) ON`/`OFF`/`STOP` | | Error handling | `ON ERROR GOTO`, `RESUME`, `RESUME NEXT`, `RESUME n`, `ERROR`, `ERR`, `ERL` | | User functions | `DEF FN`, `RANDOMIZE` | -| File management | `KILL`, `NAME`, `FILES`, `MKDIR`, `RMDIR`, `CHDIR`, `SHELL` | -| Date/time | `DATE$`, `TIME$`, `TIMER` | +| File management | `KILL`, `NAME`, `FILES`, `MKDIR`, `RMDIR`, `CHDIR`, `SHELL`, `RESET` | +| Date/time | `DATE$`, `TIME$`, `TIMER` (read/write; `DATE$`/`TIME$` assignment accepted) | +| Environment | `ENVIRON`, `ENVIRON$` | | Screen | `LOCATE`, `COLOR`, `WIDTH`, `SCREEN`, `KEY ON`/`OFF`/`LIST`, `KEY n,"string"` | | Graphics | `PSET`, `PRESET`, `LINE`, `CIRCLE`, `DRAW`, `PAINT`, `GET`, `PUT`, `VIEW`, `WINDOW`, `PALETTE`, `PMAP` | | Sound | `SOUND`, `BEEP`, `PLAY` (MML parser, PulseAudio backend) | | Memory | `DEF SEG`, `PEEK`, `POKE`, `BSAVE`, `BLOAD` | | Hardware I/O | `OUT`, `INP`, `WAIT`, `MOTOR`, `STICK`, `STRIG` | +| Device stubs | `ERDEV`, `ERDEV$`, `IOCTL`, `IOCTL$`, `COM`, `LCOPY` | | Misc | `KEY`, `TRON`/`TROFF`, `OPTION BASE`, `MID$` assignment | | System | `SYSTEM` | @@ -259,6 +261,45 @@ OUT &H61, INP(&H61) AND &HFC ' speaker off When the PPI speaker bits are set, the PIT frequency divisor is used to generate a continuous tone via PulseAudio (same backend as `SOUND` / `PLAY`). +## Environment Variables + +- `ENVIRON "var=value"` — set an environment variable (uses the C `putenv()` call) +- `ENVIRON$("var")` — read an environment variable (returns "" if not set) + +``` +ENVIRON "GREETING=Hello" +PRINT ENVIRON$("GREETING") ' prints: Hello +PRINT ENVIRON$("PATH") ' prints the system PATH +``` + +## Date/Time Assignment + +`DATE$` and `TIME$` can be assigned to set the date and time: + +``` +DATE$ = "01-15-2026" +TIME$ = "14:30:00" +``` + +These assignments are accepted for compatibility but do not modify the +system clock. Reading `DATE$` and `TIME$` always returns the current +system date and time. + +## Device Stubs + +The following device-related statements and functions are accepted for +compatibility with programs that reference them, but return stub values +since there is no real device hardware: + +- `ERDEV` — device error code (always 0) +- `ERDEV$` — device error name (always "") +- `IOCTL [#n,] string` — device control string output (accepted, ignored) +- `IOCTL$(n)` — device control string input (always "") +- `COM ON` / `COM OFF` / `COM STOP` — serial port event trapping (accepted, ignored) +- `LCOPY [n]` — screen dump to printer (accepted, ignored) +- `CALL` / `CALLS` — machine code execution (raises Illegal function call) +- `RESET` — close all open files (equivalent to `CLOSE`) + ## Sound - `SOUND frequency, duration` — play a tone (frequency in Hz, duration in clock ticks) diff --git a/docs/roadmap.md b/docs/roadmap.md index f23b2dc..f2b2d65 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -20,6 +20,11 @@ stub). Default: reads return 0xFF (floating bus), writes discarded. Statements: `OUT`, `WAIT`, `MOTOR`. Functions: `INP()`, `STICK()`, `STRIG()`. +Also in v0.15.0: filled remaining statement/function gaps — `RESET`, +`ENVIRON`/`ENVIRON$`, `ERDEV`/`ERDEV$`, `IOCTL`/`IOCTL$`, `LCOPY`, +`DATE$`/`TIME$` assignment, `CALL`/`CALLS`, `COM`. All 144 defined +tokens are now handled (100% token coverage). + ## Next Up *(Looking for the next major feature — see IDE and Notebook Integration below.)* @@ -43,3 +48,7 @@ Statements: `OUT`, `WAIT`, `MOTOR`. Functions: `INP()`, `STICK()`, `STRIG()`. - 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 +- `DATE$`/`TIME$` assignment accepted but does not modify the system clock +- Device stubs (`ERDEV`, `IOCTL`, `COM`, `LCOPY`) return defaults — no real + device emulation