# PLAN — Terminal Basic Arbeitsplan für die Re-Implementierung des DOS-BASIC-Dialekts (1992) in Rust. Dieses Dokument wird fortgeschrieben: erledigte Punkte werden abgehakt, Entscheidungen mit Datum und Begründung festgehalten. Konvention: `[ ]` offen · `[x]` erledigt · `[~]` in Arbeit --- ## Leitplanken - **Re-Imagination, nicht Emulation** (2026-09-01): Ziel ist ein BASIC zum Bauen von Terminal-Tools (CLI und TUI). Stufe 1 ist die getreue Nachbildung von UI/UX, Sprachstandard und Standardbibliothek des Vorbilds — rekonstruiert aus vorhandener Online-Dokumentation (Manuals auf archive.org, Wiki-Referenzen, zeitgenössische Artikel). Stufe 2 (nach Phase 6) reichert die Sprache bewusst um Elemente außerhalb des Vorbilds an; Erweiterungen sind additiv und brechen den Kernstandard nicht. - **Referenzverhalten schlägt Eleganz — innerhalb von Stufe 1.** Bei Zweifeln zählt das dokumentierte Verhalten des Vorbilds (inkl. Fehlercodes, Rundung, Formatierung), nicht das, was „richtiger" wäre. Wo das Vorbild aber mit der heutigen Plattform kollidiert (Codepages, DOS-Hardware, Segmente), gewinnt die Plattform; solche Abweichungen werden in der Sprachreferenz dokumentiert. - **Vollständigkeit ist das Soll** (2026-09-02): Erwartet wird eine **100 % kompatible Sprachimplementierung und volle Standardbibliothek** des Vorbilds — abzüglich ausschließlich der in der Sprachreferenz explizit benannten Non-Features. Aufzählungen von Anweisungen/Funktionen in diesem Plan sind **Beispiele, keine Scope-Definition**. Messbar wird das über ein Vollständigkeits-Inventar (alle Keywords, Anweisungen, Funktionen, Methoden, Eigenschaften, Ereignisse aus der Original-Hilfe) mit Abdeckungsstatus → Aufgabe in Phase 3, Abnahmekriterium in Phase 6. **Guiding Principle — die Original-Dokumentation führt** (2026-09-02): Alles, was dort dokumentiert ist, wird unterstützt **oder** durch eine explizite Fehlermeldung abgewiesen. Eine Abweisung setzt voraus, dass das Feature vorher vom Projektinhaber als Non-Feature deklariert und in der Sprachreferenz unter „Abweichungen" gelistet wurde. Stilles Weglassen oder generische Syntaxfehler für dokumentierte Features sind Bugs. - **Markenrecht:** Der Name des Vorbilds wird in Code, Doku und Artefakten nicht verwendet. Wir sprechen vom „Vorbild" bzw. „dem Dialekt". - **Performance ist Anforderung, nicht Politur** (2026-09-01): - **Instant-Compile:** Der Compiler übersetzt so schnell, dass der Benutzer nie auf einen Build wartet — Start aus der IDE fühlt sich wie beim Vorbild an (Run drücken, Programm läuft). Budget: ein komplettes Projekt kompiliert **in Sekunden** und liefert ein ausführbares Ergebnis; einzelne Module im Millisekundenbereich. - Architektur-Konsequenzen: Single-Pass-Design (Lexer/Parser/Codegen ohne teure globale Analysen), modulweise inkrementelle Übersetzung (nur Geändertes neu), keine Optimierungspasses, die den Turnaround kosten — Schnelligkeit der VM kommt aus dem VM-Design, nicht aus einem Optimizer. - **Schnelle Ausführung:** Die TBVM führt generierten Code zügig aus (Details in docs/tbvm-design.md, Abschnitt „Performance"); Messlatte via Benchmarks ab Phase 2. - `tbc build --exe` erzeugt Executables **ohne** Compiler-/Linker- Toolchain beim Anwender (vorkompilierter Runner + angehängtes `.tbc`) — damit bleibt auch der Weg zum verteilbaren Binary im Sekundenbereich. - **Jede Phase endet mit lauffähigen Tests** gegen eine wachsende Kompatibilitäts-Testsuite (Verzeichnis `tests/compat`, geplant). --- ## Phase 0 — Exploration und Grundsatzentscheidungen **Status: abgeschlossen (2026-09-01).** Detailarbeiten, die hier noch offen waren, sind als Eingangsaufgaben in die Phasen verschoben, die sie konsumieren (Regel: Phasen sind einzeln abschließbar; nichts bleibt in einer geschlossenen Phase zurück). ### 0.1 Sprach- und Bibliotheksreferenz rekonstruieren Primärquelle ist vorhandene Online-Dokumentation (archive.org-Manuals, Wiki-Referenzen zur QB/PDS-Familie, zeitgenössische Artikel, Screenshots). Emulator-Sessions nur noch als Rückfallebene für Detailfragen, die die Dokumentation nicht beantwortet. - [x] Sprachreferenz zusammengetragen und gegen die Original-Hilfe des Vorbilds (dos-help.soulsphere.org, README der Professional Edition) verifiziert → [docs/sprachreferenz.md](docs/sprachreferenz.md); die drei verbleibenden Detailfragen sind als Aufgaben zugeordnet: SINGLE/DOUBLE-Literalschwelle → Phase 1, `PRINT USING`-Überlauf und `KEY n`-Makros → Phase 3 - [x] Forms-/Steuerelemente-Referenz aus Original-Hilfe, CONSTANT.BI und Programm-Stringtabellen rekonstruiert (alle 16 Steuerelemente mit Eigenschaften/Methoden/Ereignissen, Defaults, SCREEN-Objekt, Modalität, Menüsystem) → [docs/forms-referenz.md](docs/forms-referenz.md) - [x] Dateiformate dokumentiert → [docs/dateiformate.md](docs/dateiformate.md); die Definition der Text-`.FRM`-Serialisierung (kein Original-Beispiel auffindbar) ist Eingangsaufgabe von Phase 4 - [x] Laufzeitfehler-Katalog vollständig (1–76, ISAM 80–89, Forms 260–480) als `tb_runtime::errors` implementiert (inkl. Tests) - [x] IDE-UX-Referenz: Menüstruktur, Fensterverwaltung, Farbschema, Tastenbelegung, Editor-Verhalten aus Original-Hilfe und Screenshots → [docs/ide-referenz.md](docs/ide-referenz.md) - [x] Testkorpus-Grundstock gelegt (`tests/compat/` mit dokumentierter Sollausgabe). Der Ausbau ist Daueraufgabe jeder Phase; das Test-Harness (`tbc run` + Ausgabevergleich) ist Phase-2-Aufgabe ### 0.2 VM-/Runtime-Entscheidung (Aufstellung der Optionen) Anforderungen an die Ausführungsschicht: BASIC-Fehlersemantik (`ON ERROR GOTO`/`RESUME` mit `ERR`/`ERL`), `GOSUB`/`RETURN`, unterbrechbare Ausführung (Debugger-Einzelschritt, Strg+Untbr, ereignisgesteuerte Forms-Hauptschleife), dynamische Strings/Arrays mit BASIC-Semantik, serialisierbares Kompilat, gute Fehlerortung (Zeile/Spalte). | Option | Vorteile | Nachteile | Eignung | |---|---|---|---| | **1. Eigene Bytecode-VM in Rust („TBVM")** | Volle Kontrolle über Semantik (Fehlerbehandlung, GOSUB, Events, Suspend/Resume); Bytecode als `.tbc` serialisierbar; Debugger-Integration trivial (Zeileninfo im Bytecode); keine Fremdabhängigkeit | Eigenaufwand für VM, GC/Refcounting für Strings/Arrays; „nur" Interpreter-Geschwindigkeit | **Empfohlen** — Interpreter-Tempo genügt für 80×25-Programme bei Weitem | | **2. Tree-Walking-Interpreter** | Schnellster Weg zu ersten laufenden Programmen; ideal zum Validieren der Semantik | Langsam; Debugger/Resume-Semantik unsauber; wäre später Wegwerfcode | Optional als Bootstrap in Phase 1, dann ersetzen | | **3. WebAssembly-Ziel (wasmtime/wasmer)** | Ausgereifte VMs mit JIT (Cranelift); portables, standardisiertes Kompilat; Sandbox; theoretisch Browser-Ausführung | BASIC-Semantik passt schlecht: `ON ERROR`/`RESUME`, `GOSUB` und unterbrechbare Ausführung müssen aufwendig transformiert werden (Relooper/State-Machine); Strings/Arrays komplett selbst verwalten; Debugging über zwei Ebenen; schwere Abhängigkeit | Später als **zweites Backend** denkbar (gleiche IR), nicht als Start | | **4. Cranelift direkt (JIT auf nativen Code)** | Native Geschwindigkeit; Rust-eigenes Projekt, gut eingebettet | Gleiche Semantik-Transformationsprobleme wie WASM; kein portables Kompilat; JIT auf allen drei Plattformen pflegen | Nur falls Performance je Thema wird — unwahrscheinlich | | **5. LLVM-AOT (inkwell)** | Maximale Performance, echte Executables | Sehr schwere Toolchain-Abhängigkeit (LLVM-Build je Plattform); lange Kompilierzeiten; Debugger/Edit-Run-Zyklus der IDE leidet massiv | Ungeeignet für dieses Projekt | | **6. Transpilation auf fremde Skript-VM (Lua via mlua/piccolo)** | Ausgereifte VM mit GC geschenkt | Semantik-Mismatch (Zahlentypen, Fehler-/Eventmodell, 1-basierte vs. BASIC-Arrays mit `OPTION BASE`); Fehlerortung und Debugger bilden schlecht ab | Ungeeignet | | **7. Transpilation nach Rust (AOT)** | Native Binaries, keine VM | Kein Interpretermodus → IDE-Kernfeatures (Direktfenster, Start ohne Build-Wartezeit, Debugger) praktisch unmöglich; Rust-Toolchain als Laufzeitvoraussetzung | Ungeeignet als Primärziel | **Entscheidung (2026-09-01, bestätigt):** Eigene Stack-basierte Bytecode-VM (**Option 1, TBVM**), sowohl in der Entwicklungsphase als auch **eingebettet in die Executables** (`tb`-IDE und von `tbc` erzeugte Programme), damit der schnelle Edit-Run-Turnaround überall identisch ist. Die IR/Bytecode-Schicht wird sauber vom Interpreter getrennt, sodass später ein zweites Backend (WASM via Cranelift, Option 3) ergänzt werden kann, ohne das Frontend anzufassen. Für die Ausführungsgeschwindigkeit typischer Terminal-Programme ist ein Interpreter mehr als ausreichend; entscheidend sind Debugger-Fähigkeit, exakte Fehlersemantik und der schnelle Edit-Run-Zyklus der IDE. - [x] Optionen aufstellen und bewerten (siehe Tabelle) - [x] Bytecode-**Grobdesign** und Speichermodell (Tagged Enum, Rc statt GC) → [docs/tbvm-design.md](docs/tbvm-design.md). Das Feindesign (Opcode-Satz, Konvertierungsmatrix, Runner-Verhalten) ist Eingangsaufgabe von Phase 2 ### 0.3 Ratatui-/Terminal-Spike **Entscheidung (2026-09-01):** Keine CP437-Emulation — der Textbildschirm ist durchgängig **UTF-8/Unicode**. Strings sind Unicode-Text, `CHR$`/`ASC` arbeiten auf Codepoints. Das ist eine bewusste Abweichung vom Vorbild und wird in der Sprachreferenz unter „Abweichungen" dokumentiert. **Entscheidung (2026-09-02):** **Dynamische Terminalgröße** statt festem 80×25. IDE und erzeugte Programme passen sich der Fenstergröße an; Mindestgröße ist 80×25, darunter wird nur ein Hinweis gerendert (btop-artig). `SCREEN.Height`/`Width`, `CSRLIN`/`POS`/`LOCATE` arbeiten auf der tatsächlichen Größe; `tb-ui::screen` unterstützt `resize()`. - [x] 80×25-Zellenpuffer (Zeichen + Farbattribut) als eigenes Widget rendern; kleinere Terminals: Hinweis „Terminal zu klein", größere: zentriert (Letterboxing) → `tb-ui::screen`, Demo: `cargo run -p tb-ui --example spike` - [x] 16-Farben-Palette (Vordergrund 0–15, Hintergrund 0–7) auf ANSI-Indexfarben abgebildet; Blink-Attribut vorerst ignoriert (offen) - [x] Maus-Ereignisse (crossterm) und Sondertasten (F1–F12, Alt-Kombis) im Spike sichtbar gemacht; der systematische Test je Terminal-Emulator ist Teil der Plattformtests in Phase 6 (Die Ereignisschleifen-Architektur — Terminal-Events → Event-Queue → VM-Ticks — ist Eingangsaufgabe von Phase 4.) ## Phase 1 — Sprach-Frontend (`tb-frontend`) - [x] Lexer inkl. Typ-Suffixe, Zeilennummern/Labels, `REM`/`'`-Kommentare, case-insensitive Keywords, Zeilenfortsetzung mit `_`, Hex-/Oktal- Literale, Literal-Typisierung - [x] SINGLE/DOUBLE-Schwelle suffixloser Dezimalpunkt-Literale entschieden (> 7 signifikante Stellen → DOUBLE) und in docs/sprachreferenz.md §1 dokumentiert - [x] AST für Module, Prozeduren, Anweisungen, Ausdrücke, Deklarationen - [~] Parser (zeilenorientiert, fehlertolerant — Fehler pro Anweisung gesammelt, Synchronisation bis Anweisungsende). Kern komplett: Zuweisung, PRINT (inkl. USING/#), INPUT/LINE INPUT, IF (Block + einzeilig), SELECT CASE, FOR/DO/WHILE, GOTO/GOSUB/ON-GOTO, ON [LOCAL] ERROR/RESUME, DIM/REDIM/CONST/DEFtype/OPTION/TYPE/ DECLARE/SUB/FUNCTION/CALL, DATA/READ/RESTORE, DEF FN (einzeilig). Offen: MID$-Anweisung, DEF FN-Blockform, Datei-E/A-Anweisungen (werden als Platzhalter geparst → Phase 3), `$INCLUDE`-Metabefehl - [~] Semantik: Symboltabellen, implizite Deklaration, `DEFtype`-Regeln, Typprüfung, `OPTION EXPLICIT`, Arrays (implizit/DIM/REDIM), Builtin-Signaturen, Label-Prüfung, Prozedur-Signaturprüfung. Offen: `COMMON`/`SHARED` über Prozedurgrenzen, UDT-Feldtypen, `OPTION BASE`-Auswertung, Konstantenfaltung - [~] Diagnostik mit exakten Positionen; Meldungstexte am Vorbild orientiert (Type mismatch, Duplicate definition, Label not defined …) — vollständiger Abgleich mit den Compile-Meldungen des Vorbilds offen - [x] Meilenstein: kompletter Testkorpus parst und wird typgeprüft (`crates/tb-frontend/tests/corpus.rs`) ## Phase 2 — Bytecode und VM (`tb-vm`) - [ ] Eingangsaufgabe (aus Phase 0 übernommen): Bytecode-**Feindesign** — Opcode-Satz, Zahlenkonvertierungs-Matrix (implizite Casts, Rundung, Überlauf), `STOP`/`CONT`-Verhalten im Runner ohne IDE (offene Punkte in docs/tbvm-design.md abarbeiten) - [ ] Bytecode-Format und Serialisierung (`.tbc`) - [ ] Codegenerator AST → Bytecode - [ ] Interpreter: Ausdrücke, Kontrollfluss (`IF`, `SELECT CASE`, Schleifen, `GOTO`/`GOSUB`), Prozeduraufrufe, `BYREF`-Semantik - [ ] Fehlerbehandlung: `ON ERROR GOTO/RESUME`, `ERR`/`ERL`, Fehlerkaskaden - [ ] Unterbrechbarkeit: Tick-Grenzen, Breakpoints, Einzelschritt, Variableninspektion (Grundlage für IDE-Debugger) - [ ] Benchmarks in `benches/`: Compile-Budget messen (Projekt ≈50k Zeilen < 1 s, einzelnes Modul < 50 ms) und VM-Durchsatz (Schleifen/Strings); Ergebnisse in docs/tbvm-design.md festhalten - [ ] Meilenstein: Konsolen-Testkorpus läuft mit korrekter Ausgabe (`tbc run`) ## Phase 3 — Laufzeitbibliothek (`tb-runtime`) und Bildschirm (`tb-ui::screen`) Ziel ist die **vollständige** Standardbibliothek des Vorbilds (siehe Leitplanke Vollständigkeit); die Aufzählungen unten sind Beispiele. - [ ] Vollständigkeits-Inventar erstellen: maschinenlesbare Liste aller Anweisungen/Funktionen des Vorbilds aus der Original-Hilfe (dos-help.soulsphere.org, Topic-Listen) mit Status implementiert/offen/Non-Feature → `docs/inventar.md`; ab dann Abdeckung je Phase fortschreiben - [ ] Strings: `LEFT$`, `MID$` (auch als Anweisung), `INSTR`, `STR$`/`VAL`, `SPACE$`, `STRING$`, `LTRIM$`/`RTRIM$`, `UCASE$`/`LCASE$` … - [ ] Zahlenformatierung: `PRINT`-Zonen, `PRINT USING` (vollständig; dabei offene Detailfrage klären: `%`-Präfix bei Feldüberlauf), Banker's Rounding, `CINT`/`CLNG`/`CSNG`/`CDBL`/`CCUR` - [ ] Mathematik: `RND`/`RANDOMIZE` (kompatibler PRNG!), trigonometrische Funktionen, Integer-Überlaufverhalten (Fehler 6) - [ ] Datei-E/A: `OPEN` (sequenziell/random/binär), `INPUT#`/`LINE INPUT#`, `PRINT#`/`WRITE#`, `GET`/`PUT` mit Record-Typen, `EOF`/`LOF`/`SEEK`, Pfadsemantik plattformübergreifend. Record-Layout: feste Strings als **UTF-32** (Entscheidung 2026-09-02 — 4 Bytes/Zeichen, feste Record-Länge; bewusst inkompatibel zu Vorbild-Dateien) - [ ] ISAM-Dateiunterstützung (Entscheidung 2026-09-02: wird implementiert, nicht Non-Feature): Anweisungen/Funktionen der Professional Edition (`OPEN … FOR ISAM`, Tabellen/Indizes, `SEEKGT`-Familie …) — Umfang aus der Original-Hilfe inventarisieren, dann implementieren - [ ] Breite Unicode-Zeichen (Emoji, CJK): belegen **zwei Zellen** (Entscheidung 2026-09-02) — Zellenmodell und `LOCATE`/`POS`-Semantik entsprechend umsetzen (unicode-width), Verhalten dokumentieren - [ ] Bildschirm: `PRINT`, `LOCATE`, `COLOR`, `CLS`, `INPUT`, `INKEY$`, `CSRLIN`/`POS`, `WIDTH`, `VIEW PRINT` auf dem Zellenpuffer - [ ] Offene Detailfrage klären: Umfang der `KEY n`-Funktionstasten-Makros (`KEY LIST`/`ON`/`OFF`) und in docs/sprachreferenz.md festhalten - [ ] Meilenstein: klassische Konsolenprogramme laufen unverändert ## Phase 4 — Forms-Engine (`tb-ui::forms`) - [ ] Eingangsaufgabe (aus Phase 0 übernommen): Ereignisschleifen- Architektur — Terminal-Events → Event-Queue → VM-Ticks, kooperative Zustellpunkte (`DOEVENTS`, `SLEEP`, blockierende Eingabe, Ende einer Ereignisprozedur) - [ ] Formular-Modell: Eigenschaften, Lade-/Entladezyklus, `SHOW`/`HIDE` (modal/nicht-modal) - [ ] Steuerelemente: CommandButton, TextBox, ListBox, ComboBox, CheckBox, OptionButton, Frame, Label, HScrollBar/VScrollBar, PictureBox (Text), Timer — mit allen Eigenschaften/Methoden/Ereignissen des Vorbilds - [ ] Menüsystem (Menüleiste, Shortcuts, Access Keys) - [ ] Fokus-/Tab-Reihenfolge, Access-Keys, Maussteuerung - [ ] `.FRM`-Textformat: Serialisierung **definieren** (kein Original- Beispiel verfügbar — Windows-1.0-Schema, siehe dateiformate.md), dokumentieren, dann lesen/schreiben implementieren - [ ] Ereignisdispatch: Event-Queue ↔ VM (Ereignisprozeduren `Name_Ereignis`) - [ ] Meilenstein: Beispiel-Formularprogramme aus dem Testkorpus laufen ## Phase 5 — IDE (`tb-ide`) - [ ] IDE-Rahmen: Menüleiste, MDI-artige Fensterverwaltung, Statuszeile, klassisches Farbschema - [ ] Editor: Syntaxprüfung/-normalisierung pro Zeile (Keywords groß, Leerzeichen), Suchen/Ersetzen, Hilfe-Verweise - [ ] Projektverwaltung (`.MAK`): mehrere Module/Formulare - [ ] Formular-Designer: Steuerelemente platzieren/verschieben/skalieren, Eigenschaftenfenster - [ ] Ausführen aus der IDE: Start/Unterbrechen/Fortsetzen/Neustart - [ ] Debugger: Breakpoints, Einzelschritt/Prozedurschritt, Direktfenster, Überwachungsausdrücke - [ ] Meilenstein: Programm komplett in der IDE schreiben, gestalten, debuggen und ausführen ## Phase 6 — Kompatibilität, Politur, Distribution - [ ] Kompatibilitäts-Testsuite ausbauen (Snapshot-Tests der Bildschirmausgabe) - [ ] Plattformtests: Windows Terminal, Linux (mind. 2 Emulatoren), macOS — inkl. systematischem Maus-/Sondertasten-Test (F1–F12, Alt-Kombis; aus Phase 0 übernommen) und Dokumentation bekannter Terminal-Einschränkungen - [ ] Performance-Pass über die VM (nur falls nötig) - [ ] `tbc build` → binäres Ergebnis: `.tbc`-Bytecode bzw. eigenständig ausführbares Programm (Bytecode + eingebetteter Runner) - [ ] Dokumentation: Sprachreferenz, Migrationshinweise, Beispielprogramme - [ ] CI (GitHub Actions: Build + Tests auf allen drei Plattformen), Releases --- ## Stufe 2 — Anreicherung (nach Phase 6, Ideenspeicher) Bewusste Erweiterungen jenseits des Vorbilds — additiv, der Kernstandard bleibt gültig. Noch nichts davon ist beschlossen; Sammlung wächst: - Sprachkomfort: `OPTION EXPLICIT`, Zeilenfortsetzung, `BYVAL` überall, längere Bezeichner, `&&`-Literale? (jeweils opt-in) - Terminal von heute: Bildschirmgrößen jenseits 80×25, 256/24-Bit-Farben, Scrollback, Resize-Ereignisse als Forms-Ereignis - Neue Steuerelemente (Tabelle/Grid, Baum, Statusleiste) im Stil der Forms-Engine - Standardbibliothek: Prozessaufrufe mit Pipes, Umgebungs-/Argument-Handling für CLI-Tools, JSON/CSV, HTTP-Client, Pfad-/Verzeichnisfunktionen - Verteilung: `tbc build --exe` als Single-File-Tool-Baukasten --- ## Entschiedene Fragen (2026-09-02, alle offenen Punkte geklärt) - **CURRENCY (`@`):** voll unterstützt als i64-Festkomma (×10 000); das Vorbild unterstützt den Typ laut Original-Hilfe vollständig. - **ISAM:** wird implementiert (kein Non-Feature) → Aufgabe in Phase 3. - **`PEEK`/`POKE`/`CALL INTERRUPT` u. ä. Hardware-Nähe:** nicht unterstützt; Ablehnung bereits **zur Compile-Zeit** (Meldung „Feature unavailable") — in der Semantik umgesetzt, dokumentiert in der Sprachreferenz. - **Breite Unicode-Zeichen (Emoji, CJK):** belegen **zwei Zellen** → Umsetzung in Phase 3. - **`GET`/`PUT`-Records unter Unicode:** feste Strings als **UTF-32** (4 Bytes/Zeichen, feste Record-Länge); Inkompatibilität der Binärdateien zum Vorbild wird bewusst akzeptiert → Phase 3. - **Blink-Attribut (`COLOR` 16–31):** kein echtes Blinken, Simulation als „hell" — in `tb-ui::screen` umgesetzt. - **Lizenz:** MIT (LICENSE im Repo). Neue offene Fragen werden hier gesammelt und mit Datum entschieden.