375 lines
5.6 KiB
Markdown
375 lines
5.6 KiB
Markdown
# 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|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()`
|
|
* `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<u8>`
|
|
|
|
> Not implemented
|
|
---
|
|
|
|
`decode(data:Vec<u8>) -> Reference`
|
|
|
|
> Not implemented
|
|
---
|
|
|
|
## 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`
|
|
|
|
---
|
|
|
|
`get() -> Reference`
|
|
|
|
```
|
|
let var = Varying::with(*Boolean::with(true));
|
|
let value = Boolean::from(var.get()).unwrap();
|
|
```
|
|
---
|
|
|
|
`set(refer:Reference)`
|
|
|
|
```
|
|
let var = Varying::new();
|
|
var.set(*Sequence::with("Hello!"));
|
|
```
|
|
---
|
|
|
|
|
|
## Boolean
|
|
Stores the value true or false.
|
|
|
|
`get() -> bool`
|
|
|
|
```
|
|
let value = Boolean::with(true);
|
|
if value.get() {
|
|
println!("True");
|
|
}
|
|
```
|
|
---
|
|
|
|
`set(value:bool)`
|
|
|
|
```
|
|
let mut value = Boolean::new();
|
|
value.set(true);
|
|
```
|
|
---
|
|
|
|
|
|
## Natural
|
|
Stores a non-negative integer value.
|
|
|
|
`get() -> u64`
|
|
```
|
|
let value = Integer::with(-1);
|
|
println!("{}", value.get());
|
|
```
|
|
---
|
|
|
|
`set(value:u64)`
|
|
```
|
|
let mut value = Integer::new();
|
|
value.set(-273);
|
|
```
|
|
---
|
|
|
|
|
|
## Integer
|
|
Stores a signed integer value.
|
|
|
|
`get() -> i64`
|
|
```
|
|
let value = Integer::with(-1);
|
|
println!("{}", value.get());
|
|
```
|
|
---
|
|
|
|
`set(value:i64)`
|
|
```
|
|
let mut value = Integer::new();
|
|
value.set(-273);
|
|
```
|
|
---
|
|
|
|
|
|
## 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`
|
|
|
|
---
|