value-bag
Getting started
Add the value-bag
crate to your Cargo.toml
:
= "1.0.0-alpha.9"
version
You'll probably also want to add a feature for either sval
(if you're in a no-std environment) or serde
(if you need to integrate with other code that uses serde
):
= "1.0.0-alpha.9"
features =
version
= "1.0.0-alpha.9"
features =
version
Then you're ready to capture anonymous values!
// Capture a value that implements `serde::Serialize`
let bag = capture_serde1;
// Print the contents of the value bag
println!;
Cargo features
The value-bag
crate is no-std by default, and offers the following Cargo features:
std
: Enable support for the standard library. This allows more types to be captured in aValueBag
.error
: Enable support for capturingstd::error::Error
s. Impliesstd
.sval
: Enable support for using thesval
serialization framework for inspectingValueBag
s by implementingsval::value::Value
. Impliessval1
.sval1
: Enable support for the stable1.x.x
version ofsval
.
serde
: Enable support for using theserde
serialization framework for inspectingValueBag
s by implementingserde::Serialize
. Impliesstd
andserde1
.serde1
: Enable support for the stable1.x.x
version ofserde
.
test
: Add test helpers for inspecting the shape of the value inside aValueBag
.
What is a value bag?
A ValueBag
is an anonymous structured bag that supports casting, downcasting, formatting, and serializing. The goal of a ValueBag
is to decouple the producers of structured data from its consumers. A ValueBag
can always be interrogated using the consumers serialization API of choice, even if that wasn't the one the producer used to capture the data in the first place.
Say we capture an i32
using its Display
implementation as a ValueBag
:
let bag = capture_display;
That value can then be cast to a u64
:
let num = bag.as_u64.unwrap;
assert_eq!;
It could also be serialized as a number using serde
:
let num = to_value.unwrap;
assert!;
Say we derive sval::Value
on a type and capture it as a ValueBag
:
let work = Work
let bag = capture_sval1;
It could then be formatted using Display
, even though Work
never implemented that trait:
assert_eq!;
Or serialized using serde
and retain its nested structure.
The tradeoff in all this is that ValueBag
needs to depend on the serialization frameworks (sval
, serde
, and std::fmt
) that it supports, instead of just providing an API of its own for others to plug into. Doing this lets ValueBag
guarantee everything will always line up, and keep its own public API narrow. Each of these frameworks are stable though (except sval
which is 1.0.0-alpha
).