From 6ccaeb37389b60a4f735862a8e4d4e2c6986e004 Mon Sep 17 00:00:00 2001 From: zawz Date: Thu, 20 Feb 2020 10:58:12 +0100 Subject: [PATCH 1/4] 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 From fa40e30a132a3c05287f3770b7511f1e980a862c Mon Sep 17 00:00:00 2001 From: zawz Date: Thu, 20 Feb 2020 10:59:13 +0100 Subject: [PATCH 2/4] Fix formatting --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6a9edc1..53d8d94 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ zawz's standard C++ library. Tools for easier coding -Online Documentation: (http://zawz.net/doc/ztd) -Github: (http://github.com/zawwz/ztd) -ZFD format details: [zfd.md](filedat.md) +Online Documentation: http://zawz.net/doc/ztd +Github: http://github.com/zawwz/ztd +ZFD format details: [filedat.md](filedat.md) ## Building From b8b1d32af61982a6f500a810f7a00772a7102433 Mon Sep 17 00:00:00 2001 From: Mateo FERON Date: Thu, 20 Feb 2020 11:37:11 +0100 Subject: [PATCH 3/4] Add separate md info --- Doxyfile | 2 +- include/filedat.hpp | 7 ++++--- filedat.md => md/filedat.md | 10 +++++----- md/ztd.md | 8 ++++++++ 4 files changed, 18 insertions(+), 9 deletions(-) rename filedat.md => md/filedat.md (94%) create mode 100644 md/ztd.md 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/include/filedat.hpp b/include/filedat.hpp index 1fef2b9..f03bc44 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 @@ -130,14 +131,14 @@ 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 /*! @param in String data @param offset Used for debugging - @param data Used for debuggingy + @param data Used for debugging */ inline void set(std::string const& in, int offset=0, filedat* data=nullptr) { this->set(in.c_str(), in.size(), offset, data); } diff --git a/filedat.md b/md/filedat.md similarity index 94% rename from filedat.md rename to md/filedat.md index b40a25f..3c23ac5 100644 --- a/filedat.md +++ b/md/filedat.md @@ -1,9 +1,9 @@ -# ZFD format details +# ZFD format {#zfd} -The format is composed of infinitely concatenable "chunks". There a three types of chunks: --Map chunk : between braces {} --List chunk : between brackets [] --String value +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 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) + From b32d1dbf42c7974788d5219fcda02ffba865d4ab Mon Sep 17 00:00:00 2001 From: zawz Date: Thu, 20 Feb 2020 11:39:53 +0100 Subject: [PATCH 4/4] Fix readme --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 53d8d94..a836c26 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,6 @@ zawz's standard C++ library. Tools for easier coding Online Documentation: http://zawz.net/doc/ztd Github: http://github.com/zawwz/ztd -ZFD format details: [filedat.md](filedat.md) ## Building