Files

21 KiB

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, Extended BASIC Unravelled and Disk BASIC Unravelled.

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 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 and Super Extended BASIC Unravelled error-trap listings.

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. Interpreter storage and execution behavior are documented in Color BASIC Unravelled. 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.