6.7 KiB
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);
transfer(dst:Reference, src:Reference) -> Result<(),()>
Move an object from one location to another, clearing the original.
copy(dst:Reference, src:Reference) -> Result<(),()>
Copy the contents of an objcet to another location, keeping the original.
encode(refer:Reference) -> Vec<u8>
encode_raw(refer:Reference) -> Vec<u8>
encode_tag(refer:Reference) -> Vec<u8>
Serializes an object into binary encoding. The raw variant does not produce a tag prefix for the root object.
decode(data:&Vec<u8>, index:&mut usize) -> Result<Type,()>
decode_raw(data:&Vec<u8>, type_id:usize, index:&mut usize) -> Result<Type,()>
decode_tag(data:&Vec<u8>, index:&mut usize) -> Result<usize,()>
Parses a valid binary encoding and produces the represented object. The raw variant does not decode a tag prefix on the root object.
Language Compiler
Not implemented
Common Methods
new() -> Self
let value = Integer::new();
from(refer:Reference) -> Result<Self,()>
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 number.
get() -> f64
set(value:f64)
Block
Constant-sized series of bytes.
new(size:usize) -> Block
length() -> usize
get() -> Vec<u8>
set(data:Vec<u8>)
Sequence
Variable-sized series of bytes.
length() -> usize
get() -> String
get_raw() -> Vec<u8>
set(data:&str)
set_raw(data:Vec<u8>)
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