Update README with types list and usage information.

This commit is contained in:
yukirij 2023-08-12 03:03:28 -07:00
parent 50fa81005d
commit b24c3a5c62

View File

@ -1,7 +1,18 @@
# Suzu Runtime / Notation # Suzu Runtime / Notation
Szun is a library for defining, manipulating, and formatting structured, dynamically-typed data. Szun is a library for defining, manipulating, and formatting structured, dynamically-typed data.
# Documentation ## Runtime
The Szun runtime provides an interface for constructing and modfying data objects.
## Encoding
Szun uses a tag-prefixed, hierarchical, binary encoding with variable-sized values to produce serializations of reduced size.
## Language
Szun notation provides a human-readable format for structures and data to be defined.
The notation may be parsed and loaded at runtime or compiled directly into encoded format.
# Runtime Documentation
## Conventions ## Conventions
@ -9,8 +20,28 @@ Szun is a library for defining, manipulating, and formatting structured, dynamic
Examples in this documentation will assume inclusion of the szun namespace. Examples in this documentation will assume inclusion of the szun namespace.
Practical examples should use `szun::` or `use szun::{...};` in limited scopes. Practical examples should use `szun::` or `use szun::{...};` in limited scopes.
### Interface Usage
While the runtime provides methods for directly acquring and releasing memory, it is recommended that developers use typed interfaces to ensure memory is freed upon leaving scope.
## Type Building
## Data Types
|Type|Code|Parameters|Description|
|---|---|---|---|
|Undefined|x00|--|Data is not defined|
|Varying|x01|--|Stores any data type|
|Boolean|x02|--|True or false|
|Natural|x10|--|Non-negative integers|
|Integer|x11|--|Integers|
|Decimal|x12|--|Floating-point representable numbers|
|Block|x1e|size|Constant-sized series of bytes|
|Sequence|x1f|--|Variable-sized series of bytes|
|Array|x21|size, type|Constant-sized, ordered collection|
|List|x22|type|Variable-sized, ordered collection|
|Record|x7e|schema|Instance of a schema|
|Schema|x7f|--|Definition of abstract structure|
### Type Building
Type building functions are used to generate identifiers used in the construction of complex data types. Type building functions are used to generate identifiers used in the construction of complex data types.
* `varying()` * `varying()`
@ -21,10 +52,10 @@ Type building functions are used to generate identifiers used in the constructio
* `sequence()` * `sequence()`
* `array(size, type)` * `array(size, type)`
* `list(type)` * `list(type)`
* `schema()`
* `record(schema)` * `record(schema)`
* `schema()`
### Example #### Example
This example produces an identifier representing block of 4 bytes, which can be used to construct a list containing that type. This example produces an identifier representing block of 4 bytes, which can be used to construct a list containing that type.
``` ```
let type_id = block(4); let type_id = block(4);