TOML Include

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/!TOML Reader and Writer.md

@@ -0,0 +1,12 @@
+# TOML Reader and Writer
+This is a class designed to read and write TOML configuration files.
+
+## Notes:
+- Some features of TOML (such as inline tables, lists, backslash escape) are not implemented yet.
+- Only double quotes is supported for string values.
+
+## Supported TOML value types
+- Strings.
+- Intagers.
+- Floatingpoints.
+- Booleans.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/.MDRoot

@@ -0,0 +1 @@
+This file indicates that this subdirectory should be considered as a root page in the markdown version of the documentation, see the docgen notes for more details.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml/Methods/dump.nvgt

@@ -0,0 +1,28 @@
+/**
+	Dump all loaded data into a string.
+	`string toml::dump(bool indent = true, bool empty_sections = true);`
+	## Arguments:
+		- `bool indent = true`: If this is set to true, all keys in every section will be proceeded with a tab character in the output. This indent number will increase if you have nested subsections, e.g. `game.server.name` will have 2 tabs on its key, `name`.
+		- `bool empty_sections = true`: Should the data include empty sections? Default is usually ok.
+	## Returns:
+		`string`: The entire TOML data as a string.
+*/
+
+// Example:
+#include "toml.nvgt"
+void main() {
+	toml t;
+	// Lets set all the possible types of supported values.
+	t.set("", "main_key", "Hello, world!");
+	t.set("", "int_key", 23);
+	t.set("", "float_key", 10.5);
+	t.set("", "boolean_key", false);
+	t.set("", "boolean_key2", true);
+	// Lets completely set another section.
+	t.set("owner", "name", "Jon");
+	t.set("owner", "age", 20);
+	// Subsections?
+	t.set("owner.contact", "telegram", "bla_bla_bla");
+	t.set("owner.contact", "facebook", "bla_bla_bla_book");
+	alert("Info", "\n\n" + t.dump());
+}

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml/Methods/get.md

@@ -0,0 +1,12 @@
+# get
+Fetch a value from the TOML data given a section and key.
+
+`var@ toml::get(string section, string key = "", var@ def = null);`
+
+## Arguments:
+- `string section`: The section to get the value from (if any). E.g. game.server
+- `string key = ""`: The key to get.
+- `var@ def = null`: The default value to facilitate handling by having an alternative value in case the original value ends up in failure.
+
+## Returns:
+`var@`: The value at the particular key if found, the default value otherwise.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml/Methods/get_keys.md

@@ -0,0 +1,11 @@
+# get_keys
+List all key names in a given section.
+
+`string[] toml::get_keys(string name, bool all = false);`
+
+## Arguments:
+- `string name`: The name of the section. Can be blank if you want.
+- `bool all = false`: Should the function fetch all keys of all sections? Note that this currently does not work if you have multiple keys with the same name.
+
+## Returns:
+`string[]`: An array containing all the keys.  An empty array means that the section is either blank or does not exist.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml/Methods/initialize_section.nvgt

@@ -0,0 +1,24 @@
+/**
+	Returns a TOML section with the given name, creating if necessary.
+	`toml_section@ toml::initialize_section(string name = "", bool create = false);`
+	## Arguments:
+		- `string name = ""`: The name of the section to retrieve. An empty string always means the main sectionless.
+		- `bool create = false`: Should this section be created if it does not exist?
+	## Returns:
+		`toml_section@`: A handle to the `toml_section` class on success, null otherwise.
+	## Remarks:
+		This method is useful to modify a specific section or create if necessary so you do not have to verify.
+*/
+
+// Example:
+#include "toml.nvgt"
+void main() {
+	toml t;
+	t.set("", "main_key", "Hello");
+	alert("Info", string(t.get("", "main_key", "Default value (woops?)")));
+	toml_section@ s = t.initialize_section("");
+	alert("Same as above box", string(s.get("main_key", "Default value")));
+	@s = t.initialize_section("test", true); // Create new.
+	s.set("testkey", "World");
+	alert("Info", t.dump());
+}

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml/Methods/load.md

@@ -0,0 +1,14 @@
+# load
+Load a TOML file / stream.
+
+1. `bool toml::load(string filename);`
+2. `bool toml::load(datastream@ f);`
+
+## Arguments (1):
+- `string filename`: The name of the TOML file to load.
+
+## Arguments (2):
+- `datastream@ f`: A stream (i.e the file object) that is ready to be read.
+
+## Returns:
+`bool`: `true` if the TOML data was successfully loaded, `false` otherwise.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml/Methods/loads.md

@@ -0,0 +1,10 @@
+# loads
+This function loads TOML data stored as a string, doing it this way insures that TOML data can come from any source, e.g. dynamic string.
+
+`bool toml::loads(string str);`
+
+## Arguments:
+- `string str`: The TOML data to load (as a string).
+
+## Returns:
+`bool`: `true` if the data was successfully loaded, `false` otherwise.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml/Methods/remove.md

@@ -0,0 +1,14 @@
+# remove
+Removes a key or a section.
+
+`bool toml::remove(string section, string key = "");`
+
+## Arguments:
+- `string section`: The section to remove or to look up the key from.
+- `string key = ""`: The key to remove. If this is set to blank, the entire section (if any) will be removed.
+
+## Returns:
+`bool`: `true` if the key or the section was successfully removed, `false` otherwise.
+
+## Remarks:
+If the `key` argument is empty, the function will remove the entire section. Otherwise, it will remove a given key if exists.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml/Methods/set.md

@@ -0,0 +1,15 @@
+# set
+Set a value in the TOML data given a section name, a key and a value.
+
+`bool toml::set(string section, string key = "", any@ value = null);`
+
+## Arguments:
+- `string section`: The section to put this key/value pair in (leave blank to add at the top of the file without a section).
+- `string key = ""`: The key to set.
+- `any@ value = null`: The value to set, see main  TOML Reader introduction for supported types. Unsupported type of value always returns `false`.
+
+## Returns:
+`bool`: `true` if the value was successfully written, `false` otherwise.
+
+## Remarks:
+If you specified a section that does not exist, it will automatically be created.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml_section/!toml_section.md

@@ -0,0 +1,11 @@
+# toml_section
+This class is integrated in `toml` class serving as a TOML section.
+
+`toml_section(string name, dictionary data = dictionary());`
+
+## Arguments:
+- `string name`: The name of the section. Empty for the main top section.
+- `dictionary data = dictionary()`: The data to associate with this section.
+
+## Remarks:
+You don't usually use this class unless you are doing with each TOML section.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml_section/Methods/dump.md

@@ -0,0 +1,13 @@
+# dump
+Dump all loaded data into a string.
+
+`string toml_section::dump(bool head, int indent_size = 0, int indent_head_size = 0, bool empty_sections = true);`
+
+## Arguments:
+- `bool head`: Should the data be prefixed with the section's name if the section name is not empty? For example, if the section is named test, the first line of the data will be `[test]`.
+- `int indent_size = 0`: Indentation size. 0 is no indentation.
+- `int indent_head_size = 0`: Indentation size for the header. This is the same with `indent_size` argument, but this is for the header itself if the `head` argument will be `true`.
+- `bool empty_sections = true`: Should the data include empty sections? Default is usually ok. If this is used from the main TOML class, this value is retrieved from the main `dump` method of the TOML class.
+
+## Returns:
+`string`: The entire TOML data of this section as a string.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml_section/Methods/get.md

@@ -0,0 +1,11 @@
+# get
+Fetch a value from the TOML data given a key.
+
+`var@ toml_section::get(string key, var@ def = null);`
+
+## Arguments:
+- `string key`: The key to get.
+- `var@ def = null`: The default value if the key could not be retrieved.
+
+## Returns:
+`var@`: The value at the particular key if found, the default value otherwise.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml_section/Methods/remove.md

@@ -0,0 +1,10 @@
+# remove
+Removes a key.
+
+`bool toml_section::remove(string key);`
+
+## Arguments:
+- `string key`: The key to remove.
+
+## Returns:
+`bool`: `true` if the key was successfully removed, `false` otherwise.

doc/src/references/include/TOML Reader and Writer (toml.nvgt)/classes/toml_section/Methods/set.md

@@ -0,0 +1,11 @@
+# set
+Set a value in the TOML data given a key and a value.
+
+`bool toml_section::set(string key, any@ value);`
+
+## Arguments:
+- `string key`: The key to set.
+- `any@ value`: The value to set. Supported types are the same with the ones in the main introduction documentation.
+
+## Returns:
+`bool`: `true` if the value was successfully written, `false` otherwise.