diff options
author | Katharina Fey <kookie@spacekookie.de> | 2019-02-28 20:33:22 +0100 |
---|---|---|
committer | Katharina Fey <kookie@spacekookie.de> | 2019-02-28 20:33:22 +0100 |
commit | f28abd489cc7ebd9f2d14f584052a93607d78985 (patch) | |
tree | 6f1780cb8cd0c6f792fe5120b21bf3586bbf4afa | |
parent | 89d2605fe096b7ff483b0f7acb5e4f29c8c6e98f (diff) |
Adjusting the way that schemas work
-rw-r--r-- | README.md | 36 |
1 files changed, 21 insertions, 15 deletions
@@ -33,6 +33,12 @@ defining what data types exist and how they are layed out. The file extention for a `g3f` file is `.g3f` by default, however this implementation is not opinionated on that. +Another important point: +it should be considered part of the spec that writes are +done in-place to existing data. +No data should be overwritten if not explicitly desired +by the application using the `g3f` library! + ### Header At the top of every `g3f` file is a header. @@ -47,14 +53,15 @@ It looks something like this {impl "g3f-reference"} {impl_version "0.8.5"} -{schemas} -# ... +{data} ``` A few notes here: -- `g3f` is a flat format. When declaring a new top-level block (i.e. `{schemas}`) this ends the `{header}` block. -- A block can enforce a schema (i.e. here we enforce that all required fields from `builtin/header` are present) +- `g3f` is a flat format. When declaring a new top-level block + (i.e. `{data}`) this ends the `{header}` block. +- A block can enforce a schema (i.e. here we enforce that all + required fields from `builtin/header` are present) - Nodes always have a single data value. Supported types are - string (`"1.0.0"`) - int (`42`) @@ -63,23 +70,22 @@ A few notes here: - list<...> (`[ ... ]` - Elements are not comma-separated!) - ref (`some_id` - not quoted!) - type (`<...>` refers to some type information - - NULL (`<>` which is an empty type/name marker) + - schema (`<schema>` as a literal) - `#` is a line comment. There are no block-comments ### Schemas As previously mentioned `g3f` is a strongly typed file format. Schemas are IDs that can be referenced by other IDs. -But because `g3f` is completely flat, it's impossible to define -schema blocks inside the `{schema}` block itself. - -Instead it uses the `NULL` markers to define the existence of schemas. -Schemas are then later defined in-line with the rest of the data. +Because `g3f` is completely flat, it's impossible to have a `{schemas}` +block in which to define schemas. +Instead inside the header it's possible to use the `<schema>` type marker +to pre-declare schema data which will later be defined by blocks. ```g3f -{schemas} -{node <>} -{link <>} +{header} +{node <schema>} +{links <schema>} {node} {id <int>} @@ -100,7 +106,7 @@ if you want your file format to be completely dynamic and terrible. ```g3f {<>:node} {id 0} -{links [ 1 ]:} +{links [ 1 ]} {<>:node} {id 1} @@ -131,7 +137,7 @@ struct node_t { struct node_t * nodes = [ node_t { ... }, node_t { ... } ]; ``` -Because `g3f` has no hirarchy structure, and there's no in-file format references between the two nodes, +Because `g3f` has no hierarchical structure, and there's no in-file format references between the two nodes, the deserialised returns a list of nodes. Building a graph in memory is then your responsibility. However, `g3f` can handle a few scenarios for you. |