toml: Reformatted README
- infos/metadata = order comment/# comment/#/start comment/#/space type tomltype origvalue
- infos/description = This storage plugin reads and writes TOML files, using Flex and Bison.
-# TODO: Documentation
-
# NULL/empty keys
+
The plugin supports null and empty keys with the help of the [null](../null/README.md) plugin.
# Requirements
- - The plugin needs Flex (TODO: min version) and Bison (minimal version 3).
+The plugin needs Flex (TODO: min version) and Bison (minimal version 3).
# Strings
+
Although the plugin can read any kind of TOML string (bare, basic, literal, basic multiline, literal multiline) it will write back all non-bare strings as basic strings (and it's multiline version of it).
Therefore, any string set with `kdb set` must be treated as a basic string and possible escape sequences and special meanings of quotation characters must be taken care of.
@@ -46,11 +46,13 @@ sudo kdb umount user/tests/storage
```
# TOML specific structures
+
TOML specific structures are represented by the metakey `tomltype` on a certain key.
It will be set when the TOML plugin reads a TOML structure from a file. Additionally, this metakey can be set by the user, if they want a certain TOML structure to be written.
No automatic inference of this metakey is done on writing.
## Simple Tables
+
TOML's simple tables are represented by setting the `tomltype` metakey to `simpletable`.
```
@@ -85,6 +87,7 @@ sudo kdb umount user/tests/storage
```
## Table Arrays
+
Table arrays are represented by setting the `tomltype` metakey to `tablearray`. It is not required to also set the array metakey, since the plugin will set the metakey, if it is missing.
```
@@ -126,14 +129,18 @@ sudo kdb umount user/tests/storage
## Inline Tables
+TODO: Write doc
+
## Arrays
+
Arrays are recognized by the `array` metakey. On writing, the plugin will detect arrays automatically and set the appropriate metakey if it is missing.
TODO: Example
# Order
+
The plugin preserves the file order by the usage of the metakey `order`. When reading a file, the order metakey will be set according to the order as read in the file.
-If you add new keys by eg. `kdb set` the order of the set key will be set to the next-to-highest order value present in the existing key set.
-However, the order is only relevant between elements with the same TOML-parent. For example keys of a simple table are only sorted with each other, not with any keys outside that table. If that table has it's order changed and moves to another position in the file, so will it's subkeys.
+If new keys are added, eg. via `kdb set`, the order of the set key will be set to the next-to-highest order value present in the existing key set.
+However, the order is only relevant between elements with the same TOML-parent. For example keys of a simple table are only sorted with respecet to each other, not with any keys outside that table. If that table has it's order changed and moves to another position in the file, so will it's subkeys.
There is an additional limitation on ordering for prevention of messing up resulting TOML-file semantics on writing.
When sorting elements under the same TOML-parent, tables (simple and array) will always be sorted after non-table elements, regardless of their order.
