Crate msgpack_schema[−][src]
Expand description
msgpack-schema is a schema language for describing data formats encoded in MessagePack.
It provides two derive macros Serialize
and Deserialize
that allow you to transcode MessagePack binary data to/from Rust data structures in a type-directed way.
use msgpack_schema::{Deserialize, Serialize}; #[derive(Deserialize, Serialize)] struct Human { #[tag = 0] name: String, #[tag = 2] #[optional] age: Option<u32>, }
Behaviours of serializers and deserializers
Some general rules
- The deserializer ignores irrelevant key-value pairs in MsgPack map objects.
- MsgPack map objects must not have duplicate keys.
Option<T>
is roughly equal to declaringT | null
in TypeScript. Deserializer interpretsnull
asNone
whateverT
is. SoOption<Option<T>>
is the same asOption<T>
(unless used together with#[optional]
.)
Structs with named fields
Structs with named fields will be serialized into a MsgPack map object whose keys are fixints specified by #[tag]
attributes.
schema | Rust | MessagePack |
---|---|---|
ⓘ struct S { #[tag = 0] foo: u32, #[tag = 1] bar: String, } |
ⓘ S { foo: 42, bar: "hello".to_owned() } |
|
Fields in named structs may be tagged with #[optional]
.
- The tagged field must be of type
Option<T>
. - On serialization, the key-value pair will not be included in the result map object when the field data contains
None
. - On deserialization, the field of the result struct will be filled with
None
when the given MsgPack map object contains no corresponding key-value pair.
Newtype structs
Tuple structs with only one element are treated transparently.
schema | Rust | MessagePack |
---|---|---|
ⓘ struct S(u32) |
ⓘ S(42) |
|
Unit structs and empty tuple structs
Serialization and deserialization of unit structs and empty tuple structs are currently unsupported.
schema | Rust | MessagePack |
---|---|---|
ⓘ struct S |
ⓘ
S |
UNSUPPORTED |
ⓘ struct S() |
ⓘ
S() |
UNSUPPORTED |
Unit variants and empty tuple variants
Unit variants and empty tuple variants are serialized into a single fixint whose value is determined by the tag.
schema | Rust | MessagePack |
---|---|---|
ⓘ enum E { #[tag = 3] Foo } |
ⓘ
E::Foo |
|
ⓘ enum E { #[tag = 3] Foo() } |
ⓘ
E::Foo() |
|
Newtype variants
Newtype variants (one-element tuple variants) are serialized into an array of the tag and the inner value.
schema | Rust | MessagePack |
---|---|---|
ⓘ enum E { #[tag = 3] Foo(u32) } |
ⓘ E::Foo(42) |
|
Untagged variants
Enums may be attached #[untagged]
when all variants are newtype variants.
Serializing untagged variants results in the same data layout as the inner type.
The deserializer deserializes into an untagged enum type by trying deserization one by one from the first variant to the last.
schema | Rust | MessagePack |
---|---|---|
ⓘ #[derive(Serialize, Deserialize)] #[untagged] enum Animal { Foo(String), Bar(u32), } |
ⓘ E::Bar(42) |
|
Modules
value |
Macros
msgpack | Constructs a MessagePack object. |
Enums
DeserializeError | |
Token |
Traits
Deserialize | |
Deserializer | |
Serialize | |
Serializer |
Functions
deserialize | Read out a MessagePack object. |
serialize | Write out a MessagePack object. |
Derive Macros
Deserialize | |
Serialize |