StellSi-Fahrplancompiler		Version 0.19
----------------------------------------------------

1) Einfhrung

Der StellSi-Fahrplancompiler dient zur Erzeugung von StellSi-Fahrplnen (.stwf-Dateien) aus menschenlesbaren und mit einem normalen Texteditor erzeugten Fahrplanquelldateien (.stwfq und .stwfd). Dabei kann ein Fahrplan fr ein ganzes Streckennetz aus nur einer Datei erzeugt werden.

Hierfr wurde eine sehr schlichte, imperative Programmiersprache entwickelt, deren Handhabung und Funktion im folgenden erlutert wird.


2) Aufbau einer Fahrplanquelldatei

Fahrplanquelldateien sind UTF-8-enkodierte Textdateien, die aus einem Header und einer Sequenz von Kommandos bestehen. Der Header definiert die zugrundeliegende Version der Programmiersprache und sieht wie folgt aus:

	StellSi	FplDef 1

Jedes Kommando beginnt mit einer neuen Zeile und besteht aus einem Befehl, gefolgt von Argumenten:

	CMD	[Arg1]	[Arg...]

Optional knnen auch noch Datenblcke angehngt sein. Diese sind in geschweifte Klammern { } eingeschlossene, mehrzeilige Datenabschnitte. Diese Datenblcke beginnen mit dem ersten Token hinter dem letzten Argument.

Kommentare, d.h. vom Compiler ignorierte Anmerkungen, knnen mit // eingeleitet werden und erstrecken sich ber den Rest der Codezeile. Alternativ sind mit /* und */ eingeschlossene Abschnitte (auch ber Zeilen hinweg) Kommentare.


3) Tokens

Der Programmcode wird aus sog. Tokens gebildet, d.h. Blcken aus zusammenhngenden Zeichen und Ziffern. Ein neues Token beginnt nach einem Leerzeichen, Tabulator-Zeichen, Zeilenumbruch, Klammer oder Operator. Folgende Operatoren/Sonderzeichen sind derzeit definiert:

	->	<-	+	-	.	,	~	*	$

Eine Sonderrolle kommt Anfhrungszeichen zu: In Anfhrungszeichen eingeschlossener Text wird als ein Token interpretiert. Derartige Abschnitte drfen sich nicht ber mehrere Zeilen erstrecken.


4) Kommandos

Die folgend beschriebenen Kommandos sind derzeit definiert:

4.1) AUT [Autor] [Kommentar]

Fgt einen Autor in den erzeugten Fahrplnen hinzu. [Autor] ist der Name des Autors, [Kommentar]das Kommentarfeld.

4.2) BIB [ID] [Pfad]

Ldt eine StellSi-Bibliothek (.stwb) in den Fahrplan; blicherweise ntig fr Fahrzeugbibliotheken. [ID] ist dabei eine eindeutige Zahl, die die Biblitohek spter identifiziert. Als [Pfad] muss ein StellSi-lesbarer Pfad angegeben werden, dieser wird i.d.R. mit "/lib" beginnen.

4.3) FZG [Name] [Bib-ID] [Fzg-ID]

Dieser Befehl ist hilfsweise notwendig, um spter einfach Reihungen definieren zu knnen. Hierbei werden Aliasnamen [Name] fr Fahrzeuge angelegt, die ber die ID der Bibliothek [Bib-ID] und die innerhalb dieser .stwb-Datei von StellSi vergebenen [Fzg-ID] definiert werden.

4.4) BTR [Kurz] [Lang]

Dieser Befehl legt in der Betriebsstellenliste Aliasnamen [Kurz] fr eine Betriebsstelle mit dem angegebenen Langnamen [Lang] an.

4.5) AA [Name] [Pfad] ([Suffix]) {Daten}

Mit diesem Befehl wird eine weitere Auenanlage unter der ID [Name] in die Liste der Auenanlagen eingefgt. [Pfad] beschreibt den Dateipfad zu dieser Auenanlage. Aus der Datei werden auch Betriebsstellen gelesen, die DS100-Abkrzungen aus der .stwa-Datei werden wie ein BTR-Kommando behandelt. Bei einem leeren Pfad wird die Auenanlage als Platzhalter betrachetet. Mit dem [Suffix] knnen mehreren Auenanlagen im gleichen Verzeichnis in den Ausgabedateien voneinander getrennt werden.

Im Datenblock werden zeilenweise die Fahrtrichtungen definiert. Jede Fahrtrichtung definiert sich wie folgt:

	[Kurzname] ([Beschriftung]) ([Streckenanschluss-IDs...]) (LZ [Lenkziffern...])

Der [Kurzname] ist ein Aliasname fr die Fahrtrichtung, die [Beschriftung] wird spter in der Zugliste als Fahrtrichtung angezeigt. Dem folgt eine Liste beliebig vieler [Streckenanschluss-IDs]. Dabei handelt es sich um die von StellSi in der .stwa-Datei vergebenen IDs. Die Reihenfolge bestimmt, ber welchen Anschluss die Zge bevorzugt angeboten werden. Diese knnen weggelassen werden, sofern in der Auenanlage eine Fahrtrichtung definiert ist, deren Name der [Beschriftung] entspricht. Auch die [Beschriftung] kann weggelassen werden, sofern in der Auenanlage ein passender [Kurzname] fr die Fahrtrichtung vergeben wurde.

Folgt auf die [Streckenanschluss-IDs] das Schlsselwort "LZ", so folgt anschlieend noch eine Auflistung aller Lenkziffern, die in dieser Fahrtrichtung verwendet werden. Hieraus ermittelt der Compiler fr die Zge automatisch eine passende Lenkziffer.

4.6) RHG [Name] [Fzg-IDs...]

Definiert eine Reihung mit dem angegebenen [Name]n, bestehend aus den angegebenen Fahrzeugen (siehe FZG-Kommando). Durch den vorangestellten Operator ~ kann ein Fahrzeug gedreht eingefgt werden.

4.7a) VT * [Von] [Bis]

Schrnkt die Gltigkeit aller impliziten Verkehrstage ein auf die angegebene Spanne. Die Argumente sind in folgendem Format anzugeben: "YYYY-MM-DD".

4.7b) VT [Name] [Tage] [Von] [Bis] [Ausschluss] [Einschluss]

Definiert einen Verkehrstag mit dem angegebenen [Name]n. Die Zge verkehren an den angegebenen [Tage]n. Dabei handelt es sich um eine Folge von Ziffern zwischen 1 und 7, die den jeweiligen Wochentag (Montag bis Sonntag) beschreiben. [Von] und [Bis] geben die Zeitspanne der Gltigkeit an. [Ausschluss] und [Einschluss] knnen mit Semikolon separierte Listen enthalten, um bestimmte Tage ausdrcklich ein- bzw. auszuschlieen. Alle Daten sind im Format "YYYY-MM-DD" anzugeben. Achtung: Der Tageswechsel wird bei Berechnungen nur fr den Parameter [Tage] bercksichtigt. Ebenso werden die weiteren Parameter fr die Ermittlung von Folgezgen ignoriert.

4.8) ZL [Name] {Daten}

Erzeugt einen Zuglauf mit dem angegebenen [Name]n. Im Datenblock wird der Fahrplan definiert. Jeder Fahrplaneintrag (Einfahrten, Ausfahrten und Halte) nimmt dabei eine Zeile ein, die wie folgt aussieht:
Einfahrt: <- [AA-Name] . [Anschluss-Name] ([Zeit])
Ausfahrt: -> [AA-Name] . [Anschluss-Name] ([Zeit])
Halt: [BTR-Name] . [Signaltyp] [Gleis] [Ankunftzeit] [Abfahrtzeit] [Mindesthaltezeit] ([Auftrge...])
Durchfahrt/Abfahrt: [BTR-Name] . [Signaltyp] [Gleis] - [Abfahrtzeit] ([Auftrge...])
Ankunft: [BTR-Name] . [Signaltyp] [Gleis] [Ankunftzeit] - ([Auftrge...])
Hinweise: $ [Hinweisname] [Argument]

[AA-Name] bezieht sich auf das Kommando AA, [Anschluss-Name] auf dessen Datenblock. [BTR-Name] bezieht sich auf das Kommando BTR. Der [Signaltyp] kann H (H-Tafel), E (Einfahrsignal), A (Ausfahrsignal), Z (Zwischensignal), B (Blocksignal) oder AB (Blocksignal an Abzweigstelle) sein.

Wird bei einer Ein- oder Ausfahrt der Parameter [Zeit] weggelassen, wird eine geeignete Zeit automatisch ermittelt. Voraussetzung ist, dass ein Halt oder eine Durchfahrt vor bzw. nach dem Eintrag angegeben wurde.

Zu den Eintrgen knnen Auftrge angegeben werden. Folgende Auftrge sind mglich:
- WENDE: Zug wendet an der Betriebsstelle.
- FOLGE: Zug wechselt auf die Folgeleistung. Es ist eine Zugnummernregel der Form "ZN (+- ) [Wert]", oder "ZN *" anzugeben. Letzteres nutzt die automatische Ermittlung von Folgeleistungen.
- GATTUNG: Zug wechselt auf die angegebene Gattung.
- LINIE: Zug wechselt auf die angegebene Gattung und Liniennummer.
- LZ: Zug wechselt seine Lenkziffer. Es ist die neue Lenkziffer anzugeben. Ist zwischen LZ und Lenkziffer ein *, handelt es sich nur um einen Lenkziffernhinweis fr die automatische Lenkziffernbestimmung.

Mit Hinweisen knnen Zusatzangaben gesetzt werden, damit die richtigen Fahrwege genutzt werden. Er bezieht sich jeweils auf den vorherigen und alle nachfolgenden Eintrge. Derzeit ist nur der Hinweis "VzG" untersttzt; als Argument wird eine Streckennummer erwartet.

4.9) ZLS [BTR-Name 1] ([VzG-Nummer]) [BTR-Name 2] {Daten}

Erzeugt ein Zuglaufsegment. Wann immer in einem Zuglauf die erste angegebene Betriebsstelle ([BTR-Name 1]) von der Zweiten gefolgt wird, werden die im Datenblock angegebenen Eintrge eingefgt. Der Datenblock entspricht dem Kommando ZL, untersttzt derzeit aber nur Ein- und Ausfahrten.

Ist eine VzG-Nummer angegeben, wird das Zuglaufsegment nur auf Zge angewendet, die gem Hinweis ber die angegebene Strecke verkehren sollen.

4.10) SET [Variable] [Wert]

Setzt die angegebene [Variable] auf den gegebenen [Wert]. Als Wert kommen - je nach Variable, auch komplexe Ausdrcke wie Listen oder Zuglaufspezifikationen in Frage.

Die Variable "Linie" ist dabei ein Alias fr die Variable "Gattung" gefolgt von "Liniennummer".

4.11a) Z [Zugnummer] [Startzeit] [Verkehrstag] ([Gattung])

Erzeugt einen Zug mit der angegebenen [Zugnummer] mit dem gegebenen [Verkehrstag] zur gegebenen [Startzeit]. Letztere fungiert als Offset zum aktuellen Zuglauf. Die Angabe einer [Gattung] ist optional. Als weitere Parameter des Zugs werden die Variablen "Gattung" (wenn nicht angegeben), "Liniennummer" (wenn keine Gattung angegeben), "Reihung" und "Zuglauf" zugrundegelegt.

4.11b) Z [Zugnummer] [ZL-Spezifikation] [Verkehrstag] ([Gattung])

Verglichen mit dem vorigen Befehl wird anstelle der Variable "Zuglauf" eine Zuglauf-Spezifikation entgegengenommen.

4.11c) Z [Zugnummer] * [Verkehrstag] ([Gattung]) {Daten}

Verglichen mit dem vorigen Befehl wird anstelle der Variable "Zuglauf" ein eigener, im Datenblock definierter impliziter Zuglauf erzeugt. Das Format des Datenblocks entspricht dem Kommando ZL.

4.12a) TZ (Liste) [Startzeit erster Zug] [Schrittweite Zeit] [Verkehrstag]

Erzeugt mehrere Zge zugleich: Die aufgelisteten Zge werden angelegt. Die [Startzeit erster Zug], jeweils inkrementiert mit [Schrittweite Zeit] wird zugrundegelegt, und fr alle Zge der angegebene [Verkehrstag] gesetzt. Wie beim Kommando Z werden dabei die Variablen "Gattung", "Liniennummer", "Reihung" und "Zuglauf" zugrundegelegt.

4.12b) TZ * [Verkehrstag] {Daten}

Erzeugt mehrere Zge zugleich: Der Datenblock enthlt jeweils Prchen aus Zugnummer und Startzeit. Wie beim Kommando Z werden dabei die Variablen "Gattung", "Liniennummer", "Reihung" und "Zuglauf" zugrundegelegt.

4.12c) TZ [Zugnummer Start] [Zugnummer Ende] [Schrittweite Zugnummer] [Startzeit erster Zug] [Schrittweite Zeit] [Verkehrstag] (Veraltet)

Erzeugt mehrere Zge zugleich: Die Zge von [Zugnummer Start] bis [Zugnummer Ende], mit der angegebenen [Schrittweite Zugnummer] werden angelegt. Die [Startzeit erster Zug], jeweils inkrementiert mit [Schrittweite Zeit] wird zugrundegelegt, und fr alle Zge der angegebene [Verkehrstag] gesetzt. Wie beim Kommando Z werden dabei die Variablen "Gattung", "Liniennummer", "Reihung" und "Zuglauf" zugrundegelegt.

4.13a) M (Liste) [Modifikationsregel]

Dieser Befehl modifiziert die durch die Liste selektierten Zge anhand der angegebenen [Modifikationsregel]. Die nderungen wirken nur auf die ausgewhlten Zge; andere Zge, die den gleichen Zuglauf nutzen, sind nicht betroffen.

Folgende Modifikationsregeln sind derzeit definiert:

- Setzen des Verkehrstags: VT [Verkehrstag]
- Setzen der Zuggattung: GATTUNG [Gattung]
- Setzen der Reihung: RHG [Reihung]
- Setzen des Zuglaufs: ZL [ZL-Spezifikation]
- Setzen der Linie: LINIE [Gattung] [Linie]
- Subtraktion/Addition von Verkehrstagen: VT (+-) [Verkehrstag] (nicht implementiert)
- ndern der Regel fr die Folgeleistung: FOLGE (+- ) [Wert]
- Lschen eines Fahrplaneintrags: ENTF [BTR-Name] . [Signaltyp], oder LOE <- [AA-Name], oder LOE -> [AA-Name] (nicht implementiert)
- Einfgen eines Fahrplaneintrags: EINFG (nicht implementiert)
- ndern eines Fahrplaneintrags: EDIT (nicht implementiert)
- Setzen der Auftrge an einem Fahrplaneintrag: AUFTRAG [BTR-Name] . [Signaltyp] [Auftrge...]

4.13b) M (Liste) (Einschrnkung) [Modifikationsregel]

Dieser Befehl modifiziert die durch die Liste selektierten Zge unter Beachtung der gegebenen Einschrnkung anhand der angegebenen [Modifikationsregel]. Die nderungen wirken nur auf die ausgewhlten Zge; andere Zge, die den gleichen Zuglauf nutzen, sind nicht betroffen.

4.14) OUT [Name] [Pfadregel]

Dieser Befehl dient abschlieend der Erzeugung von .stwf-Dateien aus den zuvor angelegten Fahrplandaten. Als Fahrplanname wird der gegebene [Name] gesetzt. Es wird pro Auenanlage (siehe Kommando AA) eine .stwf-Datei generiert. Zur Erzeugung der Dateien wird die [Pfadregel] genutzt, ein String, der den Ausgabedateinamen angibt. Damit hier tatschlich mehrere Dateien erzeugt werden knnen, sind zwei Sonder-Makros definiert:
$(ThisStwDir): Nutzt das Verzeichnis der jeweiligen Auenanlage.
$(ThisStwPath): Nutzt Verzeichnis und Dateiname der jeweiligen Auenanlage.
$(AASuffix): Fgt Auenanlagen-spezifischen Suffix ein.

4.15) DAT [Datei]

Mit diesem Befehl kann eine weitere Fahrplanquelldatei geladen und ausgefhrt werden. Diese Dateien mssen in sich gltige Quelldateien sein und werden an der Stelle des DAT-Befehls rekursiv ausgefhrt. Hierdurch knnen Fahrplne auf mehrere Quelldateien verteilt oder streckenspezifische Daten von Fahrplandaten getrennt werden. Empfohlene Dateiendung ist .stwfd.

4.16) BIF [Name] {Daten}

Fr das mitgelieferte Bildfahrplan-Programm definiert dieses Kommando eine Strecke, d.h. Ansicht. Der Datenblock enthlt zeilenweise die Daten, die abwechselnd folgenden Formaten entsprechen:
Betriebsstelle: [Typ] [BTR-Name] [Streckenkilometer] (| [Streckenkilometer])
Strecke: [Anzahl Gleise] ($ (*) [VzG-Nummer])

Die zweite [Streckenkilometer]-Angabe kann fr Kilometrierungswechsel genutzt werden.

Vor und nach Betriebsstellen kann folgendes eingefgt werden:
Streckenfilter: -> [AA-Name] . [Anschluss-Name]
                <- [AA-Name] . [Anschluss-Name]
Bahnhofsfilter: * [BTR-Name]

Der Betriebsstellen-[Typ] kann Bf, Abzw, Uest, Hp oder Bk sein. Der Streckenkilometer ist als Fliekommazahl anzugeben. Der Streckenfilter wirkt jeweils im Zulauf auf die zugehrige Betriebsstelle. Mehrere Filter knnen mit dem Operator | getrennt werden.

Zur Strecke kann eine VzG-Nummer angegeben werden. Ist diese mit einem * gekennzeichnet, werden nur Zge gezeichnet, die explizit diese Strecke befahren.

5) Namen

Wann immer IDs oder Namen vergeben werden, werden die in nach Objekttypen separierten Listen gefhrt. Das bedeutet, es kann z.B. Auenanlagen (Kommando AA) und Betriebsstellen (BTR) unter demselben Namen geben. Innerhalb der jeweilgen Liste mssen die Namen allerdings eindeutig sein, eine Neudefinition berschreibt die vorangehende.


6) Verkehrstage

Verkehrstage knnen explizit und implizit definiert werden. Die explizite Definition erfolgt ber das Kommando VT. Es lassen sich jedoch berall, wo ein Verkehrstag anzugeben ist, auch implizite Definitionen nutzen. Hierzu sind die Operatoren '+', ',' und '-' implementiert, mit denen Verkehrstage zusammengefhrt ('+' und ',') und Bereiche gebildet ('-') werden knnen. Diese Ausdrcke sind in runde Klammern zu setzen. Zustzlich sind die Verkehrstage Mo, Di, Mi, Do, Fr, Sa und So definiert. Der implizite Verkehrstag (Mo-Mi,Fr) lsst einen Zug Montags, Dienstags, Mittwochs und Freitags fahren. Aus Komfortgrnden ist zudem "tgl" fr tgliche Zge vordefiniert.


7) Listen

Listen werden mit runden Klammern umschlossen. Im Inneren knnen entweder die Listenelemente direkt aufgelistet werden, oder eine Funktion zur Erzeugung der Elemente genutzt werden. Als Funktionen definiert sind:

LISTE [Elemente...]: Auflistung aller Elemente, mit Leerzeichen getrennt
SCHLEIFE [Start] [Ende] [Schrittweite]: Generiert die Zahlen von [Start] bis [Ende] mit der angegebenen [Schrittweite].


8) Einschrnkungen

Einschrnkungen werden mit runden Klammern umschlossen. Derzeit sind nur Einschrnkungen folgenden Typs zulssig: (WENN VT [Verkehrstag])


9) Zuglauf-Spezifikationen

Zuglauf-Spezifikationen werden mit runden Klammern umschlossen. Im Inneren werden sie mit "ZL" eingeleitet, gefolgt von abwechselnd einer Zeitangabe und dem Namen eines Zuglaufs. Die Zeitangabe ist optional - fehlt sie, wird Null angenommen. Die erste Zeitangabe definiert die Basiszeit, die folgenden Zeiten definieren die bergangszeit zwischen den Zuglufen. Beginnt der nachfolgende Zuglauf mit derselben Betriebsstellenspezifikation, mit der der vorherige endet, entspricht die bergangszeit der planmigen Haltezeit. Etwaige Auftrge werden vom vorherigen Zuglauf bernommen. Sind die Betriebsstellen verschieden, so entspricht die bergangszeit der Fahrtzeit. Das Gleis wird vom vorherigen Zuglauf bernommen, auer, es ist mit "-" angegeben. Die Mindesthaltezeit wird vom vorherigen Zuglauf bernommen, auer, es wurde keine angegeben.


10) Folgeleistungen

Die automatische Ermittlung von Folgeleistungen (Auftrag "FOLGE ZN *") sucht fr jeden Zug mit dieser Regel an jedem Wochentag die zeitlich nchste Fahrplanleistung, die auf demselben Gleis derselben Betriebsstelle beginnt. Das Suchfenster erstreckt sich dabei auf den aktuellen und folgenden Wochentag. Wird keine Folgeleistung gefunden, wird eine Warnung generiert.
