Crate tycho[−][src]

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.6"

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!")
    }
}

Serialisation

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


// 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


// Define a deserialisable object (see above)

// Decode bytes
let bytes = /* vec![ ... ] */

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();

Re-exports

pub use ser::error::TychoSerializerError as SerializeError;

pub use de::error::TychoDeserializeError as DeserializeError;

Modules

de
ser
util

Enums

Element	A non-terminating value, structure or array.
Value	A primitive, terminating value.

Traits

ElementUtil
ValueUtil

Functions

decode	Decode an element from bytes.
encode	Encode an element into bytes.
from_bytes	Deserialize from bytes
from_element	Deserialize from an element
to_bytes	Serialize into bytes
to_element	Serialize from into an element