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.18.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.18.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.18.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    #[allow(unused_imports)]
92    pub use crate::{
93        alloc::{borrow, boxed, collections, string, vec},
94        core::{cmp, convert, fmt, hash, marker, mem, ops, option, result, str, write},
95    };
96}
97
98#[cfg(all(not(feature = "alloc"), not(feature = "std")))]
99extern crate core as std;
100
101#[cfg(feature = "derive")]
102#[doc(inline)]
103pub use sval_derive_macros::*;
104
105mod data;
106mod result;
107mod stream;
108mod value;
109
110#[doc(inline)]
111pub use self::{data::*, result::*, stream::*, value::*};
112
113/**
114A generic streaming result.
115*/
116pub type Result<T = (), E = Error> = std::result::Result<T, E>;
117
118/**
119Stream a value through a stream.
120*/
121pub fn stream<'sval>(
122    stream: &mut (impl Stream<'sval> + ?Sized),
123    value: &'sval (impl Value + ?Sized),
124) -> Result {
125    stream.value(value)
126}
127
128/**
129Stream a value through a stream with an arbitrarily short lifetime.
130*/
131pub fn stream_computed<'sval>(
132    stream: &mut (impl Stream<'sval> + ?Sized),
133    value: impl Value,
134) -> Result {
135    stream.value_computed(&value)
136}
137
138// NOTE: Tests for implementations of `Value` are in `sval_test`
139
140#[doc(hidden)]
141pub mod __private {
142    // Internal to `#[derive]` macros
143
144    pub use crate::std::{option, result};
145}
sval/lib.rs

sval/
lib.rs
