From 50fa81005dcf4ec6a598d5a6af64106601d481b8 Mon Sep 17 00:00:00 2001 From: yukirij Date: Fri, 11 Aug 2023 20:12:04 -0700 Subject: [PATCH] Update README, add acquire/release interface functions. --- README.md | 275 ++++++++++++++++++++++++++++++------------ src/interface/mod.rs | 1 + src/interface/util.rs | 11 ++ src/runtime/lib.cc | 1 - src/runtime/type.h | 7 +- 5 files changed, 214 insertions(+), 81 deletions(-) create mode 100644 src/interface/util.rs diff --git a/README.md b/README.md index a29b859..74dafef 100644 --- a/README.md +++ b/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 +`release(refer:Reference)` -### decode(data:Vec) -> 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` + +> Not implemented +--- + +`decode(data:Vec) -> Reference` + +> Not implemented +--- ## Language Compiler - +> Not implemented ## Common Methods -### new() -> Self +`new() -> Self` + ``` let value = Integer::new(); ``` +--- + +`from(refer:Reference) -> Result` -### from(ref:Reference) -> Result ``` 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"); + 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` + +--- + +`set(data:Vec)` + +--- + ## Sequence Variable-sized series of bytes. -### get() -> String +`length() -> usize` -### get_raw() -> Vec +--- -### set(data:&str) +`get() -> String` -### set_raw(data:Vec) +--- + +`get_raw() -> Vec` + +--- + +`set(data:&str)` + +--- + +`set_raw(data:Vec)` + +--- ## 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` + +--- diff --git a/src/interface/mod.rs b/src/interface/mod.rs index b2ea5d5..76316a9 100644 --- a/src/interface/mod.rs +++ b/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; diff --git a/src/interface/util.rs b/src/interface/util.rs new file mode 100644 index 0000000..ed7a5ca --- /dev/null +++ b/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)} +} diff --git a/src/runtime/lib.cc b/src/runtime/lib.cc index ac051ae..b1bb700 100644 --- a/src/runtime/lib.cc +++ b/src/runtime/lib.cc @@ -703,7 +703,6 @@ extern "C" size_t schema_bind(Reference addr, size_t id) auto& object = (*reinterpret_cast(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(rawlist_cell(object.data, sizeof(size_t), i)); diff --git a/src/runtime/type.h b/src/runtime/type.h index 9d8f6b6..d91b88f 100644 --- a/src/runtime/type.h +++ b/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 data; }; }