Basic Format

The Whee configuration files are read using the NTreeReader class, which can be found in the git repository. This page is a basic introduction to the file format so you don't have to decipher the code to figure out how it works.

The NTree format is similar to the YAML format or Python syntax in that it uses whitespace to delimit related blocks. The name is derived from the fact that the format is hierarchical, a Node Tree if you will, and also the fact that it's intended as an easy way to read entries from a file (NTree being a homophone of entry). That may not be terribly interesting, but hopefully knowing the reasoning behind the name will help give you an idea what the format is all about. Also of historical note is that this class was originally created for the game Coldest to make reading the configuration files more standardized and robust. At this point I would deem it a complete success, but then I'm biased since that's also my project. ;-)

The format itself is quite simple. Each line consists of a key and some number of values. The values are delimited by whitespace, but can also be read as a single value if desired (for example, string values that need to allow spaces). For example, consider the following line:

Key Value1 Value2 Value3

Depending on what the code requires, that is either a key Key with values Value1 (index 0), Value2 (index 1), and Value3 (index 2), or a key Key with value "Value1 Value2 Value3". It is not necessary (or possible) to specify which format will be used, the code should read it in the appropriate fashion. Note that there is currently no way to include whitespace in a key as everything after the whitespace would be considered a value.

As mentioned earlier, this format is also hierarchical. All key-value pairs that occur at an indentation level of 0 are considered part of the root node. Children of the root node are indicated by indenting any number of spaces or tabs. All key-value pairs that occur consecutively at the same or greater indentation level are part of a node, or a child of that node (in the case of greater indentation). Consider the following example:

RootKey RootValue
AnotherRootKey More Root Values
ChildNode
   ChildKey ChildValue
   NestedChildNode
      NestedChildNodeKey Nested Child Node Values
   AnotherChildKey More Child Values
ChildNode2
   Child2Key Child2Value

This file describes a root node with keys RootKey and AnotherRootKey, and two child nodes named ChildNode and ChildNode2. One thing not previously mentioned is that nodes can be looked up by name, and the name of a node is simply the line preceding the first indented line of the node. That means that theoretically the name line could be a valid key-value pair in the parent node, although I wouldn't recommend that to avoid confusion. This means that NestedChildNode is a child of ChildNode with a key NestedChildNodeKey.

Also note that even though ChildKey and Child2Key are at the same indentation level, they are not part of the same node because the line ChildNode2 is between them and indented less. However, ChildKey and AnotherChildKey are part of the same node because even though NestedChildNodeKey is between them and indented differently, it is indented further which does not signal the end of a node.

That should be enough to make sense of the configuration files for Whee. Now you will probably want to take a look at the widget reference.