sval 1.0.0-alpha.5

A no-std, object-safe serialization framework
Documentation

sval

Build Status Latest version Documentation Latest

A lightweight, no-std, object-safe, serialization-only API for structured values with serde and std::fmt 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 data-structures 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.

Supported formats

  • JSON, the ubiquitous JavaScript Object Notation used by many HTTP APIs.

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. Implies alloc.
  • alloc: assume a global allocator is available.
  • derive: add support for #[derive(Value)].
  • serde: enable integration with major versions of serde. Some implementations of sval::Value may not be representable without the alloc feature.
    • serde1: enable integration with just the 1.x version of serde. Any future versions of serde will also receive their own feature.
  • fmt: support converting any Value into a Debug.
  • arbitrary-depth: support stateful values with any depth. Implies alloc.
  • test: add helpers for testing implementations of Value. Implies std. You should avoid using this feature outside of dev-dependencies.

How to use it

Add sval to your crate dependencies:

[dependencies.sval]
version = "1.0.0-alpha.5"

To support my data-structures

Simple struct-like data-structures can derive sval::Value:

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

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

Other data-structures 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 = "1.0.0-alpha.5"
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::v1::to_serialize(my_data);

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

let my_value = sval::serde::v1::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));

    ..
}