Das Lua-Tutorial - 2 Tipps und Bibliotheken

== Das Lua-Tutorial - #2 Tipps und Bibliotheken == Im ersten Teil wurde geklärt, was eine Skriptsprache ist, welchen Editor man für die Bearbeitung nehmen sollte. Es wurden die wichtigsten Sprachelemente wie Variablen, If-Else-Verzweigungen, Schleifen, Funktionen und Tabellen vorgestellt. Am Ende dieses Teils beherrscht man folgende Grundlagen [list][*]Lösen von Programmierfehlern [*]Zurechtfinden im offiziellen Lua-Handbuch [*]Vereinfachen gängiger Arbeiten [*]Projektorganisation und Teamarbeit [*]Allgemeine Funktionen und die math-Bibliothek [/list] === Lösen von Programmierfehlern === Die meisten Fehlerquellen kennt jeder: [list][*]Tippfehler [*]Nichtbeachtung der Großschreibung [*]Übergabe eines fehlerhaften Parameters [*]Illegaler Aufruf einer Funktion [*]Zugriff auf eine Variable, die nicht existiert [*]Logikfehler [/list]Doch wenn diese Fehler auftreten, können besonders die letzteren viel Suchzeit in Arbeit beanspruchen, sogar einige Tage. [img='http://rail-sim.de/wiki/images/1/1f/PP_LUATUT02_01_Fehlermeldung.png',left,429][/img]Tippfehler sind schnell zu finden: Stimmt der Quellcode nicht, meldet der Interpreter, dass etwas nicht stimmt und benennt möglichst genau die betroffene Stelle. Dazu klickt im Dialog der Fehlermeldung auf „Show Bug Report“ und findet Informationen zum System, den Prozessen und vor allem: Welcher Fehler eingetreten ist (und eventuell warum) – Rot eingerahmt. In diesem Fall habe ich zum Beispiel statt „function“ „funktion“ für einen Funktionsrumpf geschrieben (Zeile 20). [img='http://rail-sim.de/wiki/images/thumb/6/66/PP_LUATUT02_02_Bug_Report.png/800px-PP_LUATUT02_02_Bug_Report.png',left,517][/img] Man sieht: Diese Fehlerquelle ist leicht zu finden und schnell zu lösen. Die Nichtbeachtung der Groß- und Kleinschreibung führt schnell zu fehlerhaften Funktionsnamen und Variablen. Hier helfen nur drei Methoden: [list][*]Folge dem Quellcode und schaue nach, ob irgendetwas falsch geschrieben wurde. [*]Halte dazu beim Programmieren für Funktionen, Variablen und Tabellen eine einheitliche Namensgebung ein (siehe unten). [*]Untersuche Argumente und Variablen mit einer selbstgebauten DebugMessage()-Funktion (siehe Teil 1). [/list] Die Prüfung eines fehlerhaften Arguments kann schnell erledigt sein. Dazu gibt es folgende Möglichkeiten: [list][*]Gib mit der Funktion DebugMessage() eine Informationsnachricht mit den Parametern aus. [*]Prüfe die Werte auf Gültigkeit, indem der Wertebereich überprüft wird. Überprüfe Variablen auch auf den Wert nil. [/list]Ein illegaler Aufruf einer Funktion kann einen fatalen Fehler auslösen: Solche Fehler lösen einen zwanghaften Fehlerdialog aus. Bekommt eine Funktion Argumente, die außerhalb des zu erwartenden Wertebereiches sind, kann sie entweder Fehlermeldungen ausgebenoder löst ein unvorhergesehenes Verhalten aus. Möchte man prüfen, ob eine Variable ungültig ist, muss man Sie nur gegen den Wertebereich oder nil prüfen. Da es allerdings viele Variablen im Quellcode gibt, ist dieses Verfahren sehr aufwendig. Logikfehler lösen ein unerwartetes Programmverhalten aus. Hier gibt es nur eine Lösung: [list][*]Verhalten beobachten, schildern [*]Auf dem Papier das Ganze an einem Worst-Case-Szenario durcharbeiten. Tipp: Mit Microsoft® Visio® kann man die Logik an Flussdiagrammen visualisieren. [*]Logik verändern und beobachten was passiert [/list]Fehler sind vielschichtig, doch für alles gibt es eine Lösung. Es hilft auch, wenn man seine persönlichen Lieblingsfehler kennt, denn dann weiß man, wo man anfangen soll! Eine weitere Lösung kann das Kommentieren sein: Diese Kommunikationsaufgabe hilft Fehler schneller zu verstehen! === Das Lua-Handbuch === Zur Skriptsprache Lua gibt es ein offizielles Handbuch. Das Handbuch ist im Dokumentationsbereich auf der offiziellen Seite von Lua ([url]http://www.lua.org[/url]) zu finden. Der Direktlink zum Lua 5.1 Reference Manual lautet [url]http://www.lua.org/manual/5.1/[/url]. Es ist zu beachten, dass das Handbuch nur auf Englisch verfügbar ist nur alle Funktionen allgemein schreibt. Teilweise ist Vorwissen aus anderen Programmiersprachen notwendig, um die Hintergründe zu verstehen. Für uns sind die Punkte „2 - The Language“ und „5 - Standard Libraries“ wichtig. Die restlichen Punkte sind für Anwendungsprogrammierer oder Sprachentwickler wichtig. Die Sprachdokumentation ist allgemein als Text mit Beispielen beschrieben. Die Funktionen werden mit der Definition vorgestellt, was diese Bewirkt und deren Voraussetzungen, die Bedeutung der Parameter und der Wertebereich der Argumente sowie die zu erwartenden Rückgabewerte. Die Inhaltsübersicht auf der Hauptseite listet die einzelnen Themen auf. Scrollt man auf der Hauptseite herunter, sind alle eigenen Lua-Funktionen aufgelistet. Auf der rechten Spalte findet man unter dem Namen „C API“ und „auxilary library“ eine Dokumentation für Anwendungsprogrammierer. === Vereinfachen gängiger Arbeiten === Dieser Abschnitt hätte auch den Titel „Tipps zum Überleben“ bekommen können. Und darum geht es jetzt: Tipps, damit das Chaos vermieden wird. Die Funktion von Kommentaren wurde im ersten Teil geklärt. Dennoch gibt es viele Fragen, wie man diese sinnvoll anwendet. Es folgen ein paar Tipps und Vorlagen: ==== Informationen zur Datei ==== Wie beschrieben sollten hier Informationen stehen, was die Datei allgemein macht, wer sie geschrieben hat, wann sie geschrieben und was an ihr verändert wurde. Zusatzinformationen wie die verwendete Lizenz, die Dokumentationssprache und der Name der Gruppe tragen ebenfalls zur Übersicht bei und sind teilweise Pflicht. Das folgende Bild zeigt eine exemplarische Dokumentation (ohne Lizenz): [img]http://rail-sim.de/wiki/images/2/28/PP_LUATUT02_03_HeaderDoc.png[/img] ==== Beschreibung globaler Definitionen ==== Im Grunde müssen globale Definitionen nur beschreiben, was diese bedeuten. Beispiel: [img='http://rail-sim.de/wiki/images/2/20/PP_LUATUT02_04_GlobalVar.png',none,716][/img] ==== Funktionen ==== Funktionen benötigen ebenfalls eine Dokumentation (ganz wichtig!): [list][*]Was macht die Funktion? [*]Welche Parameter gibt es? Welche Argumente sind gültig? Abhängigkeiten? [*]Welche Rückgabewerte sind zu erwarten? Fehlerbehandlung? [/list]Hierzu ein Beispiel: [img]http://rail-sim.de/wiki/images/b/bf/PP_LUATUT02_05_Funktionen.png[/img] Aufgabenfelder / Programmblöcke / Rümpfe Hier sollte man nicht beschreiben, was die Sprachkonstrukte machen, sondern warum bestimmte Prozesse notwendig sind und wie diese zusammenhängen. Diese Dokumentation sollte den Logikprozess abbilden – und nicht die Sprache. Ein Beispiel siehe oben bei den Funktionen (Warum interessiert mich die Nachricht überhaupt nicht?). Wie benennt man Variablen und Funktionen? Nach dem vereinbarten Muster der Gruppe. Doch es gibt Grundregeln: [b]P[/b]ascal[b]C[/b]ase oder [b]c[/b]amel[b]C[/b]ase. Globale Definitionen werden oftmals [tt]KOMPLETT_GROSS[/tt] und mit Unterstrich in Worte getrennt: [tt]pxpPZB_MGN_2000[/tt] ist so ein Beispiel. Der Name der Gruppe ([tt]pxp[/tt]) wurde hier vor der Definition klein angefügt. Ansonsten schreibe ich Variablen im PascalCase: [tt]TrainSpeed[/tt]. Globalen Variablen bekommen bei mir ein sogenanntes Prefix: [tt]g_[/tt]. Damit ist eindeutig, dass diese Variable global ist. Beispiel: [tt]g_TrainData[/tt]. Wenn möglich, schreibe ich Funktionen im camelCase. Damit die Funktionsgruppe erkennbar ist, nutze ich ein Verb: [tt]create[/tt], [tt]release[/tt], [tt]get[/tt], [tt]set[/tt], [tt]is[/tt]oder [tt]has[/tt]. Beispiel: [tt]function isPZBContactActive()[/tt] Das ganze Prinzip wird in den folgenden Beispielprojekten (z.B. Signale) sicherlich klar. === Projektorganisation und Teamarbeit === Projekte sollten einen eigenen Ordner bekommen, wenn dies möglich ist. Alle Dateien eines Projekts sollten in einem eigenen Ordner nach Funktion sortiert werden. Z.B. [list][*]Objekte in „Meshes“ [*]Texturen in „Textures“ [*]Vorlagen in „Templates“ [*]Skripte in „Scripts“ [*]Grundmodelle in „Template Meshes“ [/list]Wichtig ist, dass man alle Daten einer bestimmten Version zuordnen kann, damit der Austausch der Dateien einfach vonstattengeht. Die Versionsverwaltung kann man für relativ kleine Projekte manuell selbst auf einem Downloadserver durchführen. Ein paar FTP-Accounts und schon kann das Austauschen beginnen. Eine Teamplattform ist natürlich von Vorteil. Für größere Projekte, an denen viele Mitarbeiter (ab 5) arbeiten, empfiehlt es sich eine Software zu nehmen und einen Online-Server, auf denen man mit wenigen Klicks alles austauschen kann. Eine solche Software ist zum Beispiel TortoiseSVN mit einem passenden Onlinespeicher. Dieses Verfahren wird in einem anderen Tutorial beschrieben, da es den Rahmen dieses Tutorials sprengen würde. [b]Wichtig ist: Sei auf den neuesten Stand und gib Bescheid, wenn Daten aktualisiert worden sind.[/b] Und dokumentiere was wo wann geändert wurde. === Die Mathematikbibliothek === Dieser Abschnitt stellt die wichtigsten Funktionen und die Mathematikbibliothek vor. ==== Allgemeine Funktionen ==== [table] [tr] [td]assert(value[, message])[/td] [td]Löst einen fatalen Fehler aus, wenn value false oder nil ist. Gibt die Nachricht message aus.[/td] [/tr] [tr] [td]dofile(filepath)[/td] [td]Führt eine Datei aus. Der Arbeitsordner (Current Working Directory) bezieht sich auf den Ordner, in dem sich die RailWorks.exe befindet.[/td] [/tr] [tr] [td]print(text)[/td] [td]Schreibt text in die Konsole bzw. schreibt ihn in die Log-Datei.[/td] [/tr] [tr] [td]tonumber(text)[/td] [td]Wandelt text in eine Zahl um. Gibt nil zurück, wenn es nicht funktionierte.[/td] [/tr] [tr] [td]tostring(value)[/td] [td]Wandelt einen Wert in einen Text um.[/td] [/tr] [tr] [td]type(value)[/td] [td]Gibt den Datentyp von value in Textform zurück: „nil“, „number“, „string“, „table“, „function“, „boolean“, „thread“ oder „userdata“.[/td] [/tr] [tr] [td]key, value = inpairs(table)[/td] [td]Für die generische For-Schleife. Iteriert eine Tabelle. key besitzt den Namen des Schlüssels, value den Wert.[/td] [/tr] [/table] [img]http://rail-sim.de/wiki/images/4/4c/PP_LUATUT02_06_Math.png[/img] ==== Die Bibliothek math ==== Der Zugriff auf die math-Bibliothek erfolgt über die Tabelle math: math.(Funktion). Die wichtigsten Funktionen sind fett markiert. [table] [tr] [td][b]abs(x)[/b][/td] [td][b]Gibt den absoluten Wert von x zurück.[/b][/td] [/tr] [tr] [td]acos(x)[/td] [td]Gibt den Arkuscosinus von x in Radiant zurück.[/td] [/tr] [tr] [td]asin(x)[/td] [td]Gibt den Arkussinus von x in Radiant zurück.[/td] [/tr] [tr] [td]atan(x)[/td] [td]Gibt den Arkustangens von x in Radiant zurück.[/td] [/tr] [tr] [td][b]ceil(x)[/b][/td] [td][b]Rundet die Zahl x auf (Ganzzahl).[/b][/td] [/tr] [tr] [td]cos(x)[/td] [td]Berechnet den Cosinus von x in Radiant.[/td] [/tr] [tr] [td]cosh(x)[/td] [td]Berechnet den Cosinus Hyperbolicus von x in Radiant.[/td] [/tr] [tr] [td]deg(radian)[/td] [td]Berechnet den Winkel in Grad von radian.[/td] [/tr] [tr] [td]exp(x)[/td] [td]Berechnet e^x.[/td] [/tr] [tr] [td][b]floor(x)[/b][/td] [td][b]Rundet x ab[/b].[/td] [/tr] [tr] [td]fmod(x, y)[/td] [td]Gibt den Rest der Division x/y zurück. Er ist zwischen [0 und