Files

340 lines
21 KiB
Markdown

# BASIC development workspace
> Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.
## Direct machine operations
- **Load into CoCo** installs the editor's complete program at a safe BASIC
prompt, without running it. It replaces the existing in-memory program and
prepares a fresh BASIC execution/variable state. The previous running/paused
state of the emulator is preserved; a paused load does not execute guest
instructions until Run or Resume completes the interpreter initialization.
- **Run** performs the same validated replacement and starts a fresh execution
through the existing ROM interpreter. It does not add a source breakpoint or
require an additional Run action in the emulator.
- **Read from CoCo** reads the program currently in BASIC memory back into the
editor. This includes changes made through the CoCo's own line editor. It reads
program source, not variable values or a suspended execution checkpoint.
Load and Run preflight the entire source, ROM, memory mapping, available space
and interpreter state before replacing program memory. They refuse an unsafe
state, such as a program still executing or waiting for INPUT. Mounted disks,
cassettes, cartridges and machine configuration are retained. Existing media
save/export protections remain independent of these program-memory operations.
Read-back is a canonical listing: keywords use their BASIC spellings, `?` may
become `PRINT`, lines are numbered and sorted, and ROM-inserted separators around
`ELSE` and apostrophe remarks are handled so that reading and reloading preserves
the program. It is not a byte-for-byte copy of the editor's original formatting.
Programs containing unsupported binary/non-ASCII text or damaged line links are
rejected without replacing the editor's contents.
## BASIC line breakpoints
Click the gutter circle beside a numbered statement, or use **Toggle BASIC
breakpoint at insertion point** in the toolbar. Breakpoints are explicit; the
sample and a new document start with none. **Run** installs the program and its
breakpoints together, so even its first line can stop before executing. Changes
to the breakpoint set can also attach to an already-loaded matching program.
At a breakpoint the whole emulator pauses, the source line is highlighted, and
**Continue** resumes without reloading BASIC, clearing variables, unwinding
GOSUB/FOR stacks or closing files. Continue executes the stopped line once before
that breakpoint can stop again. **Run** remains a fresh program transfer, subject
to the existing OK-prompt guard; it is not the Continue action. The main emulator
Resume action can also leave a BASIC stop.
These are **line-entry breakpoints**. A colon-separated second statement and a
return into the middle of a line do not re-trigger that line's entry breakpoint.
The stepping controls below can stop at those individual statements.
In Earth or Mars, set a breakpoint on the line that prints `M$` and add
`M$` as a watch. Run the program and select a planet. At the stop, the watch
contains its greeting and the screen still shows the menu. Step once to print
the greeting. Continue to switch back to the usual text colors and return to BASIC.
The editor checks its source against the tokenized program in CoCo memory.
Editing the source detaches the live mapping immediately and hides the execution
highlight; pending breakpoint numbers apply on the next Run. A core comparison
of the line chain, command dispatcher and memory mapping also detaches when the
guest program or relevant memory changes. Continue rechecks the source and stop
on the emulation queue before resuming. It refuses a stale stop. Explicit CPU
stepping, PC changes, binary loading, resets and configuration replacement also
end the BASIC debugging attachment. Manual machine-code breakpoints are kept
separately.
Breakpoint selections last for the current editor document/session. New, Open
and Read from CoCo clear them; Renumber clears them after changing the labels so
old breakpoint numbers cannot silently target different code. Source files and
recovery drafts do not currently store breakpoints. Closing the workspace window
alone preserves its model and the paused CoCo session.
The hook uses the shared command dispatcher at `$ADC6`, with the current line at
`$0068` and input pointer at `$00A6`. The input pointer must identify the line's
first token. The Color, Extended and Disk BASIC dispatch loops have different
entry paths but converge here. The implementation validates the qualified
bundled CoCo 3 interpreter and dispatcher before enabling this behavior; it does
not patch ROM or program bytes. The primary references are the command dispatch
sections in [Color BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/color-basic-unravelled.pdf),
[Extended BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/extended-basic-unravelled.pdf)
and [Disk BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/disk-basic-unravelled.pdf).
## Statement stepping and Step Over
At a BASIC breakpoint, **Step Into BASIC statement** (the down-arrow toolbar
button) executes until the next statement the interpreter dispatches. A yellow
highlight identifies its source line; a stronger orange highlight identifies
its next token, including separate statements on the same line. The mapping is
emitted by the tokenizer from the original editor source, preserving spelling,
spacing, CRLF and source order. Highlighting never edits the document or moves
the insertion point.
**Step Over BASIC subroutine** (the bent-arrow button) follows a `GOSUB` through
its `RETURN`, including recursion and `ON … GOSUB`. Nested `FOR/NEXT` loops are
not mistaken for subroutine calls. An explicit breakpoint inside the call still
wins. On an ordinary statement, Step Over stops at the next statement just like
Step Into. `IF` can dispatch an inline THEN/ELSE command as a separate stop;
expressions themselves are not individually stepped. REM, DATA, skipped branches
and empty separators follow the interpreter's behavior.
The editor is temporarily read-only while a step is running. **Pause BASIC step**
appears during a wait, and the main emulator Pause action also cancels stepping.
A step pauses automatically after 600 emulated video frames (about ten seconds),
so a nonreturning subroutine or INPUT wait cannot leave an unbounded debugger
operation. Continue resumes the existing execution without reloading. After
cancellation or the limit, stepping becomes available again at the next BASIC
breakpoint; no statement highlight is invented for a mid-statement pause.
Use Show CoCo and Continue to supply input normally.
END, STOP, and runtime errors that return to BASIC finish a step at the OK prompt.
The emulator remains paused; Continue lets the prompt accept commands or a new
editor transfer. Program,
interpreter or mapping changes cancel an active step and detach its source map.
Changes to the editor after a stop also detach debugging as described above.
Step Over observes the qualified interpreter's GOSUB frame push at `$AE9D` and
RETURN pop at `$AEDA`, recording and matching frame addresses instead of guessing
from the stack pointer alone. The input-loop entry at `$AC7C` identifies a return
to the prompt. These routines and the dispatcher are guarded against changes;
CoCo 3's normal boot patch to the preceding OK-print routine is outside the guard.
The [Color BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/color-basic-unravelled.pdf)
GO, RETURN and command-dispatch listings provide the interpreter reference.
## Step Out and runtime errors
**Step Out** runs the current `GOSUB` through its `RETURN`, stopping before the
next mapped statement in the caller. It handles nested and recursive calls and
skips intervening `FOR` frames. Explicit breakpoints still take precedence. The
button is unavailable at top level, in an unrecognized stack, or after a
mid-statement pause. Pause and the same 600-frame execution bound apply.
The caller walk starts at the interpreter's current dispatch return address,
verifies its BSR/JSR instruction, and walks typed 18-byte FOR and five-byte GOSUB
frames within BASIC's RAM bounds. It verifies the saved caller line/pointer
against the attached source, then matches the exact frame at `$AEDA`. A changed
caller frame cancels Step Out. Different DOS command-loop return addresses are
accepted only when their call into the recognized dispatcher is verified.
Run now attaches error observation even without a source breakpoint. It still
runs immediately and never adds a default breakpoint. Unhandled errors finish
the ROM's normal reporting and file cleanup, then pause before keyboard input
at the OK prompt. A banner shows the ROM's actual two-character error code and
source line; **Show Line** selects that numbered source row without modifying it.
This is line-level navigation, not a claim to identify the exact faulty
expression. Values that remain in BASIC can be inspected at this stop.
Choose **Continue** to return to the normal prompt before editing and running a
corrected program. If source edits have already detached debugging, resume the
CoCo from the main window. Continue does not resume the aborted BASIC program.
A new transfer, changed source, reset, or detached source mapping clears the old
error. The last matching error can remain visible after returning to the prompt.
`ON ERR GOTO` remains under the ROM's control. Handled errors do not produce the
unhandled-error banner or an automatic stop; a breakpoint in the handler still
works. Error observation uses the shared `$AC65` reporting path after the error
code has been printed, rather than intercepting every error before the guest
can handle it. The error routines are guarded alongside command dispatch.
The additional interpreter references are the
[Disk BASIC Unravelled command-loop and error-driver listings](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/disk-basic-unravelled.pdf)
and [Super Extended BASIC Unravelled error-trap listings](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/super-extended-basic-unravelled.pdf).
## Variables and watches
The collapsible **Variables and Watches** panel reads the stopped BASIC program's
numeric and string variables, DIM arrays, and DEF FN entries. It refreshes at a
BASIC breakpoint, after statement stepping, and at the stepping stop before the
OK prompt. **Refresh BASIC variables** also rereads a safe stop. Continuing,
editing the source, resetting or detaching debugging clears the displayed values.
An arbitrary CPU pause in the middle of INPUT, expression evaluation or string
collection is not a safe BASIC inspection stop.
Arrays expand into pages of 32 elements. Their displayed bounds are inclusive
and begin at zero; multidimensional indices use the source's order. Strings
preserve case and quote their contents, with nonprinting bytes escaped as
`\xHH`. Numbers decode the interpreter's five-byte floating-point representation.
DEF FN entries are identified but never evaluated.
**Watches** accepts named variables and array elements with literal, nonnegative
subscripts, such as `A`, `NAME$`, or `M(1,2)`. BASIC identifies names by their first
two characters, so `NAME$` appears as `NA$`. Unknown names say **Not assigned**;
unknown arrays say **Not dimensioned**. Wrong subscript counts and out-of-range
indices are reported separately. Watches do not evaluate expressions, functions,
PEEK or assignments and never create a guest variable. Up to 128 watch names are
remembered with the local workspace recovery draft, independently of breakpoints.
Inspection copies normal BASIC RAM on the emulation queue without executing
instructions, modifying memory or accessing device registers. It validates the
qualified interpreter, source/program identity, MMU mapping, variable-table
bounds and array descriptors. Strings whose descriptors point outside ordinary
BASIC RAM are shown as unavailable. A malformed table returns an inspection
error instead of guessed values. Asynchronous results are discarded after the
source, machine generation or stopped execution position changes. This is
read-only inspection; editing values and general expression watches are not
implemented.
## Validation approach
`BASICBridgeTests` runs against optional, ignored
`platforms/macos/LocalResources/ROMs/coco3.rom` and `disk11.rom`. Tests explicitly
skip the ROM integrations if those files are absent; no proprietary ROM bytes are
checked into the repository. Both guest processors are exercised sequentially
because the retained emulator core is process-global.
The key independent oracle enters an authored fixture through the actual ROM's
keyboard/tokenizer, captures the tokenized RAM program, then compares it with a
directly loaded version of the same source. The fixture includes strings,
`DATA`, `REM`, apostrophe remarks, `?`, function tokens, `ELSE`, disk commands and
CoCo 3 commands. Reading that program and reloading the returned source must
produce the same bytes. Other checks cover direct execution without queued
keystrokes, preserved media and machine generation, rejected source preserving
the previous program, and unsupported machines rejecting direct writes. Export
checks cover deterministic DSK/CAS output, paused memory/register preservation,
running-program preservation, invalid source/names and unchanged media and
machine generation. Separate core checks load the exported files through the
actual ROM's `LOAD` and `CLOAD`, including programs crossing disk granules and
cassette data blocks; cassette checks use the normal transport rather than fast
loading.
The BASIC command references maintained by Color Computer Archive are useful
background for command vocabulary and usage:
[Color BASIC, Extended BASIC and Disk BASIC references](https://colorcomputerarchive.com/repo/Documents/BASIC%20Commands/).
Interpreter storage and execution behavior are documented in
[Color BASIC Unravelled](https://colorcomputerarchive.com/repo/Documents/Books/Unravelled%20Series/color-basic-unravelled.pdf).
The bundled Quick Reference provides original local
explanations and examples. These source links do not imply that the external
manuals are bundled with the workspace.
### Initial validation — November 4, 2026
The 13 focused native tests passed on both Apple Silicon and x86_64 under
Rosetta: five bridge integrations, six editor/language/recovery checks and two
pure core token/validation tests, exercising the final normal-RUN-handler path.
The complete 63-check standalone core suite also passed. There were no failures or
skips. Each real-ROM bridge case exercised both the 6809 and 6309. The original interpreter's typed
program and the directly installed program matched byte for byte; canonical
read-back reloaded to the same representation. Paused Load preserved cycle count,
and immediate Read followed by Run executed successfully. Execution printed the
expected result with no queued paste; disk/tape assignments and machine generation
were unchanged. Invalid/oversized source, active loops, INPUT waits and unsupported
machines were rejected without replacing the previous program.
These original checks use authored isolated machine instances and predate the
line-breakpoint feature. They do not qualify other ROM revisions.
### BASIC line-debugging validation — November 4, 2026
All 40 targeted tests passed on Apple Silicon and x86_64 under Rosetta: ten
BASIC bridge integrations, 19 workspace tests and 11 existing core/native debugger
checks. The BASIC breakpoint cases run on both emulated processors. They verify
stopping before execution, repeated loop stops, Continue without a reset,
subroutine return state and variables, colon statements, coexistence with manual
CPU breakpoints, rejection of mismatched source and invalid line numbers, and
detachment after program-memory edits, PC changes and reset.
The isolated native UI check verifies both gutter clicks and the accessible
insertion-point toggle, Run to a selected line, Continue, unchanged source and
machine generation, disabling Continue after editing, and clearing breakpoints.
The captured window was visually reviewed for gutter alignment and stopped-line
highlighting. That checkpoint covered line-entry debugging; the later sections record
statement stepping and variable inspection. No default breakpoint is installed.
### Statement stepping validation — November 5, 2026
All 50 targeted tests passed on Apple Silicon and x86_64/Rosetta (Apple Silicon
in a 46-test pass plus four final guard/mapping checks): 17 BASIC bridge tests,
20 workspace tests, two tokenization/export core checks and 11 existing debugger
regressions. The new bridge cases exercise both emulated processors. Coverage
includes same-line statements, source order/CRLF and keyword case, FOR/NEXT,
IF/ELSE, nested and recursive GOSUB, ON GOSUB, explicit breakpoint precedence,
return to the OK prompt after END and a runtime error, an INPUT wait canceled
without clearing its program, and the 600-frame bound on a nonreturning call.
Self-modifying BASIC detaches and stops rather than highlighting stale source.
The editor test verifies that moving the token highlight within one line leaves
source text and insertion point unchanged.
The isolated native check passed Step Into, Step Over, same-line token rendering,
Continue after the OK-prompt stop, and pausing an INPUT wait. The existing gutter,
Continue and stale-source UI regression also passed. The final window capture was
visually reviewed; only the app window is retained here. Xcode emitted internal
QoS diagnostics during automated editor lookup; those did not fail the tests,
and this validation does not establish their underlying cause.
## Variables and watches validation — November 5, 2026
All 53 targeted tests passed on Apple Silicon and Intel under Rosetta: 19 BASIC
bridge integrations, 21 workspace checks, two pure core checks and 11 debugger
regressions. Each BASIC bridge test exercises both emulated CPUs. Real-ROM
fixtures independently create numbers (including negative, fractional, large
and small values), mixed-case/empty/binary strings, numeric and string arrays,
and DEF FN entries. The inspector recovers their values and source-order array
indices without changing RAM, cycle counts, program revision or media. Tests
also reject stale source, running/mid-statement inspection and damaged tables.
Synthetic RAM checks cover malformed array ranks, lengths, offsets, variable
pointers and string descriptors pointing at device addresses. Watch checks cover
canonical names, bounds, unknown variables, rejected expressions and recovery.
The final native checks passed array expansion, adding scalar/string/array
watches, value refresh after stepping, clearing values on Continue, and the
existing Step Into/Step Over/INPUT-cancellation workflow. The final asynchronous
stop guard and layout built for both architectures; all 21 workspace tests were
rerun successfully on Apple Silicon. A small disclosure control was replaced by
a full-row accessible array button. The breakpoint ruler now draws and clips its
own separator within the editor, fixing the vertical line previously extending
through the toolbar and footer. Window-only screenshots were visually reviewed.
Xcode still reports its internal QoS warning during UI automation; this pass does
not identify or claim to resolve that separate warning.
## Step Out, runtime-error and preset validation — November 5, 2026
The added real-ROM bridge tests exercise both emulated processors and cover
nested/recursive returns, FOR frames, explicit-breakpoint precedence, stale
source and top-level refusal, division-by-zero, syntax, DATA, type and disk-file
errors, normal ROM error output, and preserved `ON ERR GOTO` behavior.
An isolated test creates the actual Disk BASIC, Hard Drive BASIC and CoCo SDC
preset definitions from private ROMs and authored starter media. Each preset runs
`DIR` against its own mounted storage, transfers and reads back source, stops at
a breakpoint, inspects a scalar and array, steps into/out of a subroutine, and
reports an unhandled error. Optional private `rgbdos.rom` and `sdcdos.rom` are
required for that case. No personal working media are opened or modified.
The native UI test checks Step Out availability, caller return, exact source-row
selection, unchanged source, correcting/re-running after an error, and compact
window controls. The resize regression verifies a real size change and checks
that both the header and full preset guidance stay within the window. The
inspector reduces its visible rows in shorter windows while retaining its own
scrolling. Representative window captures:
- Returned to caller
- Runtime error source navigation
Validation for this stage: 57 selected BASIC/core/debugger tests passed on Apple
Silicon and the same 57 passed on Intel through Rosetta, with no skips. The native
Step Out/error-navigation workflow passed in the isolated app. Both build
architectures compiled. Xcode's App Intents metadata notice and internal test
service/QoS diagnostics are not claimed resolved by this change.