86 lines
4.1 KiB
Markdown
86 lines
4.1 KiB
Markdown
# 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
|