Initial commit

.gitignore

@@ -0,0 +1,6 @@
+*.html
+*.pdf
+*.tex
+*.aux
+*.log
+*.out

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "grapho"]
+	path = grapho
+	url = ../grapho.git

Makefile

@@ -0,0 +1,16 @@
+NAME=KsKit
+
+default: index.html $(NAME).pdf
+
+index.html: README.md
+	awk -f grapho/md2html <$< >$@
+
+$(NAME).tex: README.md
+	awk -f grapho/md2tex <$< >$@
+
+$(NAME).pdf: $(NAME).tex
+	pdflatex $<
+	pdflatex $<
+
+clean:
+	rm -f *.html *.pdf *.tex *.aux *.log *.out

README.md

@@ -0,0 +1,65 @@
+# KsKit für Eisenbahn.exe
+
+KsKit ist eine Sammlung von Lua-Funktionalität, welche ich auf meinen Anlagen für eine vorbildgerechte Signalisierung einsetze.
+Die hier geschilderten Anwendungsfälle und Programmsnipsel stellen kein Komplettpacket dar, sondern sind eher wie ein Kuchen anzusehen, aus denen man sich ein paar Rosinen rauspicken darf.
+
+Aus dem Basisscript dürfen Teile entnommen werden und anderswo verwendet werden, dabei ist die Herkunft und Versionsnummer zu nennen, z.B. als Quellcode-Kommentar.
+Die Versionsnummer befindet sich am Anfang des Basisscripts und kann über die Variable `KsKitVer` abgefragt werden.
+
+## Einrichtung
+
+Das KsKit-Verzeichnis wird im EEP-Stammverzeichnis, dort im LUA/ Unterverzeichnis als ganzes hin entpackt.
+
+![So sieht das KsKit-Verzeichnis im Windows Explorer aus](img/einrichtung.png)
+
+Die Einbindung vom Anlagenscript aus erfolgt mittels `require("kskit")`.
+
+**Wichtig**: Wenn KsKit verwendet wird, darf keine EEPMain definiert sein. 
+
+Findet EEP die Dateien von Lua nicht, wird im Ereignisfenster eine Liste von Orten ausgegeben, an denen die Dateien gesucht wurden.
+Die Orte sind in diesem Fall mit dem Installationsort abzugleichen.
+
+## Allgemeine Lua-Kniffe
+
+Bei der Entwicklung des Basisscriptes haben sich einige Mechanismen als sehr praktisch erwiesen, um die Komplexität des Codes im Zaum zu halten.
+
+### Mainfunktionen
+
+Das Basisscript bringt eine eigene EEPMain mit, daher darf von Seiten des Anlagen-Scriptes keine weitere EEPMain definiert werden.
+Soll Lua-Code im Rahmen der EEPMain ausgeführt werden, wird mittels MainFunktion() eine Lambda-Funktion registriert.
+Als Argument wird eine Funktion übergeben, welche keine Argumente nimmt.
+Diese Funktion wird dann in jedem Zyklus einmal aufgerufen.
+
+Der Vorteil dieser Verfahrensweise liegt darin, das vom User keine EEPMain mit Referenzen auf verschiedene Anlagenkomponenten angelegt und aktualisiert werden muss.
+Auf einer Anlage können beliebig viele Mainfunktionen eingesetzt werden.
+
+```
+MainFunktion(function()
+  if EEPGetSignalTrainsCount(1) > 0 then
+    EEPSetSignal(1, 1, 1)
+   end
+end)
+```
+
+Dieser Programmcode bindet eine Funktion an die EEPMain.
+Die Funktion fragt ab, ob vor einem Signal ein Zug steht und schaltet in diesem Falle das Signal auf Fahrt.
+
+### Signalfunktionen
+
+Analog zu den Mainfunktionen ergibt sich ein ähnliches Problem mit den Signal-Callbacks.
+Ein herkömmlicher Signal-Callback kann nur an einer einzigen Stelle definiert werden.
+An einigen Stellen ist es jedoch notwendig, das mehrere Stellen über ein Umschalten eines Signals informiert werden wollen.
+
+Mittels der SignalFunktion kann eine Funktion an ein Signal angebunden werden.
+Ändert das Signal nun seine Stellung, wird die Funktion mit der neuen Stellung als Argument aufgerufen.
+
+Als konkretes Beispiel sind einzelnstehende Vorsignale im Bahnhofsbereich zu betrachten.
+Mehere Vorsignale können von einem Hauptsignal abhängig sein und benötigen Informationen über dessen Schaltzustand als auch über den Schaltzustand der dazwischenliegenden Fahrstrasse.
+
+Als Beispiel wird eine Signalfunktion definiert, welche lediglich die neue Stellung eines Signals ausgibt:
+
+```
+SignalFunktion(1, function(Stellung)
+  print("Signal auf ", Stellung, " umgestellt")
+end)
+```

grapho

@@ -0,0 +1 @@
+Subproject commit 094ef7a2de22c7698938877eaf22b4d958722805

init.lua

@@ -0,0 +1,39 @@
+-- Versionsnummer. Diese dient vor allem zu Diagnosezwecken.
+-- Ich weiss jetzt noch nicht, wie viele verschiedene Versionen von dem Script spaeter herumfliegen werden.
+KsKitVersion=0
+
+-- Tabelle, in der alle Lambda-Funktionen gespeichert werden
+-- Die Eintragung erfolgt durch die MainFunktion() vom Zielort aus.
+MainFunktionTabelle={}
+
+-- Neues Main-Lambda registrieren
+function MainFunktion(Funktion)
+  table.insert(MainFunktionTabelle, Funktion)
+end
+
+-- Alle Main-Lambda's ausfuehren
+-- Dies ersetzt die Standard-EEP-Main Funktion.
+function EEPMain()
+  for cnt = 1, #MainFunktionTabelle do
+   MainFunktionTabelle[cnt]()
+  end
+  return 1
+end
+
+-- Neues Signal-Lambda registrieren
+SignalFunktionen = {}
+function SignalFunktion(Signal, Funktion)
+  if not SignalFunktionen[Signal] then
+    EEPRegisterSignal(Signal)
+    -- Callback bei EEP registrieren
+    _G["EEPOnSignal_"..tostring(Signal)]=function(Stellung)
+      -- Alle registrierten Lambdas ausfuehren
+      for cnt = 1, #SignalFunktionen[Signal] do
+       SignalFunktionen[Signal][cnt](Stellung)
+      end
+    end
+    SignalFunktionen[Signal]={}
+  end
+  -- In unsere eigene Tabelle eintragen
+  table.insert(SignalFunktionen[Signal], Funktion)
+end