# forms-dateiformat Specification

## Purpose

Das Formulardateiformat legt fest, wie ein Formular samt seiner
Steuerelemente und seines Codes als Textdatei abgelegt, wieder gelesen
und aus binären Dateien des Vorbilds übernommen wird — die Grundlage
dafür, dass Formulare überhaupt gespeichert und ausgetauscht werden
können.

## Requirements

### Requirement: Aufbau des Textformats
Eine Formulardatei SHALL aus einer `VERSION`-Zeile, einem
Beschreibungsteil und einem Codeteil bestehen. Der Beschreibungsteil
SHALL aus verschachtelten Blöcken `Begin <Klasse> <Name>` … `End` mit
Zeilen `Eigenschaft = Wert` bestehen; Zeichenketten stehen in
Anführungszeichen. Der Codeteil SHALL gewöhnlicher Quelltext des
Formularmoduls sein. Die Versionen `1.00` und `2.00` SHALL angenommen
werden; eine andere Version MUST mit Nennung der vorgefundenen Version
abgewiesen werden.

#### Scenario: Formular mit einem Steuerelement
- **WHEN** eine Datei ein `Form`-Blockelement mit einem eingebetteten `CommandButton`-Block und anschließendem `SUB`-Code enthält
- **THEN** entsteht daraus eine Formularbeschreibung mit einem Steuerelement und dem zugehörigen Quelltext

#### Scenario: Unbekannte Version
- **WHEN** die Datei mit `VERSION 3.00` beginnt
- **THEN** wird sie abgewiesen und die Meldung nennt `3.00`

### Requirement: Schreiben ist die Umkehrung des Lesens
Das unveränderte Schreiben einer gelesenen Formularbeschreibung SHALL
die Originaldatei bytegleich erhalten, einschließlich explizit
geschriebener Vorgabewerte. Beim kanonischen Schreiben einer neuen oder
geänderten Beschreibung SHALL nur geschrieben werden, was vom
Vorgabewert abweicht. Für diese kanonische Ausgabe SHALL Reihenfolge
und Einrückung festgelegt und dokumentiert sein, damit zwei Läufe
dieselbe Datei erzeugen. Ein expliziter Control-Array-Index SHALL auch bei
`Index = 0` erhalten bleiben; er ist eine Strukturangabe und kein auslassbarer
Eigenschaftsdefault.

#### Scenario: Rundlauf
- **WHEN** eine Formulardatei gelesen und unverändert wieder geschrieben wird
- **THEN** ist die geschriebene Datei byte-gleich zur gelesenen

#### Scenario: Vorgabewerte werden nicht geschrieben
- **WHEN** eine neue oder geänderte Beschreibung kanonisch geschrieben wird und ein Steuerelement nur Vorgabewerte trägt
- **THEN** enthält sein Block außer `Begin`/`End` keine Eigenschaftszeile

#### Scenario: Expliziter Default im unveränderten Original
- **WHEN** eine gelesene Datei einen Vorgabewert ausdrücklich enthält und unverändert geschrieben wird
- **THEN** bleibt auch diese Eigenschaftszeile bytegleich erhalten

#### Scenario: Arrayelement mit Index null
- **WHEN** ein Formular mit einem einzigen Control-Arrayelement `Index = 0` kanonisch geschrieben und erneut gelesen wird
- **THEN** bleibt das Control ein Array und seine Indexangabe erhalten

### Requirement: Fehlerhafte Dateien werden benannt
Eine unbekannte Klasse, eine für die Klasse unbekannte Eigenschaft, ein
Wert außerhalb des Wertebereichs und ein unausgeglichener Block MUST je
mit Dateiname, Zeilennummer und dem betroffenen Namen gemeldet werden.
Eine solche Datei MUST NOT teilweise übernommen werden.

#### Scenario: Unbekannte Eigenschaft
- **WHEN** ein `CommandButton`-Block die Zeile `Farbe = 3` enthält
- **THEN** nennt die Meldung Datei, Zeile, `CommandButton` und `Farbe`

#### Scenario: Unausgeglichener Block
- **WHEN** einer Datei ein `End` fehlt
- **THEN** nennt die Meldung die Zeile des offenen `Begin`-Blocks

### Requirement: Konvertierung binärer Formulardateien
Ein Unterbefehl SHALL eine binäre Formulardatei des Vorbilds (Kennung
`FC 08 01 00`) in das Textformat übersetzen. Eine nicht erkannte oder
beschädigte Datei MUST mit Nennung der Fundstelle abgewiesen werden;
eine Teilausgabe MUST NOT entstehen. Der erschlossene Aufbau des
Binärformats SHALL dokumentiert sein.

#### Scenario: Bekannte Beispieldatei
- **WHEN** eine binäre Beispieldatei konvertiert wird
- **THEN** entsteht eine Textdatei, deren Lesen dieselbe Formularbeschreibung ergibt wie die dokumentierte Erwartung

#### Scenario: Fremde Datei
- **WHEN** eine Datei ohne die Kennung übergeben wird
- **THEN** bricht der Befehl mit einer Meldung ab und schreibt keine Ausgabedatei
