お化け

Obake

Versioned data-structures for Rust.
View on docs.rs »

About

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.

Getting Started

To get started, add the following to your Cargo.toml file:

toml [dependencies] obake = "1.0"

Example

```rust

[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 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 { 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 }); ```

Other Features

• #[obake(inherit)]: allows nesting of versioned data-structures.
• #[obake(derive(...))]: allows derive attributes to be applied to generated enums.
• #[obake(serde(...))]: allows serde attributes to be applied to generated enums.
  • Note: requires the feature serde.

Limitations

• Cannot be applied to tuple structs (or enum variants with unnamed fields).
• Cannot be applied to items with generic parameters.

License

<sup>Licensed under either of Apache License, Version 2.0 or MIT license at your option.</sup>

<sub>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.</sub>