sval/
lib.rs

1/*!
2Structured, streaming values.
3
4`sval` is a serialization framework that treats data as a flat stream of tokens.
5The source of that data could be some Rust object or parsed from some encoding.
6It's well suited to self-describing, text-based formats like JSON.
7
8# Getting started
9
10For a complete introduction, see [the project readme](https://github.com/sval-rs/sval).
11
12Add `sval` to your `Cargo.toml`:
13
14```toml
15[dependencies.sval]
16version = "2.16.0"
17```
18
19By default, `sval` doesn't depend on Rust's standard library or integrate with its collection types.
20To include them, add the `alloc` or `std` Cargo features:
21
22```toml
23[dependencies.sval]
24version = "2.16.0"
25features = ["std"]
26```
27
28`sval` provides procedural macros for deriving its traits.
29Add the `derive` Cargo feature to enable them:
30
31```toml
32[dependencies.sval]
33version = "2.16.0"
34features = ["derive"]
35```
36
37# The `Value` trait
38
39[`Value`] is a trait for data types to implement that surfaces their structure through visitors called _streams_.
40`Value` is like `serde`'s `Serialize`. It can also be used like `serde`'s `Deserialize`.
41
42Many standard types in Rust implement the `Value` trait. It can be derived on your own types using the `sval_derive` library.
43
44# The `Stream` trait
45
46[`Stream`] is a trait for data formats and visitors to implement that observes the structure of _values_.
47`Stream` is like `serde`'s `Serializer`. It can also be used like `serde`'s `Deserializer`.
48
49# Data-model
50
51`sval`'s data-model is defined by the [`Stream`] trait. It includes:
52
53- Null
54- Booleans (`true`, `false`)
55- Text blobs
56- Binary blobs
57- Integers (`u8`-`u128`, `i8`-`i128`)
58- Binary floating points (`f32`-`f64`)
59- Sequences
60- Maps
61- Tags
62- Tagged values
63- Records
64- Tuples
65- Enums
66
67# Tags
68
69[`Tag`] is a type for extending `sval`'s data-model with new kinds of values.
70Rust's own `()` and `Option<T>` types are expressed as tags.
71Other examples of tags include text that encodes RFC3339 timestamps or RFC4122 UUIDs.
72
73The [`tags`] module contains built-in tags.
74Other libraries may define their own tags too.
75*/
76
77#![doc(html_logo_url = "https://raw.githubusercontent.com/sval-rs/sval/main/asset/logo.svg")]
78#![no_std]
79#![deny(missing_docs)]
80
81#[cfg(feature = "std")]
82extern crate std;
83
84#[cfg(all(feature = "alloc", not(feature = "std")))]
85extern crate alloc;
86#[cfg(all(feature = "alloc", not(feature = "std")))]
87extern crate core;
88
89#[cfg(all(feature = "alloc", not(feature = "std")))]
90mod std {
91    pub use crate::{
92        alloc::{borrow, boxed, collections, string, vec},
93        core::{cmp, convert, fmt, hash, marker, mem, ops, result, str, write},
94    };
95}
96
97#[cfg(all(not(feature = "alloc"), not(feature = "std")))]
98extern crate core as std;
99
100#[cfg(feature = "derive")]
101#[doc(inline)]
102pub use sval_derive_macros::*;
103
104mod data;
105mod result;
106mod stream;
107mod value;
108
109#[doc(inline)]
110pub use self::{data::*, result::*, stream::*, value::*};
111
112/**
113A generic streaming result.
114*/
115pub type Result<T = (), E = Error> = std::result::Result<T, E>;
116
117/**
118Stream a value through a stream.
119*/
120pub fn stream<'sval>(
121    stream: &mut (impl Stream<'sval> + ?Sized),
122    value: &'sval (impl Value + ?Sized),
123) -> Result {
124    stream.value(value)
125}
126
127/**
128Stream a value through a stream with an arbitrarily short lifetime.
129*/
130pub fn stream_computed<'sval>(
131    stream: &mut (impl Stream<'sval> + ?Sized),
132    value: impl Value,
133) -> Result {
134    stream.value_computed(&value)
135}
136
137// NOTE: Tests for implementations of `Value` are in `sval_test`
sval/lib.rs

sval/
lib.rs
