# Ratio Metadata
At [Ratio CASE](https://www.ratio-case.nl) we use a common metadata model throughout our crates and applications for "items" which can be anything. It consists of:
- An (externally defined) unique ID.
- A name.
- A set of categorical labels or tags.
- A set of numerical weights.
- Any remaining "free-form" annotations as JSON serializable values.
This crate provides a "manager" for the metadata side of these things depending on unique keys for objects coming from [`SlotMap`]. Internally it uses [`SecondaryMap`] objects to store the additional metadata per object.
[SlotMap]: https://docs.rs/slotmap/latest/slotmap/struct.SlotMap.html
[SecondaryMap]: https://docs.rs/slotmap/latest/slotmap/struct.SecondaryMap.html
## Examples
Let's get to it!
```foo
// Some imports from slotmap.
// We use the default key implementation, but custom keys work just as well.
use slotmap::{DefaultKey, SlotMap};
// The store we want to fill!
use ratio_metadata::{MetadataStore, Metadata, MetadataRef};
// Let's configure a 'MetaStore' type by filling in MetadataStore's generics.
#[derive(PartialEq, PartialOrd, Eq, Ord)]
pub enum Kind {
K1,
K2,
}
#[derive(PartialEq, PartialOrd, Eq, Ord)]
pub enum Label {
L1,
L2,
L3,
}
#[derive(PartialEq, PartialOrd, Eq, Ord)]
pub enum Weight {
W1,
W2,
}
#[derive(PartialEq, PartialOrd, Eq, Ord)]
pub enum Annotation {
A1,
A2,
}
type MetaStore = MetadataStore<DefaultKey, String, Kind, Label, Weight, Annotation>;
type Meta = Metadata<String, Kind, Label, Weight, Annotation>;
type MetaRef<'a> = MetadataRef<'a, String, Kind, Label, Weight, Annotation>;
// Initialize the variables.
let mut sm: SlotMap<DefaultKey, ()> = SlotMap::new();
let mut metas = MetaStore::default();
```
## Changelog
This repository keeps a [CHANGELOG.md](https://gitlab.com/ratio-case-os/rust/ratio-metadata/-/blob/main/CHANGELOG.md) according to the recommendations by
[Keep a Changelog](https://keepachangelog.com/).
## Contributions
Contributions are welcome! By submitting a contribution, you agree to license your work under the terms of the [Mozilla Public License 2.0](https://mozilla.org/MPL/2.0/). Please ensure that your contributions adhere to the existing code style and include appropriate tests and documentation where applicable.
### To get started:
1. Fork the repo
1. Create a new branch
1. Make your changes
1. Make sure you run `just fix` to adhere to the project's formatting
1. Submit a merge request with a clear description of the changes
### Licensing
This project is licensed under the [Mozilla Public License 2.0](https://mozilla.org/MPL/2.0/). You are free to use, modify, and distribute this code, provided that any files you modify or create that are based on MPL-licensed files also remain under the MPL. You must include a copy of the license with the source and make the source code available when distributing binaries.
See the [LICENSE](https://gitlab.com/ratio-case-os/rust/ratio-metadata/-/blob/main/LICENSE) file for the full license text.
**Code examples both in the docstrings and rendered documentation thereof are free to use!**
At Ratio, we are huge supporters of open-source code and the open-source community. In our Python projects we usually strive to use one of the (L)GPL flavors. These are difficult to pair with compiled codebases, however, which is where we see the MPL-2.0 as a great fit for our open-source Rust efforts. It's a weak copyleft license that just protects the source as it is written and encourages changes to the crate's source to be published accordingly. It's sort of "automagically" implied and done right when `cargo` would pull in the source files to build with, as (the mentioning of) the license is included in the header of each file, and any binaries you generate with them are not of our concern from a distribution perspective.
Enjoy the code!