Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/doctorn/obake
Versioned data-structures for Rust
https://github.com/doctorn/obake
migration rust serialization versioning
Last synced: about 2 months ago
JSON representation
Versioned data-structures for Rust
- Host: GitHub
- URL: https://github.com/doctorn/obake
- Owner: doctorn
- License: apache-2.0
- Created: 2021-08-26T13:28:55.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-04-20T14:48:59.000Z (over 1 year ago)
- Last Synced: 2024-05-01T18:34:53.655Z (5 months ago)
- Topics: migration, rust, serialization, versioning
- Language: Rust
- Homepage:
- Size: 74.2 KB
- Stars: 202
- Watchers: 4
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
[](https://github.com/doctorn/obake/actions/workflows/obake.yml)
[![Issues][issues-shield]][issues-url]
[![crates.io][crates-io-shield]][crates-io-url]
[![License][license-shield]][license-url]
お化け
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 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 { bar: 42 }).into();
// this enumeration implements `Into`, 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`](https://serde.rs) attributes to be applied to
generated `enum`s.
- 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
Licensed under either of Apache License, Version
2.0 or MIT license at your option.
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.
[crates-io-shield]: https://img.shields.io/crates/v/obake
[crates-io-url]: https://crates.io/crates/obake
[issues-shield]: https://img.shields.io/github/issues/doctorn/obake.svg
[issues-url]: https://github.com/doctorn/obake/issues
[license-shield]: https://img.shields.io/crates/l/obake
[license-url]: https://github.com/doctorn/obake/blob/main/LICENSE-APACHE