diff --git a/README.md b/README.md index 74dafef..3f313f4 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,18 @@ # Suzu Runtime / Notation 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 @@ -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. 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. * `varying()` @@ -21,10 +52,10 @@ Type building functions are used to generate identifiers used in the constructio * `sequence()` * `array(size, type)` * `list(type)` -* `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. ``` let type_id = block(4);