diff --git a/Doxyfile b/Doxyfile index cfc7e52..30b7dd4 100644 --- a/Doxyfile +++ b/Doxyfile @@ -813,7 +813,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = include +INPUT = include md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/README.md b/README.md index 57e7e9c..a836c26 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,8 @@ 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 ## Building @@ -14,3 +13,8 @@ Use ``doxygen`` to generate HTML documentation files ## Installing ``sudo make install`` + +## Generating documentation + +Use ``doxygen`` to generate HTML documentation files + diff --git a/include/filedat.hpp b/include/filedat.hpp index 9e890ad..6df103a 100644 --- a/include/filedat.hpp +++ b/include/filedat.hpp @@ -14,7 +14,8 @@ /*! @file filedat.hpp * @brief Storing and reading data * -* Easily organize data in a JSON-like file format +* Easily organize data in a JSON-like file format. +* See [ZFD format](@ref zfd) */ namespace ztd @@ -131,7 +132,7 @@ namespace ztd @param in C string data @param in_size Size of the string data @param offset Used for debugging - @param data Used for debugging + @param parent Used for debugging */ void set(const char* in, const int in_size, int offset=0, filedat* parent=nullptr); //! @brief Set data diff --git a/md/filedat.md b/md/filedat.md new file mode 100644 index 0000000..3c23ac5 --- /dev/null +++ b/md/filedat.md @@ -0,0 +1,158 @@ +# ZFD format {#zfd} + +ZFD 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 diff --git a/md/ztd.md b/md/ztd.md new file mode 100644 index 0000000..5610e93 --- /dev/null +++ b/md/ztd.md @@ -0,0 +1,8 @@ +# ztd {#mainpage} + +zawz's standard C++ library. Tools for easier coding + +Github: http://github.com/zawwz/ztd + +[ZFD format details](@ref zfd) +