Update README, add acquire/release interface functions.

README.md

@@ -1,4 +1,5 @@
-# Suzu Runtime and Notation
+# Suzu Runtime / Notation
+Szun is a library for defining, manipulating, and formatting structured, dynamically-typed data.
 
 # Documentation
 
@@ -6,221 +7,337 @@
 
 ### Namespacing
 Examples in this documentation will assume inclusion of the szun namespace.
-In practice, this is not recommended outside of limited scopes.
-```
-fn procedure()
-{
-    use szun::*;
-
-    /* ... */
-}
-```
+Practical examples should use `szun::` or `use szun::{...};` in limited scopes.
 
 
 ## Type Building
-Type building functions allow for the construction of identifiers representing complex data types. These identifiers are used to allocate typed 
-```
-varying()
-boolean()
-natural()
-integer()
-block(size)
-sequence()
-array(size, type)
-list(type)
-schema()
-record(schema)
-```
+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)`
+* `schema()`
+* `record(schema)`
 
 ### Example
-This example produces an identifier representing a list of blocks of 4 bytes each.
+This example produces an identifier representing block of 4 bytes, which can be used to construct a list containing that type.
 ```
-let type_id = list(block(4));
+let type_id = block(4);
+let list = List::new(type_id);
 ```
 
 ## Global Functions
 
-### allocate(type)
+`acquire(type) -> Reference`
+
+Allocate a new instance of the provided type.
 ```
-let ref = allocate(list(integer()));
+let refer = acquire(list(integer()));
 ```
+---
 
-### encode(ref:Reference) -> vec<u8>
+`release(refer:Reference)`
 
-### decode(data:Vec<u8>) -> 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
+`new() -> Self`
+
 ```
 let value = Integer::new();
 ```
+---
+
+`from(refer:Reference) -> Result<Self,()>`
 
-### from(ref:Reference) -> Result<Self,()>
 ```
 match Integer::from(list.at(0)) {
-    Ok(data) => { println!("Integer: {}", data); }
+    Ok(int) => { println!("Integer: {}", int.get()); }
     Err(_) => { println!("Not Integer"); }
 }
 ```
+---
+
+`with(value) -> Self`
 
-### with(value) -> Self
 ```
 let b = Boolean::with(true);
 ```
+---
+
+`*Dereference -> Reference`
 
-### Dereference
 ```
-let ref = *Integer::new();
+let refer = *Integer::new();
 ```
+---
 
 
 ## Varying
+Stores a value of any other type.
 
-### set(ref:Reference)
-```
-let var = Varying::new();
-var.set(*Sequence::with("Hello!"))
-```
+`is_null() -> bool`
+
+---
+
+`get() -> Reference`
 
-### get() -> Reference
 ```
 let var = Varying::with(*Boolean::with(true));
-let ref = var.get();
+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
+`get() -> bool`
+
 ```
 let value = Boolean::with(true);
 if value.get() {
     println!("True");
 }
 ```
+---
+
+`set(value:bool)`
 
-### set(value:bool)
 ```
 let mut value = Boolean::new();
 value.set(true);
 ```
+---
 
 
 ## Natural
 Stores a non-negative integer value.
 
-### get() -> u64
+`get() -> u64`
 ```
 let value = Integer::with(-1);
 println!("{}", value.get());
 ```
+---
 
-### set(value:u64)
+`set(value:u64)`
 ```
 let mut value = Integer::new();
 value.set(-273);
 ```
+---
 
 
 ## Integer
 Stores a signed integer value.
 
-### get() -> i64
+`get() -> i64`
 ```
 let value = Integer::with(-1);
 println!("{}", value.get());
 ```
+---
 
-### set(value:i64)
+`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.
 
-### get() -> String
+`length() -> usize`
 
-### get_raw() -> Vec<u8>
+---
 
-### set(data:&str)
+`get() -> String`
 
-### set_raw(data:Vec<u8>)
+---
+
+`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)
+`new(size:usize, type_id:usize) -> Array`
 
-### length() -> usize
+---
 
-### at(index:usize) -> Reference
+`length() -> usize`
 
-### set(index:usize, ref:Reference)
+---
+
+`at(index:usize) -> Reference`
+
+---
+
+`set(index:usize, refer:Reference)`
+
+---
 
 
 ## List
 Variable-sized, ordered collection of items.
 
-### new(type_id:usize)
+`new(type_id:usize) -> List`
 
-### length() -> usize
+---
 
-### capacity() -> usize
+`length() -> usize`
 
-### at(index:usize) -> Reference
+---
 
-### set(index:usize, ref:Reference)
+`capacity() -> usize`
 
-### insert(index:usize, ref:Reference)
+---
 
-### remove(index:usize)
+`at(index:usize) -> Reference`
 
-### reserve(capacity:usize)
+---
 
-### clear()
+`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
+`get(index:usize) -> usize`
 
-### add(type_id:usize) -> usize
+---
 
-### remove(index:usize)
+`add(type_id:usize) -> usize`
 
-### assign(key:&str, type_id:usize) -> usize
+---
 
-### map(key:&str, index:usize)
+`remove(index:usize)`
 
-### unmap(key:&str)
+---
 
-### clear()
+`assign(key:&str, type_id:usize) -> usize`
 
-### bind(id:usize)
+---
+
+`map(key:&str, index:usize)`
+
+---
+
+`unmap(key:&str)`
+
+---
+
+`clear()`
+
+---
+
+`bind(id:usize)`
+
+---
 
 
 ## Record
 Instance of a schema.
 
-### at(index:usize) -> Reference
+`new(schema_id:usize) -> Record`
 
-### set(index:usize, source:Reference)
+---
 
-### keyof(index:usize) -> String
+`at(index:usize) -> Reference`
 
-### indexof(key:&str) -> usize
+---
+
+`set(index:usize, source:Reference)`
+
+---
+
+`keyof(index:usize) -> String`
+
+---
+
+`indexof(key:&str) -> usize`
+
+---

src/interface/mod.rs

@@ -2,6 +2,7 @@ use crate::runtime::{Reference, type_key};
 use crate::tag;
 
 mod builder; pub use builder::*;
+mod util; pub use util::*;
 
 mod varying; pub use varying::Varying;
 mod boolean; pub use boolean::Boolean;

src/interface/util.rs

@@ -0,0 +1,11 @@
+use crate::runtime;
+
+pub fn acquire(type_id:usize) -> runtime::Reference
+{
+    unsafe {runtime::acquire(type_id)}
+}
+
+pub fn release(addr:Reference)
+{
+    unsafe {runtime::release(addr)}
+}

src/runtime/lib.cc

@@ -703,7 +703,6 @@ extern "C" size_t schema_bind(Reference addr, size_t id)
     auto& object = (*reinterpret_cast<Type::Schema*>(addr.address));
 
     // prepare binding
-    binding.schema = object;
     binding.binding = id;
     for(size_t i = 0; i < object.data.length; ++i) {
         size_t type_id = *reinterpret_cast<size_t*>(rawlist_cell(object.data, sizeof(size_t), i));

src/runtime/type.h

@@ -66,10 +66,15 @@ struct Schema {
 };
 
 struct SchemaBinding {
+    struct Row {
+        size_t type;
+        size_t offset;
+    };
+
     size_t binding;
     size_t alignment;
     size_t size;
-    Schema schema;
+    std::vector<Row> data;
 };
 
 }