Changes between Version 1 and Version 2 of code/doc/ConfigValueContainer

Timestamp:

Feb 27, 2008, 7:47:28 PM (16 years ago)

Author:

landauf

Comment:

—

code/doc/ConfigValueContainer

@@ -86 +86 @@
 == The config-file ==
 
+The config-file (usually ''orxonox.ini'') has a clear structure, split into sections, where each section belongs to one class. A new section is introduced by a line containing the name of the class in square brackets:
+{{{
+[ClassName]
+}}}
+The following lines contain all config-values of the class in the following form:
+{{{
+varname=value
+}}}
 
+The config file adds missing variables or sections and repairs unreadable values by resetting them to the default value, but it doesn't change or remove needless entries. This allows you to add comments or funny ASCII-art. Whitespaces are ignored, so you can format your config-file in every way you like.
+
+You can begin a line with a comment-symbol to ignore a line. If this removes an entry, a new one gets added to the end of the section, but you could add two versions of a line and comment one (for example when you want to test different settings without losing the previous value). There are four different comment-symbols:
+ * '''#'''comment: script-language style
+ * '''%'''comment: matlab style
+ * ''';'''comment: unreal tournament config-file style
+ * '''//'''comment: code style
+
+Different variable-types have different formattings in the config file. There are three different cases:
+ * '''Primitives''': varname=value
+ * '''Strings''': varname="string"
+ * '''Complex types''' (like vectors): varname=(value1, ..., valueN)
+
+ * Additionally booleans can be denoted by using ''true'' or ''false''.
+
+There are four cases causing the parser to change the config-file:
+ 1. Case: A config-value is set, but can't be parsed (wrong formatting) or can't be converted to the wanted type:
+   * Change: The value is set back to the default
+ 1. Case: A config-value is missing but the section of the corresponding class exists:
+   * Change: The value is added at the end of the section
+ 1. Case: The whole section is missing or can't be found because the [!ClassName]-line is missing:
+   * Change: The whole section is added at the end of the file
+ 1. Case: The config-file is missing:
+   * Change: The config-file is created and all sections and values are written to the file.
+
+Example of a valid config-file:
+{{{
+[MyClass] <-- This name is stupid
+firstValue_  = 1.000000
+secondValue_ = 1.0
+thirdValue_  = 1
+
+[OtherClass] <-- This name is even worse
+//teststring = "test"
+teststring = "teeeeeeeeeeeest"
+
+[StupidNamedClass] <-- This name rocks
+position1_=(1.0, 2.0, 3.0)
+position2_ = ( 1.000000 , 2.000000 , 3.000000 )
+    position3_ =      (1,2,3)
+
+gagagugubleeeeeeeeeep!
+
+[LastClass] <-- Where did you know...? Now this is scary...
+moo_ = "Oh yes they do!"
+bTheyMoo_ = true
+}}}