User Tools

Site Tools


de:doc:tools_oobdtemple
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


de:doc:tools_oobdtemple [2014/07/04 09:41] (current) – created wsauer
Line 1: Line 1:
 +====== OOBDTemple - Das OOBD Quellkode-Vorlagenwerkzeug ======
 +
 +===== Warum ein weiteres Vorlagenwerkzeug? =====
 +Es gibt sicherlich ein Duzend unterschiedliche Vorlagenwerkzeuge, alle nehmen ein Programmiergerüst und ein paar andere Daten und erstellen daraus einen Programmkode.
 +
 +Wir aber halten Ausschau nach etwas, mit dem wir schreiben und Quellcode testen können wie üblich, dann aber auch zusätzlich Teile innerhalb des Quellkodes zu finden oder zu identifizieren. Diese gleichartigen Teile möchten wir als Vorlage extrahieren, um sie in anderen Quelldateien zu importieren und zu aktualisieren.
 +
 +
 +===== Das Prinzip =====
 +Stell Dir vor Du hast einen Quellcode:
 +
 +<code>
 +
 +overall initialization
 +
 +some specific variable initialization
 +
 +a generic doTo loop:
 +
 +for (i=0 ...
 +
 +            some specific tasks in here
 +}
 +
 +specific shutdown
 +
 +generic shutdown
 +
 +
 +</code>
 +
 +Nun stell Dir vor einige Marker in den Quellkode einzufügen, welche mitteilen, welche Teile des Kodes generisch sein sollen. Der andere Teil des Quellkodes bleibt unverändert.
 +
 +<code>
 +
 +//>>>> oobdtemple >>>>
 +
 +overall initialization
 +
 +//<<<< oobdtemple <<<<
 +
 +some specific variable initialization
 +
 +//>>>> oobdtemple >>>>
 +
 +a generic doTo loop:
 +
 +for (i=0 ...
 +
 +            //<<<< oobdtemple <<<<
 +
 +            some specific tasks in here
 +
 +            //>>>> oobdtemple >>>>
 +
 +}
 +
 +//<<<< oobdtemple <<<<
 +
 +specific shutdown
 +
 +//>>>> oobdtemple >>>>
 +
 +generic shutdown
 +
 +//<<<< oobdtemple <<<<
 +</code>
 +
 +Wie Du sehen kannst, werden die generischen Teile immer von einem >>>> oobdtemple >>>> Kode <<<< oobdtemple <<<< Konstrukt eingeschlossen.
 +
 +Aber um verschachtelten Vorlagenkode zu erlauben, benötigen die Marker einen Identifizierer der angibt zu welcher Vorlage er gehört.
 +
 +Nun gehören alle Marker zu der "base" Vorlage:
 +
 +<code>
 +
 +//>>>> oobdtemple base >>>>
 +
 +overall initialization
 +
 +//<<<< oobdtemple base <<<<
 +
 +some specific variable initialization
 +
 +//>>>> oobdtemple base >>>>
 +
 +a generic doTo loop:
 +
 +for (i=0 ...
 +
 +            //<<<< oobdtemple base <<<<
 +
 +            some specific tasks in here
 +
 +            //>>>> oobdtemple base >>>>
 +
 +}
 +
 +//<<<< oobdtemple base <<<<
 +
 +specific shutdown
 +
 +//>>>> oobdtemple base >>>>
 +
 +generic shutdown
 +
 +//<<<< oobdtemple base <<<<
 +</code>
 +
 +
 +Das würde schon so weit funktionieren, aber es wird wahrscheinlich kompliziert zu erkennen, welcher Eröffnungsmarker zu welchem Abschlußmarker gehört. Aus diesem Grund können die Marker benannt werden. Diese Namen sind optional, aber wenn sie genutzt werden, müssen sie jeweils angeglichen sein.
 +
 +<code>
 +
 +//>>>> oobdtemple base init >>>>
 +
 +overall initialization
 +
 +//<<<< oobdtemple base init <<<<
 +
 +some specific variable initialization
 +
 +//>>>> oobdtemple base loop>>>>
 +
 +a generic doTo loop:
 +
 +for (i=0 ...
 +
 +            //<<<< oobdtemple base <<<<
 +
 +            some specific tasks in here
 +
 +            //>>>> oobdtemple base >>>>
 +
 +}
 +
 +//<<<< oobdtemple base loop <<<<
 +
 +specific shutdown
 +
 +//>>>> oobdtemple base shutdown >>>>
 +
 +generic shutdown
 +
 +//<<<< oobdtemple base shutdown <<<<
 +</code>
 +
 +
 +
 +===== Die oobdtemple Kommandos =====
 +Oberhalb dieses Textes haben wir gesehen, wie Quellkode versehen mit Vorlagen-Markern aussieht. Nun lass uns überprüfen wie oobdtemple damit arbeitet:
 +
 +Zunächst nehmen wir etwas einfaches
 +
 +==== oobdtemple --struct : Show template structure ====
 +
 + oobdtemple template_name --struct file
 +
 +Druckt die aktuelle Vorlagenstruktur auf die Standartausgabe in die Datei "file". Dies ist hilfreich um Fehler zu finden, wenn oobdtemple meldet, dass es strukturelle Vorlagenunterschiede gibt. 
 +
 +
 +==== oobdtemple --extract : Extrahiere Vorlage ====
 +
 +       oobdtemple template_name --extract file
 +
 +Druckt den aktuellen Vorlageninhalt in <file> auf die Standartausgabe. Dies ist hilfreich um eine "frische" Vorlage aus einem gegebenen Quellkode zu erzeugen.
 +
 +----
 +
 +Nun beginnen wir mit dem Kopieren von Vorlagen aus und in Dateien:
 +
 +
 +
 +==== oobdtemple --update : Aktualisieren der Quelldatei ====
 +
 + oobdtemple template_name --update sourcefile templatefile
 +
 +Dies aktualisiert den gegenwärtigen Inhalt von <templatefile> in <sourcefile>. Es stoppt , falls die Vorlagenstruktur zwischen <sourcefile> und <templatefile> unterschiedlich ist
 +
 +
 +==== oobdtemple --writetemplate : Aktualisieren der Vorlagendatei ====
 +
 + oobdtemple template_name --writetemplate sourcefile templatefile
 +
 +Dies sichert den aktuellen Vorlageninhalt von <sourcefile> nach <templatefile>. Es stoppt, falls die Vorlagenstruktur zwischen <sourcefile> und <templatefile> unterschiedlich ist
 +
 +----
 +
 +Dies waren die Kommandos um Dateien zu bewerten oder zu modifizieren. Die nächsten zwei Kommandos sollten in den Make Prozess integriert werden, um sicherzustellen dass die Vorlage zu dem Quellkode passt, mit dem gearbeitet werden soll.
 +
 +==== oobdtemple --check : Überprüfe Quellkode und die Beständigkeit der Vorlagendatei  ====
 +
 + oobdtemple template_name --check sourcefile templatefile
 +
 +Überprüft, ob die Vorlage von <templatefile> 1:1 in dem <sourcefile> eingebunden ist. Diese Routine kommt nach dem Aufruf mit dem Rückgabecode 1 zurück falls nicht, anderenfalls mit 0
 +
 +
 +Aber weil eine Inkonsistenz zwischen dem Quellkode und der Vorlage in der Entwicklungsphase leicht vorkommen kann, gibt es ein spezielles Kommando, welches nur eine Warnung ausgibt und nicht den kompletten Makeprozess abbricht:
 +
 +==== oobdtemple --develop : Warnt bei Inkonsistenz zwischen dem Quellkode und der Vorlage ====
 +
 + oobdtemple template_name --develop sourcefile templatefile
 +
 +Ist das gleiche wie --check, aber es schreibt nur Warnungen auf die Standartfehlerausgabe und kommt mit dem Rückgabewert 0 zurück um den Makeprozess nicht abzubrechen
 +
 +
 +===== The oobdtemple Struktur Tests =====
 +
 +Weil es offensichtlich viel Schaden im Quellkode anrichten kann, wenn man versucht eine Vorlage in diesen zu integrieren der nicht passt, führt oobdtemple ein paar Tests durch, bevor es die Operation durchführt und die beiden Teile verbindet. Wenn einer der Tests negativ ist, wird die Operation unterbrochen und die Dateien bleiben unverändert:
 +
 +  * Auf Dateienebene überprüft oobdtemple
 +    * ob alle Eröffnungsmarker mit ihren Abschlußmarkern korrespondieren
 +    * ob der optional vergebene Name des Eröffnungsmarkers dem des Abschlußmarkers gleicht
 +  * zwischen dem Quellkode und der Vorlage überprüft oobdtemple
 +    * ob die Anzahl der Marker gleich sind
 +    * ob die optional verwendeten Namen zwischen dem Quellkode und der Vorlage gleich sind
  
de/doc/tools_oobdtemple.txt · Last modified: 2014/07/04 09:41 by wsauer