TerminalBasic/openspec/changes/archive/2026-09-05-phase-4-frm/design.md

Design — Formulardateien und Konvertierung

Context

Siehe proposal.md — Why. Ausgangslage: docs/dateiformate.md hält das Schema des Windows-Schwesterprodukts als Vorlage fest und markiert die exakte Serialisierung als offen. Die Formularbeschreibung, die gelesen und geschrieben wird, stammt aus phase-4-objektmodell; dieser Change fügt nur Ein- und Ausgabe hinzu.

Goals / Non-Goals

Goals:

• Ein Format, das ein Mensch im Editor bearbeiten kann und das ein Werkzeug reproduzierbar schreibt.
• Binäre Beispieldateien werden lesbar, ohne dass wir das Binärformat jemals schreiben.

Non-Goals:

• Binärkompatibilität in Schreibrichtung.
• Verlustfreie Übernahme von Eigenschaften, die es bei uns nicht gibt (etwa reine Windows-Eigenschaften aus Version 2.00).

Decisions

D1 — Wir legen die Serialisierung fest und dokumentieren sie als Referenz

Es gibt keine Originalfassung zum Nachbilden. Festgelegt wird das Sparsamste, das den Rundlauf trägt:

VERSION 1.00
Begin Form Form1
   Caption         =  "Beispiel"
   Height          =  15
   Begin CommandButton cmdOK
      Caption         =  "&OK"
   End
End

• Drei Leerzeichen Einrückung je Ebene, Eigenschaftsname auf 16 Spalten aufgefüllt, = mit zwei Leerzeichen davor und danach — die Optik des Vorlagenschemas.
• Nur Eigenschaften, die vom Vorgabewert abweichen. Das hält Dateien klein und macht Vorgabewertänderungen sichtbar, statt sie in Altbeständen einzufrieren.
• Reihenfolge: alphabetisch wie in der Forms-Referenz je Klasse, nicht die Einfügereihenfolge — sonst hängt die Datei von der Bedienung des Designers ab.

D2 — Rundlauf ist die Prüfung, nicht der Vergleich mit einer Sollddatei

Da das Format unsere Festlegung ist, prüft ein Vergleich gegen eine handgeschriebene Solldatei nur uns selbst. Aussagekräftig ist der Rundlauf: lesen, schreiben, byte-vergleichen — und zusätzlich schreiben, lesen, Beschreibung vergleichen. Beide Richtungen fangen verschiedene Fehler.

D3 — Der Binärleser bleibt eigenständig und liest nur

Das Reverse Engineering erschließt den Aufbau aus den Beispieldateien. Der Leser übersetzt in dieselbe Formularbeschreibung wie der Textleser und teilt sich mit ihm die Prüfungen. Was er nicht erkennt, bricht ab — eine „beste Vermutung" hinterließe ein Formular, das anders aussieht als das Original, ohne dass jemand es merkt.

Unbekannte Eigenschaften aus dem Windows-Erbe werden beim Konvertieren namentlich gemeldet und übersprungen; die Zusammenfassung nennt sie am Ende, damit sie nicht in der Ausgabeflut untergehen.

Risks / Trade-offs

• Das Binärformat ist nur teilweise erschließbar → der Befehl bricht ab, statt zu raten; die dokumentierte Fundstelle sagt, wo es endete.
• „Nur Abweichungen schreiben" verliert Werte, wenn sich ein Vorgabewert ändert → die Vorgabewerte stehen im Inventar und in der Forms-Referenz; eine Änderung dort ist ein bewusster Vorgang.
• Version 2.00 kennt Eigenschaften, die wir nicht haben → beim Lesen namentlich gemeldet und übersprungen, nicht als Fehler behandelt.

Open Questions

• Ob eine Formulardatei mehrere Formulare enthalten darf, klärt sich mit der Projektverwaltung (.MAK, Phase 5); bis dahin gilt: ein Formular je Datei.