smol legibility and readability improvements

selene 2025-12-15 23:10:52 +01:00
parent f88fd885f1
commit 7d18d1ca50
Signed by: sel
SSH key fingerprint: SHA256:33R/4Rx5Lu4o81LyJyXdMrmP5CJ6j7j1Soo0Dn7mKc0

@ -2,12 +2,10 @@
**the main unit of organization within the modular object format is the object instance.** an object instance (`wgu::types::ObjectInstance`, stored & transmitted as a [json object literal](https://benalman.com/news/2010/03/theres-no-such-thing-as-a-json/)) is a data structure representing a piece of computer data of a specified type. **the main unit of organization within the modular object format is the object instance.** an object instance (`wgu::types::ObjectInstance`, stored & transmitted as a [json object literal](https://benalman.com/news/2010/03/theres-no-such-thing-as-a-json/)) is a data structure representing a piece of computer data of a specified type.
core object data is categorized into three categories, `input`, `local`, `remote`. the structure of these categories depends on the object instance's `object_type`. due to this, within wgu, those categories are stored as *json object strings* in the corresponding columns of the `objects` sqlite table. object metadata (`variant`, `object_type`, timestamps, hashes, etc.) are stored alongside these categories. core object data is categorized into three categories, `input`, `local`, and `remote`. the structure of these categories depends on the object instance's `object_type`. due to this, wgu stores these categories as *json object strings* in the corresponding columns of the `objects` sqlite table. object metadata (`variant`, `object_type`, timestamps, hashes, etc.) are stored alongside these categories.
the keys in object instances are generally referred to as **properties**. the keys in object instances are generally referred to as **properties**.
> ⚠️ **warning**
>
> a **big** pitfall early on is confusing the properties `variant` with `input.variant` > a **big** pitfall early on is confusing the properties `variant` with `input.variant`
> >
> `variant` is for differentiating between multiple object instances with the same `input_sha256`, while `input.variant` is most often used for defining multiple structures inside one object, when it can represent multiple things (the best example of that is `meta/connection`) > `variant` is for differentiating between multiple object instances with the same `input_sha256`, while `input.variant` is most often used for defining multiple structures inside one object, when it can represent multiple things (the best example of that is `meta/connection`)
@ -18,11 +16,11 @@ for referencing object instances, the properties `input_sha256` and `variant` ar
- followed by the category and a `.` (dot) (`input` | `local` | `remote`, unless you're referring to a transform destination, in which case this *must* be ommited as it's always going to be `input`) - followed by the category and a `.` (dot) (`input` | `local` | `remote`, unless you're referring to a transform destination, in which case this *must* be ommited as it's always going to be `input`)
- followed by the property name - followed by the property name
> 🧪 **example:** `5aea...b0ca+0:input.value` > **example:** `5aea...b0ca+0:input.value`
if the property you're referring to can be [duplicated](#duplicates), you also have to add the position of the value in the resulting array within `[]` (square brackets): if the property you're referring to can be [duplicated](#duplicates), you also have to add the position of the value in the resulting array within `[]` (square brackets):
> 🧪 **example:** `acab...1312+0:remote.some.thing[2]` > **example:** `acab...1312+0:remote.some.thing[2]`
## instances ## instances
@ -47,7 +45,7 @@ below are the columns of the table `objects` in wgu's sqlite database. these cat
### timestamps ### timestamps
> 🚧 **under construction** > **under construction**
> >
> **this section needs more expansion!** you can contribute by documenting how this feature or module operates in the latest available version (also check for pull requests that would change that) > **this section needs more expansion!** you can contribute by documenting how this feature or module operates in the latest available version (also check for pull requests that would change that)
@ -66,15 +64,15 @@ below are the columns of the table `objects` in wgu's sqlite database. these cat
`input_sha256` is calculated as the sha256 checksum of the property `object_type` and properties under `input`, including the start and end braces, separated by `+` (plus) symbols `input_sha256` is calculated as the sha256 checksum of the property `object_type` and properties under `input`, including the start and end braces, separated by `+` (plus) symbols
> 🧪 **example:** `meta/dummy+{"value":"you are now breathing manually"}` -> `5aea ... b0ca` > **example:** `meta/dummy+{"value":"you are now breathing manually"}` -> `5aea ... b0ca`
`full_sha256` is calculated as the sha256 checksum of the property `object_type`, the timestamp `hashed`, and the categories `input`, `local`, and `remote`, including the start and end braces, separated by `+` (plus) symbols `full_sha256` is calculated as the sha256 checksum of the property `object_type`, the timestamp `hashed`, and the categories `input`, `local`, and `remote`, including the start and end braces, separated by `+` (plus) symbols
> 🧪 **example:** `meta/dummy+2025-01-01T00:05:00Z+{"value":"you are now breathing manually"}+{}+{}` -> `7f17 ... cbdc` > **example:** `meta/dummy+2025-01-01T00:05:00Z+{"value":"you are now breathing manually"}+{}+{}` -> `7f17 ... cbdc`
### logs ### logs
> 🚧 **under construction** > **under construction**
> >
> **this section needs more expansion!** you can contribute by documenting how this feature or module operates in the latest available version (also check for pull requests that would change that) > **this section needs more expansion!** you can contribute by documenting how this feature or module operates in the latest available version (also check for pull requests that would change that)
@ -119,7 +117,7 @@ for referencing templates, the name of the module and the name of the template a
to refer to a property within a template, the same rules apply as with object instances. add a `:` (colon) symbol, followed by the category (`input` | `local` | `remote`, unless you're referring to a transform destination, in which case it's always going to be `input`), followed by a `.` (dot) and the property name, which can be nested with `.` (dots). to refer to a property within a template, the same rules apply as with object instances. add a `:` (colon) symbol, followed by the category (`input` | `local` | `remote`, unless you're referring to a transform destination, in which case it's always going to be `input`), followed by a `.` (dot) and the property name, which can be nested with `.` (dots).
> 🧪 **example:** `meta/text:input.value` > **example:** `meta/text:input.value`
for example, this is the template of the [`meta/dummy`](meta-dummy.md) object type. for example, this is the template of the [`meta/dummy`](meta-dummy.md) object type.