Differences

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

--- doc:oobdtemple [2012/06/03 08:03] – created admin
+++ doc:oobdtemple [2014/03/02 08:05] (current) – removed admin
@@ Line 1: / Line 1: @@
-====== OOBDTemple - The OOBD Source Code Template Tool ======
-===== Why another template tool? =====
-There are virtual dozens of template tools available, but they all take a template and some data and create the output out of it.
-We were looking for something instead with which we can write and test source code as usual, then identify the pieces of the code inside one source file, which could be used also in similar cases. These common parts we want to extract as a template and import and update them into other source files.
-===== The Princible =====
-Image, you have a source code:
-<code>
-overall initialization
-some specific variable initialization
-a generic doTo loop:
-for (i=0 ...
-            some specific tasks in here
-}
-specific shutdown
-generic shutdown
-</code>
-Now image you put some markers into that source, which tells, which parts of the code are generic. The specific parts of the code stays unmarked.
-<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>
-As you can see, the generic parts are enclosed into an >>>> oobdtemple >>>> code <<<< oobdtemple <<<< pair.
-But to allow nested template code, the markers needs to have a identifier, to which template they belong to.
-Now the markers belongs all to the template called base:
-<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>
-That would already work so far, but it might become complicated, which opening marker now exactly belongs to which closing marker. So for that reason the markers can be named. These names are optional, but if used, they must align to each other.
-<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>
-===== The oobdtemple Commands =====
-Above we've seen how a source code amended with markers looks like. Now lets see how oobdtemple deals with that:
-First we take something simple
-==== oobdtemple --struct : Show template structure ====
-	oobdtemple template_name --struct file
-Prints the actual template struct in <file> to stdout. Helpful for finding errors when oobdtemple complains about template structure differences
-==== oobdtemple --extract : Extract template ====
-       oobdtemple template_name --extract file
-Prints the actual template content in <file> to stdout. Helpful to generate a fresh template file out of an given soure file.
-----
-Now we start to copying templates in and out of files:
-==== oobdtemple --update : Update source file ====
-	oobdtemple template_name --update sourcefile templatefile
-Updates the actual template content of <templatefile> into <sourcefile>. Stops, if template structure between <sourcefile> and <templatefile> is different
-==== oobdtemple --writetemplate : Update template file ====
-	oobdtemple template_name --writetemplate sourcefile templatefile
-Saves actual template content of <sourcefile> to <templatefile>. Stops, if template structure between <sourcefile> and <templatefile> is different
-----
-This were the commands for evaluate or modifying files. The next two commands should be placed into the make process to make sure that the template fits to the content of the source file to work with.
-==== oobdtemple --check : Check source code and template file consistency ====
-	oobdtemple template_name --check sourcefile templatefile
-Checks, if the template of <templatefile> is 1:1 included in <sourcefile>. Exits with exitcode 1 if not, otherways with 0
-But as an inconsistency between source code and template can easily happen during the development phase, there's a special command to just give a warning but to not stop the make process:
-==== oobdtemple --develop : Warns for source code and template file consistency ====
-	oobdtemple template_name --develop sourcefile templatefile
-Same as --check, but just writes warnings to stderr and exit with 0 to not stop a make process
-===== The oobdtemple Structure checks =====
-As it obviously can create a lot of damage in the source codes, when you try to merge a template structure into a source, which has a complete different template structure, oobdtemple does a few checks first before merging files. If one of these tests fails, the operation stops and the files remains untouched:
-  * On file level oobdtemple checks
-    * if all opening tags have their closing tags
-    * if the optional name given to the opening tag equals to the closing tag
-  * between source file and template file oobdtemple checks
-    * if the number of tags are equal
-    * if the optional names of the tags are equal between source and template