Tycho

A self describing binary format designed around the serde data model.

Getting started

To get started, you can import the latest release from crates.io

[dependencies]
tycho = "0.0.5"

or you can use the developmental version from the public git repository

[dependencies.tycho]
git = "https://github.com/SamHDev/tycho.git"

Tycho

Here is the datatypes within the Tycho format:

• Unit - A value containing no data. Maps directly to ()
• Value - A primitive, terminating type.
• Boolean - true or false value (bool)
• Unsigned8 - 8-bit unsigned integer (u8)
• Unsigned16 - 16-bit unsigned integer (u16)
• Unsigned32 - 32-bit unsigned integer (u32)
• Unsigned64 - 64-bit unsigned integer (u64)
• Unsigned128 - 128-bit unsigned integer (u128)
• Signed8 - 8-bit two compelement signed integer (i8)
• Signed16 - 16-bit two compelement signed integer (i16)
• Signed32 - 32-bit two compelement signed integer (i32)
• Signed64 - 64-bit two compelement signed integer (i64)
• Signed128 - 128-bit two compelement signed integer (i128)
• String - An UTF-8 string (&str)
• Char - A single UTF-8 character. (char)
• Bytes - An array of 8-bit bytes. (&[u8])
• Option - A Some or None value (Option<T>)
• Array - An untyped array of elements
• Structure - A untyped string-value map (struct)
• Map - A typed key-value map (Map<K, V>)
• List - A typed array of values (Vec<T>)
• Variant - A variable element type with a given name. (enum)

Variants

Enums in rust, are arguably one of its best features. Serde has four types of varaints in its data model. Rather than implementing each, the Variant type is used.

enum Enum {
Foo,
// Enum::Foo -> Variant("Foo", Unit)

Bar(String),
// Enum::Bar(...)` -> Variant("bar", ...)

Baz(bool, bool, bool),
// Enum::Baz(..., ..., ...) -> Variant("baz", List(..., ..., ...))

Qux { quux: String, quuz: bool }
// Enum::Qux { ... } => Variant("qux", Structure(...))
}

Tycho Elements

Tycho elements can be instantiated directly rather than being serialised through serde.

use tycho::{Element, Value, ValueUtil, ElementUtil};

// Instantiation
let string = Element::string("Hello World!");
let array = Element::array(vec![string]);

// Encoding
let bytes = tycho::encode(array);

// Decoding
let data = tycho::decode(bytes).unwrap();

// Unpacking
if let Element::Array(array) = data {
if let Some(Element::Value(Value::String(string))) = array.get(0) {
assert_eq!(string, "Hello World!")
}
# else { panic!() }
}
# else { panic!() }

Serialisation

The main feature of tycho is the ability to serialise and deserialise using the serde framework.

# use serde::Serialize;
# use tycho;

// Define a serilisable object
#[derive(Serialize)]
pub struct Person {
name: String,
foo: bool,
bar: u32
}

// Instantiate an structure
let person = Person { name: "Dirk Gently".to_string(), foo: false, bar: 42069 };

// Serialise
let element = tycho::to_element(&person).unwrap();

// Serialise and Encode
let bytes = tycho::to_bytes(&person).unwrap();

Deserialisation

# use serde::Deserialize;
# use tycho;
# use tycho::Element;
# use tycho::util::TychoStruct;

// Define a deserialisable object (see above)
# #[derive(Deserialize)]
# pub struct Person {
#    name: String,
#    foo: bool,
#    bar: u32
# }

// Decode bytes
let bytes = /* vec![ ... ] */
# vec![ 64, 3, 3, 102, 111, 111, 16, 0, 3, 98, 97, 114, 19, 0, 0, 164, 85, 4, 110, 97, 109, 101, 29, 11, 68, 105, 114, 107, 32, 71, 101, 110, 116, 108, 121 ];

let person: Person = tycho::from_bytes(bytes).unwrap();

// Decode element
let mut element = TychoStruct::new();
element.insert("name", "Arthur Dent");
element.insert("foo", false);
element.insert("bar", 69420u32);

let person: Person = tycho::from_element(element.into()).unwrap();