# 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 Schreiben einer gelesenen Formularbeschreibung SHALL dieselbe Datei
ergeben. Geschrieben SHALL nur werden, was vom Vorgabewert abweicht;
Reihenfolge und Einrückung SHALL festgelegt und dokumentiert sein, damit
zwei Läufe dieselbe Datei erzeugen.

#### 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** ein Steuerelement nur Vorgabewerte trägt
- **THEN** enthält sein Block außer `Begin`/`End` keine Eigenschaftszeile

### 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