A simple cerealisation library
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
plugin
src
tests
.gitignore
Cargo.toml
LICENSE-APACHE
LICENSE-MIT
README.md

README.md

Cereal

A simple cerealisation library.

No longer maintained. Recommended to use serde with bincode instead.

How it works

  • Primitives are serialisable (excluding slices/pointers/references/. This library is for handling raw data)
  • Things solely made out of primitives are serialisable.
    • Use #[derive(CerealData)] with nightly
    • Or impl_cereal_data! with stable.
  • Things that can be represented as primitive(s) or other serialisable(s) are also serialisable
    • String
    • Vec<CerealData>, HashMap<CerealData,CerealData>, and other collections as I think of them.
  • Empty things are serialisable.
    • ()
    • PhantomData<T> where T: CerealData

How you use it

1. Add to Cargo.toml

[dependencies]
# ...Other dependencies...
cereal = "*"

Or if you're on nightly, you may want to include cereal_macros

[dependencies]
# ...Other dependencies...
cereal = "*"
cereal_macros = "*"

2. Implement CerealData for your types.
Nightly:

#[derive(CerealData)]
struct MyAwesomeStruct {
    field1: u32,
    field2: String,
    field3: AnotherAwesomeStruct,
}

Stable:

struct MyAwesomeStruct {
    field1: u32,
    field2: String,
    field3: AnotherAwesomeStruct,
}
impl_cereal_data!(MyAwesomeStruct, field1, field2, field3);

Yes, you have to write out each field. It's annoying, but at least you have the comfort of knowing that your code will continue to work even if I forget to update the syntax extension for a compiler change.

3. Create your type

let my_awesome_instance = MyAwesomeStruct {
    // ...
};

4. Get a writer

let a_writer: &mut Write = /* ... */;

5. Write

my_awesome_instance.write(a_writer);

6. Stop compiler screaming about an unused result

-- my_awesome_instance.write(a_writer);
++ my_awesome_instance.write(a_writer).unwrap();

7. Get a reader

let a_reader: &mut Read = /* ... */;

8. Read

let my_awesome_instance_2 = MyAwesomeStruct::read(a_reader).unwrap();

A brief note on enums

As of v0.2.0, you can now #[derive(CerealData)] on enums with both tuple and struct variants. However, for now there is no macro available for people on stable/beta channels. It may be possible, but it will take some time.

What if it eats my laundry?

This library is by nature a binarvore (binary data eater), but feeding it unhealthy data could result in it turning into a laundrovore.

You have been warned

If you encounter any problems or missing socks, open up an issue on the issue tracker, or ping me on #rust-gamedev if I'm there (nick is HeroesGrave).

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.