Add native RND and ASC functions

Implement bounded random integers with lazy clock seeding and add ASC as the inverse of CHR. Cover dispatch, validation, deterministic LCG output, UTF-8 round trips, function reference, and the breakout tutorial.

Closes #16.

Co-authored-by: andrew <andrew@aklabs.net>

.gitea/workflows/ci.yaml

@@ -17,7 +17,7 @@ jobs:
           # Not recursive, deliberately. The top-level build needs
           # deps/libakerror and deps/libakstdlib, via add_subdirectory, and
           # nothing else: the golden corpus and the Commodore font now live in
-          # this repository (tests/language/ and assets/fonts/), so
+          # this repository (tests/reference/ and assets/fonts/), so
           # deps/basicinterpret is no longer a build dependency at all.
           # It does *not* need deps/libakgl, which is guarded behind
           # AKBASIC_WITH_AKGL and defaults OFF -- and recursing into it would
@@ -62,9 +62,11 @@ jobs:
         run: |
           cmake -S . -B build
           cmake --build build --parallel 2
-      # The suite is 112 cases: 65 language files with sibling expectations,
-      # 43 unit tests, 3 embedding examples, and docs_examples.
-      # Some unit tests assert the *correct* contract for known defects (TODO.md
+      # The suite is 78 cases: 41 golden files byte-compared against the Go
+      # reference's own corpus (checked in at tests/reference/, see its README),
+      # 9 local golden cases for verbs the reference never implemented, 25 unit
+      # tests, 2 embedding examples, and 1 known-failing test that asserts the
+      # *correct* contract for defects carried over from the reference (TODO.md
       # section 6). A green run therefore does not mean defect-free -- see
       # AKBASIC_KNOWN_FAILING_TESTS.
       #

CLAUDE.md

@@ -26,7 +26,7 @@ scripting engine for game authors.
 | [the issue tracker](https://source.starfort.tech/andrew/akbasic/issues) | **Outstanding defects and gaps.** Labelled by kind and blast radius; `status::grooming` means the scope is not settled yet |
 | [`TODO.md`](TODO.md) | The record: settled design decisions, the deviation register, defects already fixed, and the reasoning behind the measurements. §0.1 first — it retires the byte-for-byte fidelity constraint several later sections were written on |
 | [`README.md`](README.md) | What the project is and why, for somebody who has not seen it |
-| [`docs/`](docs/README.md) | The language itself: twenty-one chapters, verb and function reference. [Chapter 14](docs/14-architecture.md) is the interpreter's architecture — the step loop, the pools, the two kinds of error, and how to debug it. [Chapter 15](docs/15-error-codes.md) is the error-code appendix. [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) are tutorials that build the games in `examples/breakout/`; [Chapters 20](docs/20-tutorial-galaga.md) and [21](docs/21-tutorial-galaga-enemies.md) build the embedding host in `examples/galaga/` |
+| [`docs/`](docs/README.md) | The language itself: eighteen chapters, verb and function reference. [Chapter 14](docs/14-architecture.md) is the interpreter's architecture — the step loop, the pools, the two kinds of error, and how to debug it. [Chapter 15](docs/15-error-codes.md) is the error-code appendix. [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) are tutorials that build the games in `examples/breakout/` |
 | `deps/libakerror/AGENTS.md` | The `ATTEMPT`/`CLEANUP`/`PROCESS`/`HANDLE`/`FINISH` protocol, authoritatively |
 | `deps/libakerror/UPGRADING.md` | 1.0.0's status registry. Required before writing an error code |
 | `deps/<library>/AGENTS.md` | Per-repo rules. Read the relevant one **before editing a submodule** |
@@ -57,9 +57,9 @@ repeating where you will see them:
   `include/akgl/SDL_GameControllerDB.h`. Change the template or the generator script.
 - **Do not reformat code you are not otherwise changing.** Several files mix tabs and spaces
   and there is no repo-wide formatter; style conversions get their own commit.
-- **Keep `tests/language/` editable.** Its `.bas` programs and sibling `.txt` expectations
-  are changed together when behavior changes. Record deliberate language decisions in
-  `TODO.md` or `docs/13-differences.md`.
+- **Do not edit `tests/reference/`.** Those expectations came from the Go implementation and
+  are never edited to suit this interpreter. A deliberate divergence goes in
+  `tests/reference/README.md`'s divergence table and `docs/13-differences.md`.
 - **Open an issue for outstanding work; do not add it to `TODO.md`.**
   <https://source.starfort.tech/andrew/akbasic/issues>, or `tea issues create --repo
   andrew/akbasic`. Name the file and line, the functional consequence, and what closing it would

CMakeLists.txt

@@ -268,69 +268,6 @@ if(AKBASIC_BUILD_EXAMPLES)
   endforeach()
 endif()
 
-# The galaga example: a C game on libakgl with the interpreter embedded as its
-# enemy-behavior engine. Chapters 20 and 21 build it from an empty file, so it
-# is compiled and run by every AKGL build rather than rotting in a document.
-# The asset, script and font paths are baked in so the smoke test can launch
-# from any working directory; --assets and --script override them at runtime.
-if(AKBASIC_BUILD_EXAMPLES AND AKBASIC_WITH_AKGL)
-  add_executable(akbasic_example_galaga
-    examples/galaga/main.c
-    examples/galaga/script.c
-    examples/galaga/enemies.c
-    examples/galaga/player.c)
-  target_compile_options(akbasic_example_galaga PRIVATE -Wall -Wextra)
-  target_compile_definitions(akbasic_example_galaga PRIVATE
-    GALAGA_ASSET_DIR="${CMAKE_CURRENT_SOURCE_DIR}/examples/galaga/assets"
-    GALAGA_SCRIPT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/examples/galaga/galaga.bas"
-    GALAGA_FONT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/assets/fonts/C64_Pro_Mono-STYLE.ttf")
-  target_link_libraries(akbasic_example_galaga PRIVATE akbasic akgl
-    SDL3::SDL3 SDL3_ttf::SDL3_ttf SDL3_image::SDL3_image)
-  akbasic_instrument(akbasic_example_galaga)
-  # Ten seconds of scripted play under the headless drivers: the script boots,
-  # a wave enters and forms, the autoplay pilot shoots at it, and the program
-  # tears down and exits 0. A tutorial that stops working fails here rather
-  # than in front of a reader.
-  _add_test(NAME example_galaga COMMAND akbasic_example_galaga --frames 600 --autoplay)
-  _set_tests_properties(example_galaga PROPERTIES TIMEOUT 120
-    ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_AUDIODRIVER=dummy;SDL_RENDER_DRIVER=software")
-
-  # The boundary's round-trip test: links the real script.c and the real
-  # galaga.bas, and fails the moment the two sides of the interop disagree.
-  add_executable(akbasic_example_galaga_interop
-    examples/galaga/interop_test.c
-    examples/galaga/script.c)
-  target_compile_options(akbasic_example_galaga_interop PRIVATE -Wall -Wextra)
-  target_compile_definitions(akbasic_example_galaga_interop PRIVATE
-    GALAGA_SCRIPT_PATH="${CMAKE_CURRENT_SOURCE_DIR}/examples/galaga/galaga.bas")
-  target_link_libraries(akbasic_example_galaga_interop PRIVATE akbasic akgl
-    SDL3::SDL3 m)
-  akbasic_instrument(akbasic_example_galaga_interop)
-  _add_test(NAME example_galaga_interop COMMAND akbasic_example_galaga_interop)
-  _set_tests_properties(example_galaga_interop PROPERTIES TIMEOUT 120)
-
-  # Regenerating the game figures in docs/ is a deliberate act, never part of
-  # a build, for the same reason docs_screenshots is: the PNGs are checked in.
-  # Wall-clock dt makes each regeneration differ by a few pixels of starfield,
-  # so expect a binary diff every time this runs; commit one only when the
-  # content changed on purpose. (docs_galaga_figures, not docs_game_figures:
-  # the libakgl submodule already owns that target name.)
-  add_custom_target(docs_galaga_figures
-    COMMAND ${CMAKE_COMMAND} -E env SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy
-            SDL_RENDER_DRIVER=software
-            $<TARGET_FILE:akbasic_example_galaga> --frames 40
-            --screenshot "${CMAKE_CURRENT_SOURCE_DIR}/docs/images/galaga-title.png"
-            --screenshot-frame 30
-    COMMAND ${CMAKE_COMMAND} -E env SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy