awesome-attractor/stfu/simple documentation.html

<h1>STF - Simple Tree Format</h1>
<p>
STF is a new file format to store a tree of values, just like XML and JSON can do. It has support for only 2 types: values and nodes. A node can have values and other nodes, allowing the creation of a tree format. A STF file itself is a node (the virtual root node). Nodes are a collection of other values and (child)nodes.
</p>

<h2>Usage</h2>
<p>
Nodes and values are named, the smallest name being "". We refer to the nodes with "" as name as unnamed nodes/values, but the same rules apply for the syntax; examples will follow, don't worry. Each name is followed by a ':' which signifies the end of the name (the name-terminator). The ':' is followed by either a '{' or a '"', which signifies the type of the name (the type-specifier): '{' are lists, '"' are values. The parser will extract and ignore anything in between the name-terminator and the type-specifier.
</p>

<h2>Examples</h2>
<h3>Starting easy</h3>
<p>
Here's an example of a very small STF file. It shows values and nodes and their syntax, without fancy stuff.
<pre>
name: "First value in the file"
childnode: {
    value: "This is another value, inside a child node with the name "childnode"
}
</pre>
</p>

<h3>Comments</h3>
<p>
Don't want to have a very long descriptive name, but do want a bit of extra info? Comments (or anything really) can be place in between the name-terminator and the type-specifier.
<pre>
name: This text will be ignore by the parser "First value in the file."
childnode: This text will too, be ignored {
    value: You probably already guessed it

    But this text will to be ignored. Anything here is allowed, except for a type-specifier of course! ;-)

    "This is another value, inside a child node with the name ""childnode""."
}

<h3>Getting more interesting</h3>
<p>
This example shows what characters are allowed inside names and values.
<pre>
firstnode:  {
    subnode: {
        blah: "xyz"
        blah: "names of values/childs don't have to be unique!"
    }
}
secondnode: {
   name with space: "names can contain spaces"
name
with
newlines: "names can contain newlines"
   blah: "values can contain
newlines too!"
}
</pre>
</p>
<p>
NOTE: Take a look at the other .stf files included with this project for more examples.
</p>

<h1>STFU - Simple Tree Format Utility</h1>
<p>
STFU is the first C++ implementation for STF.
</p>
<p>
This example will show you some of the basic features of STFU:
<pre>
#include <iostream>
#include "stf.hpp"
using namespace std;
using stfu::node;

int main(){
   node n,f;
   if (n.read("blah.stf")){  //could also do:  'if ("blah.stf" >> n){'
      cout << n.value("test");  // Read a value
	  
	  cout << n.child("subnode").value("hi",0); //Read the first value
	  cout << n.child("subnode").value("hi",1); //Read the second value
	  
	  n.child("subnode").value("test") = "blah"; //Add a value
	  
	  if (f.read("another_file.stf")){
	     n.child("secondnode") = f;   //add a child
	  }
	  
	  n.write("blah.stf"); //Write changes back to the file
	  // "blah.stf" << n; would also be valid.
	  
	  cout << n; //output the file to the console instead of a file.
   
   } else {
      cout << "ERROR!" << endl;
   }
}
//NOTE: For more detailed examples, please take a look at the 'main.cpp' file of this project.
</pre>
</p>
<p>
As you see, the .child() and .value() functions can be used to read, create and change values/childs. More advanced functions are available, 'main.cpp' contains examples to explain all of them.
</p>