[−][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 |
GenericStruct | An anonymous, generic variant for structure values. It does denote different structures by
a |
Enums
DecodeError | |
EncodeError | |
NoStruct | A void implementation with |
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 |
Traits
Extract | A trait to denote types which can be extracted out of a |
ExtractMut | An |
ExtractRef | An |
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_mut | A variant of |
extract_list_ref | Extracts a |
Derive Macros
Pack | |
Unpack |