[−][src]Crate packs

A PackStream implementation written in Rust.

API

The trait Pack is for encoding, the trait Unpack is for decoding. They abstracted over Write and Read respectively.

The traits are implemented for some basic types as well as for a standard set of structs which come with the PackStream specification, see the std_structs module.

use packs::{Pack, Unpack};
use packs::std_structs::Node;

let mut node = Node::new(42);
node.properties.add_property("title", "A Book's Title");
node.properties.add_property("pages", 302);

// encode `node` into a `Vec<u8>`:
let mut buffer = Vec::new();
node.encode(&mut buffer).unwrap();

// and recover it from these bytes:
let recovered = Node::decode(&mut buffer.as_slice()).unwrap();

assert_eq!(node, recovered);

User-Defined Structs

A struct can be encoded and decoded in several ways, following the PackStream specification. Specifying a #[tag = u8] attribute interprets the struct as a Structure with provided tag byte and its fields as fields of a structure. I.e. it would be then treated like a Point2D or a Node from the std_structs.

use packs::*;

#[derive(Debug, PartialEq, Pack, Unpack)]
#[tag = 0x0B]
struct Book {
    pub title: String,
    pub pages: i64,
}

// this is not packed as a `Node`. It is a genuinely user defined struct,
// it will differ in its byte structure to the `Node` above.
let book = Book { title: String::from("A Book's title"), pages: 302 };

let mut buffer = Vec::new();
book.encode(&mut buffer).unwrap();

let recovered = Book::decode(&mut buffer.as_slice()).unwrap();

assert_eq!(book, recovered);

Providing a sum type

User defined structs are often sumed up in an enum which denotes all possible structs the protocol should be able to encode and decode. This can be given by deriving Pack and Unpack for an enum. The tag attribute on the different variants is not optional, but it can differ from the one tag attribute provided to the structs themselves.

use packs::*;

#[derive(Debug, PartialEq, Pack, Unpack)]
#[tag = 0x0B]
struct Book {
    pub title: String,
    pub pages: i64,
}

#[derive(Debug, PartialEq, Pack, Unpack)]
#[tag = 0x0C]
struct Person {
    pub name: String,
}

#[derive(Debug, PartialEq, Pack, Unpack)]
enum MyStruct {
    #[tag = 0x0B]
    Book(Book),
    #[tag = 0x0C]
    Person(Person),
}

let person = Person { name: String::from("Check Mate") };

let mut buffer = Vec::new();
person.encode(&mut buffer).unwrap();

// recover via `MyStruct`:
let my_struct = MyStruct::decode(&mut buffer.as_slice()).unwrap();

assert_eq!(MyStruct::Person(person), my_struct);

Tag consistency

Different tags at an enum variant and at its corresponding struct is possible and can be useful sometimes, to use the same struct in different settings. It might lead to inconsistency if encoding and decoding doesn't follow the same path though. For example, encoding a struct with its Pack implementation and then decode it, using an enum implementation of Unpack with a different tag will not work.

Runtime-typed values

Besides using the types directly, values can be encoded and decoded through a sum type Value which allows for decoding of any value without knowing its type beforehand.

use packs::{Value, Unpack, Pack, NoStruct};
use packs::std_structs::StdStruct;

let mut buffer = Vec::new();
42i64.encode(&mut buffer).unwrap();

let value = <Value<NoStruct>>::decode(&mut buffer.as_slice()).unwrap();

assert_eq!(Value::Integer(42), value);

The type Value is abstracted over possible structures. One can use NoStruct to deny any structures or use Value<StdStruct> (c.f. StdStruct) to allow any standard structures as part of Value.

To continue on the example from above, Value<MyStruct> could have been used there as well:

let mut buffer = Vec::new();
let person = Person { name: String::from("Check Mate") };
person
    .encode(&mut buffer)
    .unwrap();

let runtime_typed = <Value<MyStruct>>::decode(&mut buffer.as_slice()).unwrap();

assert_eq!(Value::Structure(MyStruct::Person(person)), runtime_typed);

Re-exports

pub use ll::marker::Marker;

Modules

ll
std_structs
utils

Structs

Bytes
Dictionary	A `Dictionary` is a map of `String` to `Value<T>` pairs. These pairs are also called `properties` and can be seen as named values. The type parameter denotes the allowed structures for a value.
GenericStruct	An anonymous, generic variant for structure values. It does denote different structures by a `tag_byte` field; all fields are written and read as `Value` in the order in which they were given. This allows for parsing of any structure which is validly encoded, valid in the PackStream specification sense, i.e. the struct marker and the field size, a tag byte denoting the struct type and then a list of the fields.

Enums

DecodeError
EncodeError
NoStruct	A void implementation with `Pack` and `Unpack` which can be used as a placeholder to deny any structures.
Value	A type for all possible values which can be serialized through PackStream. This type abstracts over structure types, which allows the user to define their own structures which should be part of `Value`. There are two standard implementations, either `Value<NoStruct>` to denote a value where nothing further allowed as a structure, or `Value<GenericStruct>` which reads any valid structure generic, see `GenericStruct`.

Traits

Extract	A trait to denote types which can be extracted out of a `Value<T>`.
ExtractMut	An `Extract` variant for mutably borrowed values.
ExtractRef	An `Extract` variant for borrowed values.
Pack	Trait to encode values into any writer using PackStream; using a space efficient way to pack.
Unpack	Trait to decode values from a stream using PackStream.

Functions

extract_list	A variant of `extract_list_ref` with a moved `Value`.
extract_list_mut	A variant of `extract_list_ref` with a mutable borrow.
extract_list_ref	Extracts a `Value::List` with the same runtime type values into a vector of extracted values.

Derive Macros

Pack
Unpack