From 6ccaeb37389b60a4f735862a8e4d4e2c6986e004 Mon Sep 17 00:00:00 2001
From: zawz <zawz@ZSV>
Date: Thu, 20 Feb 2020 10:58:12 +0100
Subject: [PATCH] Extend doc

---
 README.md  |  11 +++-
 filedat.md | 158 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 166 insertions(+), 3 deletions(-)
 create mode 100644 filedat.md

diff --git a/README.md b/README.md
index 57e7e9c..6a9edc1 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,9 @@
 
 zawz's standard C++ library. Tools for easier coding
 
-## Documentation
-
-Use ``doxygen`` to generate HTML documentation files
+Online Documentation: (http://zawz.net/doc/ztd)  
+Github: (http://github.com/zawwz/ztd)
+ZFD format details: [zfd.md](filedat.md)
 
 ## Building
 
@@ -14,3 +14,8 @@ Use ``doxygen`` to generate HTML documentation files
 ## Installing
 
 ``sudo make install``
+
+## Generating documentation
+
+Use ``doxygen`` to generate HTML documentation files
+
diff --git a/filedat.md b/filedat.md
new file mode 100644
index 0000000..b40a25f
--- /dev/null
+++ b/filedat.md
@@ -0,0 +1,158 @@
+# ZFD format details
+
+The format is composed of infinitely concatenable "chunks". There a three types of chunks:  
+-Map chunk     : between braces    {}  
+-List chunk    : between brackets  []  
+-String value
+
+Formatting is ignored, all spaces will be ignored unless they are part of a value.  
+Comments can be written with //, ends at end of line
+
+ZFD treats everything as a string, there is no number or boolean types
+
+### Map Chunk
+
+A map chunk consists of pairs of keys and values. Format is as follows:
+```
+{
+  //no concatenator: value ends at end of line. /!\ Comments on these lines will be part of the value
+  key1=value
+  //concatenators: value ends at end of concatenation
+  key2 = " value "
+  key3 = ' value '
+  key4=[ //list ]
+  key5={ //chunk }
+}
+```
+
+### List Chunk  
+
+A list chunk consists of a linear list of values separated by commas. Format is as follows:
+```
+[
+  //comments cannot be written between a value and the separating comma
+  value,
+  " value ",
+  ' value ',
+  { //chunk },
+  [ //list ]
+]
+```
+
+# Usage
+
+## Definition
+
+```cpp
+ztd::filedat file("/path/to/file");
+```
+
+## Importing and reading
+
+### Importing
+
+```cpp
+ztd::filedat file;
+file.import_file("path/to/file"); //import from file
+file.import_stdin();              //import from stdin
+file.import_string("{a=b}");      //read from argument string
+```
+Throws exceptions if errors are encountered
+
+### Reading
+
+#### Accessing chunks
+
+```cpp
+ztd::chunkdat& chk1 = file["string"];  //key "string"
+ztd::chunkdat& chk2 = file[0];         //element #0
+ztd::chunkdat& chk3 = file[0]["key"];  //key "key" in element 0
+```
+
+String keys for map chunks, int keys for list chunks  
+
+#### Getting a string value
+
+```cpp
+ztd::chunkdat& chk;
+std::string str=chk;
+std::string str=chk.strval();
+```
+> String type casting is automatic in cases where it applies, but you can use ``chk.strval()`` where necessary
+
+## Write and Export to file
+
+### Writing
+
+```cpp
+ztd::chunkdat chk, chk2;
+
+chk  = "{ a = b }";                   // Assigning as raw string
+chk2 = "[]";
+
+chk  += std::make_pair("foo", "bar"); // Adding values to map. Can give a vector for multiple elements
+chk2 += "val";                        // Adding values to list. Can give a vector for multiple elements
+
+chk["foo"] = "foo";                   // Changing map values
+chk2[0]    = "foo";                   // Changing list values
+
+chk  -= "foo";                        // Remove element from map
+chk2 -= 0;                            // Remove element from list
+
+chk  *= "{ key = val }";              // Concatenate map chunks
+chk2 *= "[ v1 , v2 ]";                // Concatenate string chunks
+                                      // Chunks have to be of the same type for concatenation
+```
+
+> General operator rules apply here. You can use these operators without direct assign (+ instead of +=) and daisy-chain them
+
+> In case a chunk doesn't have a type, it will be automatically set to the type the operation implies
+
+It is advised to first write the data onto a chunk and then assigning the chunk to the file
+But in case you need absolute performance, you can access the filedat chunk with `filedat.data()`
+
+### Exporting
+
+#### File export
+
+```cpp
+ztd::chunkdat& chk;
+ztd::filedat file("/path/to/file");
+file = chk;
+file.export_file("/path/to/file");
+```
+
+#### Other
+
+```cpp
+ztd::chunkdat& chk;
+ztd::filedat& file;
+std::cout << chk << std::endl;
+std::cout << file << std::endl;
+```
+
+## Exception handling
+
+All filedat and chunkdat functions throw exceptions when errors are encountered
+
+### Definition
+
+```cpp
+ztd::format_error(std::string what, std::string origin, std::string data, int where);
+```
+
+### Example use
+
+```cpp
+ztd::filedat file("/path/to/file");
+try
+{
+  file.importFile();
+}
+catch (ztd::format_error& fe)
+{
+  printFormatException(fe);
+}
+```
+If origin is known, printFormatException will print only the relevant line with location  
+If origin is unknown, printFormatException will print the whole data until the discriminating line