[−][src]Crate sval
A small, no-std, object-safe, serialization-only framework.
The sval
API is built around two key traits:
Value
is a trait for data with a streamable structure. It's likeserde::Serialize
.Stream
is a trait for receiving the structure of a value. It's likeserde::Serializer
.
Getting started
Add sval
to your Cargo.toml
:
[dependencies.sval]
version = "0.4.5"
Supported formats
- JSON, the ubiquitous JavaScript Object Notation used by many HTTP APIs.
Streaming values
The structure of a Value
can be streamed to a Stream
.
in a single call
For simple use-cases, use the stream
function to stream the structure of a value:
sval::stream(MyStream, 42)?;
where 42
is a Value
and MyStream
is a Stream
.
over multiple calls
More involved use-cases may want to build up structure over time. Use a stream::OwnedStream
to hang on to a stream and pass it values over time:
use sval::{ Value, stream::{self, OwnedStream}, }; // We begin the wrapper over `MyStream` let mut stream = StreamPairs::new()?; // Pairs can be streamed independently stream.pair("a", 42)?; stream.pair("b", 17)?; // Eventually we end the wrapper and return the underlying `MyStream` let my_stream = stream.end()?; struct StreamPairs { // Using `OwnedStream<MyStream>` instead of just `MyStream` // gives us better ergonomics and validation stream: OwnedStream<MyStream>, } impl StreamPairs { fn new() -> Result<Self, stream::Error> { let mut stream = OwnedStream::new(MyStream); stream.map_begin(None)?; Ok(StreamPairs { stream, }) } fn pair(&mut self, k: impl Value, v: impl Value) -> Result<(), stream::Error> { self.stream.map_key(k)?; self.stream.map_value(v)?; Ok(()) } fn end(mut self) -> Result<MyStream, stream::Error> { self.stream.map_end()?; Ok(self.stream.into_inner()) } }
The above example captures an OwnedStream<MyStream>
and then allows multiple key-value pairs to be
streamed through it before finishing.
serde
integration
Use the serde
Cargo feature to enable integration with serde
:
[dependencies.sval]
features = ["serde"]
When serde
is available, the Value
trait can also be derived
based on an existing Serialize
implementation:
use sval::Value; #[derive(Serialize, Value)] #[sval(derive_from = "serde")] pub enum Data { Variant(i32, String), }
In no-std environments, serde
support can be enabled using the serde_no_std
feature
instead:
[dependencies.sval]
features = ["serde_no_std"]
std::fmt
integration
Use the fmt
Cargo feature to enable extended integration with std::fmt
:
[dependencies.sval]
features = ["fmt"]
When fmt
is available, arbitrary Value
s can be treated like std::fmt::Debug
:
fn with_value(value: impl sval::Value) { dbg!(sval::fmt::to_debug(&value)); // Do something with the value }
Re-exports
pub use self::stream::Stream; |
pub use self::value::Value; |
Modules
fmt | Integration between |
serde | Integration between |
stream | A stream for datastructures. |
test | Helpers for testing value implementations. |
value | A streamable value. |
Structs
Error | An error encountered while visiting a value. |
Functions
stream |