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.
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**.
> ⚠️ **warning**
>
> 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`)
@ -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 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):
> 🧪 **example:** `acab...1312+0:remote.some.thing[2]`
> **example:** `acab...1312+0:remote.some.thing[2]`
## instances
@ -47,7 +45,7 @@ below are the columns of the table `objects` in wgu's sqlite database. these cat
### 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)
@ -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
> 🧪 **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
> 🧪 **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
> 🚧 **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)
@ -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).
> 🧪 **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.