# Suzu Runtime / Notation Szun is a library for defining, manipulating, and formatting structured, dynamically-typed data. ## 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 ### Namespacing 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. ## 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|x22|size, type|Constant-sized, ordered collection| |List|x23|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()` * `boolean()` * `natural()` * `integer()` * `block(size)` * `sequence()` * `array(size, type)` * `list(type)` * `record(schema)` * `schema()` #### 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); let list = List::new(type_id); ``` ## Global Functions `acquire(type) -> Reference` Allocate a new instance of the provided type. ``` let refer = acquire(list(integer())); ``` --- `release(refer:Reference)` Destruct and deallocate a type. ``` release(refer); ``` > Warning: To avoid access violations, `release()` should not be used with interface objects, such as Boolean. --- `encode(refer:Reference) -> Vec` `encode_raw(refer:Reference) -> Vec` Serializes an object into binary encoding. The raw variant does not produce a tag prefix for the root object. > Not implemented --- `decode(data:Vec) -> Result` `decode_raw(data:Vec, type_id:usize) -> Result` Parses a valid binary encoding and produces the represented object. The raw variant does not decode a tag prefix on the root object. > Not implemented --- ## Language Compiler > Not implemented ## Common Methods `new() -> Self` ``` let value = Integer::new(); ``` --- `from(refer:Reference) -> Result` ``` match Integer::from(list.at(0)) { Ok(int) => { println!("Integer: {}", int.get()); } Err(_) => { println!("Not Integer"); } } ``` --- `with(value) -> Self` ``` let b = Boolean::with(true); ``` --- `*Dereference -> Reference` ``` let refer = *Integer::new(); ``` --- ## Varying Stores a value of any other type. `is_null() -> bool` Specifies whether or not the variable contains a object. --- `get() -> Reference` Returns a reference to the contained object. ``` let var = Varying::with(*Boolean::with(true)); let value = Boolean::from(var.get()).unwrap(); ``` --- `set(refer:Reference)` Replaces the contained object. ``` let var = Varying::new(); var.set(*Sequence::with("Hello!")); ``` --- ## Boolean Stores the value true or false. `get() -> bool` Returns the contained value. ``` let value = Boolean::with(true); if value.get() { println!("True"); } ``` --- `set(value:bool)` Replaces the contained value. ``` let mut value = Boolean::new(); value.set(true); ``` --- ## Natural Stores a non-negative integer value. `get() -> u64` Returns the contained value. ``` let value = Integer::with(-1); println!("{}", value.get()); ``` --- `set(value:u64)` Replaces the contained value. ``` let mut value = Integer::new(); value.set(-273); ``` --- ## Integer Stores a signed integer value. `get() -> i64` Returns the contained value. ``` let value = Integer::with(-1); println!("{}", value.get()); ``` --- `set(value:i64)` Replaces the contained value. ``` let mut value = Integer::new(); value.set(-273); ``` --- ## Significant Stores a fixed-precision, variable-magnitude ## Block Constant-sized series of bytes. `new(size:usize) -> Block` --- `length() -> usize` --- `get() -> Vec` --- `set(data:Vec)` --- ## Sequence Variable-sized series of bytes. `length() -> usize` --- `get() -> String` --- `get_raw() -> Vec` --- `set(data:&str)` --- `set_raw(data:Vec)` --- ## Array Constant-sized, ordered collection of items. `new(size:usize, type_id:usize) -> Array` --- `length() -> usize` --- `at(index:usize) -> Reference` --- `set(index:usize, refer:Reference)` --- ## List Variable-sized, ordered collection of items. `new(type_id:usize) -> List` --- `length() -> usize` --- `capacity() -> usize` --- `at(index:usize) -> Reference` --- `set(index:usize, refer:Reference)` --- `insert(index:usize, refer:Reference)` --- `remove(index:usize)` --- `reserve(capacity:usize)` --- `clear()` --- ## Schema Definition of an abstract structure composed of named items. `get(index:usize) -> usize` --- `add(type_id:usize) -> usize` --- `remove(index:usize)` --- `assign(key:&str, type_id:usize) -> usize` --- `map(key:&str, index:usize)` --- `unmap(key:&str)` --- `clear()` --- `bind(id:usize)` --- ## Record Instance of a schema. `new(schema_id:usize) -> Record` --- `at(index:usize) -> Reference` --- `set(index:usize, source:Reference)` --- `keyof(index:usize) -> String` --- `indexof(key:&str) -> usize` ---