Share a host program's own C structures with a script

A BASIC TYPE and a host C struct are the same thing seen from two sides, so both
go in one type table and everything the language already does with a structure
works across the boundary with no second set of rules. The host describes its
struct once as a table of field descriptors and binds an instance:

    akbasic_host_bind(&SCRIPT, "FOE@", "ENEMY", &GOBLIN);

after which `FOE@.HP# = FOE@.HP# - 10` decrements GOBLIN.hp in place, with no
marshalling step the host has to remember to run.

The sharing is done with shadow slots: a binding takes a run from the same value
pool a DIMmed record uses, a field read refreshes its slot from host memory
first, and a write converts back and stores. So the script always sees current
values and its writes always land, while the rest of the interpreter goes on
seeing one storage model instead of two.

AKBASIC_HOST_FIELD takes the offset and the width from the same member, which is
the only reason it is a macro: writing offsetof and sizeof out by hand is two
chances to name the wrong member and no way to notice. A field name's suffix
must agree with the C type it describes, refused at registration -- a host
writing "HP%" over an int32_t has said two different things about one field and
the script would believe the suffix.

Conversion refuses rather than truncates. 200 into an int8_t, 70000 into an
int16_t, -1 into a uint8_t and thirteen characters into a char[8] are each an
error naming the field, because a silent wrap is found three frames later in
code that did nothing wrong. Each width is tested separately, since a range
check is exactly the thing that is right for int32_t and wrong for int8_t when
only one of them is covered.

The language's own distinction turns out to be the one a host needs, so there is
one API rather than two: assignment copies and gives a script a private
snapshot, POINT shares and lets it change the game, and which one happened is
visible in the listing.

Two things the work required. The prescan runs again on every RUN and used to
wipe the whole type table, unregistering the host's types the first time a
script ran; it now keeps what the host registered and drops only what the script
declared. And akbasic_runtime_start() did not rewind, which cost nothing while a
host started a script once and cost everything to a host running one per enemy
-- the second start began past the end and silently did nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-01 11:56:04 -04:00
parent 2a3f68d2c4
commit 631c70ce7d
13 changed files with 1068 additions and 7 deletions

View File

@@ -145,6 +145,7 @@ set(AKBASIC_SOURCES
src/sink_stdio.c
src/sink_tee.c
src/sprite_tables.c
src/host.c
src/structtype.c
src/symtab.c
src/value.c
@@ -239,7 +240,7 @@ akbasic_instrument(basic)
# The embedding example. It is built by default and registered as a test so the
# code README.md quotes cannot rot: a signature change breaks the build.
if(AKBASIC_BUILD_EXAMPLES)
foreach(_example IN ITEMS embed hostvars)
foreach(_example IN ITEMS embed hostvars hoststruct)
add_executable(akbasic_example_${_example} examples/${_example}.c)
target_compile_options(akbasic_example_${_example} PRIVATE -Wall -Wextra)
target_link_libraries(akbasic_example_${_example} PRIVATE akbasic)
@@ -277,6 +278,7 @@ set(AKBASIC_TESTS
format_verbs
grammar_leaves
graphics_verbs
hoststruct
hostvars
housekeeping_verbs
input_verbs