sval 0.2.0

A no-std, object-safe serialization framework
Documentation

sval

Build Status Latest version Documentation Latest Documentation Master

A lightweight, no-std, object-safe, serialization-only API for structured values with serde support.

Producers of structured values use the value module. Consumers of structured values use the stream module. sval offers a json-like data model, which is more limiting than serde's, but capable enough to represent Rust datastructures in one form or another.

This library is designed to plug a no-std-object-safe sized hole in Rust's current serialization ecosystem. The driving use-case is structured logging, where individual events are typically small, and there's no complete schema that can tie values in any one event to values in another.

sval_json and sval_derive are mostly pilfered from dtolnay's excellent miniserde project.

Minimum rustc

This library requires Rust 1.31.0.

See also

Cargo features

sval has the following optional features that can be enabled in your Cargo.toml:

  • std: assume std is available and add support for std types.
  • derive: add support for #[derive(Value)].
  • serde: enable integration with serde.
  • fmt: support converting any Value into a Debug.
  • arbitrary-depth: support stateful values with any depth.
  • test: add helpers for testing implementations of Value.

How to use it

Add sval to your crate dependencies:

[dependencies.sval]
version = "0.2.0"

To support my datastructures

Simple struct-like datastructures can derive sval::Value:

[dependencies.sval]
features = ["derive"]
#[macro_use]
extern crate sval;

#[derive(Value)]
struct MyData {
    id: u64,
    name: String,
}

Other datastructures can implement sval::Value manually:

use sval::value::{self, Value};

struct MyId(u64);

impl Value for MyId {
    fn stream(&self, stream: &mut value::Stream) -> value::Result {
        stream.u64(self.0)
    }
}

To format my data

The sval_json crate can format any sval::Value as json:

[dependencies.sval_json]
version = "0.2.0"
features = ["std"]
let my_json = sval_json::to_string(my_data)?;

To integrate with serde

sval has out-of-the-box serde integration between sval::Values and serde::Serializes. Add the serde feature to sval to enable it:

[dependencies.sval]
features = ["serde"]

Use the to_serialize function to turn any sval::Value into a serde::Serialize:

let my_serialize = sval::serde::to_serialize(my_data);

Use the to_value function to turn any serde::Serialize into a sval::Value:

let my_value = sval::serde::to_value(my_data);

When the serde feature is available, structures that already derive Serialize can also always derive Value. The Value implementation will behave the same as Serialize:

#[derive(Serialize, Value)]
#[sval(derive_from = "serde")]
struct MyData {
    id: u64,
    name: String,
    #[serde(flatten)]
    props: serde_json::Map<String, serde_json::Value>,
}

To integrate with std::fmt

sval can provide a compatible Debug implementation for any sval::Value. Add the fmt feature to sval to enable it:

[dependencies.sval]
features = ["fmt"]

Use the to_debug function to turn any sval::Value into a std::fmt::Debug:

fn with_value(value: impl Value) {
    dbg!(sval::fmt::to_debug(&value));

    ..
}