Versioned data-structures for Rust.
View on docs.rs »
Obake is a procedural macro for declaring and maintaining versioned data-structures. The name 'obake' is taken from the Japanese 'お化け (おばけ)', a class of supernatural beings in Japanese folklore that shapeshift.
When developing an application, configuration formats and internal data-structures typically evolve between versions. However, maintaining backwards compatibility between these versions requires declaring and maintaining data-structures for legacy formats and code for migrating between them. Obake aims to make this process effortless.
To get started, add the following to your Cargo.toml
file:
[dependencies]
obake = "1.0"
#[obake::versioned] // create a versioned data-structure
#[obake(version("0.1.0"))] // declare some versions
#[obake(version("0.2.0"))]
#[derive(Debug, PartialEq, Eq)] // additional attributes are applied to all versions
struct Foo {
#[obake(cfg("0.1.0"))] // enable fields for specific versions with
foo: String, // semantic version constraints
#[obake(cfg(">=0.2, <=0.3.0"))] // any semantic version constraint can appear in
bar: u32, // a `cfg` attribute
#[obake(cfg("0.1.0"))] // multiple `cfg` attributes are treated as a
#[obake(cfg(">=0.3"))] // disjunction over version constraints
baz: char,
}
// describe migrations between versions using the `From` trait
// and an automatically generated type-level macro for referring to
// specific versions of `Foo`
impl From<Foo!["0.1.0"]> for Foo!["0.2.0"] {
fn from(foo: Foo!["0.1.0"]) -> Self {
Self { bar: 0 }
}
}
// an enumeration of all versions of `Foo` is accessed using the `obake::AnyVersion` type
// alias
let versioned_example: obake::AnyVersion<Foo> = (Foo { bar: 42 }).into();
// this enumeration implements `Into<Foo>`, where `Foo` is the latest declared
// version of `Foo` (in this case, `Foo!["0.2.0"]`)
let example: Foo = versioned_example.into();
assert_eq!(example, Foo { bar: 42 });
#[obake(inherit)]
: allows nesting of versioned data-structures.#[obake(derive(...))]
: allows derive attributes to be applied to generated enums.#[obake(serde(...))]
: allowsserde
attributes to be applied to generatedenum
s.- Note: requires the feature
serde
.
- Note: requires the feature
- Cannot be applied to tuple structs (or enum variants with unnamed fields).
- Cannot be applied to items with generic parameters.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Obake by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.