serde_intermediate/
lib.rs

1//! # serde-intermediate
2//! Intermediate representation for Rust's Serde serialization
3//!
4//! ---
5//!
6//! ## Table of contents
7//!
8//! 1. [Goals](#goals)
9//! 1. [Installation](#installation)
10//! 1. [Examples](#examples)
11//!
12//! ---
13//!
14//! ## Goals
15//!
16//! This crate was made to solve these particular problems:
17//!
18//! - Provide untyped (obviously "fat") runtime value representation used as exchange data ready to be deserialized on demand into typed data, for data where serializable tagged trait objects don't work on taret platforms.
19//!
20//!     Example: data stored in interpreted language runtime value.
21//!
22//! - Support for more interpreted than exact data conversion (_if it quacks like a duck, treat it like a duck_) which is default behavior, optionally force to read exact layout stored in value.
23//!
24//!     Example: more forgiving convertion between unrelated data formats.
25//!
26//! - Support for versioning (allow to produce diffs between two versions of data, that can be later patched on demand).
27//!
28//!     Example: Game assets content difference for DLC or any episodic content usage; editor UI sending only changes to the game runtime to patch what actually changed in the world (instead of sending entire serialized object state).
29//!
30//! - Support for tagged intermediate data.
31//!
32//!     Example: Game asset stores data of type that is decided at runtime (associated tag gives hint what type its layout represents).
33//!
34//! ---
35//!
36//! ## Installation
37//!
38//! 1. Core crate with most important `Intermediate` and `ReflectIntermediate` types:
39//!
40//!     ```toml
41//!     [dependencies]
42//!     serde-intermediate = "*"
43//!     ```
44//!
45//!     If you prefer to compile without `ReflectIntermediate` derive macro (`derive` feature adds derive macros and is enabled by default):
46//!
47//!     ```toml
48//!     [dependencies]
49//!     serde-intermediate = { version = "*", default-features = false }
50//!     ```
51//!
52//! 1. Crate that adds support for tagged intermediate value (to embed tagged `Intermediate` in other serializable data with `TaggedIntermediate` type):
53//!
54//!     ```toml
55//!     [dependencies]
56//!     serde-tagged-intermediate = "*"
57//!     ```
58//!
59//!     Same as with core crate, you can exclude `ReflectIntermediate` from compilation:
60//!
61//!     ```toml
62//!     [dependencies]
63//!     serde-tagged-intermediate = { version = "*", default-features = false }
64//!     ```
65//!
66//! ---
67//!
68//! ## Examples
69//!
70//! Serialize/deserialize:
71//!
72//! ```rust
73//! use std::time::SystemTime;
74//! use serde::{Serialize, Deserialize};
75//!
76//! #[derive(Debug, PartialEq, Serialize, Deserialize)]
77//! enum Login {
78//!     Email(String),
79//!     SocialMedia{
80//!         service: String,
81//!         token: String,
82//!         last_login: Option<SystemTime>,
83//!     }
84//! }
85//!
86//! #[derive(Debug, PartialEq, Serialize, Deserialize)]
87//! struct Person {
88//!     // (first name, last name)
89//!     name: (String, String),
90//!     age: usize,
91//!     login: Login,
92//! }
93//!
94//! let data = Person {
95//!     name: ("John".to_owned(), "Smith".to_owned()),
96//!     age: 40,
97//!     login: Login::Email("john.smith@gmail.com".to_owned()),
98//! };
99//! let serialized = serde_intermediate::to_intermediate(&data).unwrap();
100//! let deserialized = serde_intermediate::from_intermediate(&serialized).unwrap();
101//! assert_eq!(data, deserialized);
102//! ```
103//!
104//! More elaborate problems and solutions:
105//!
106//! 1. Versioning (diff/patch) [(test_versioning)](https://github.com/PsichiX/serde-intermediate/blob/master/core/src/tests.rs#L440)
107//! 1. Conversion between data layouts [(test_transform)](https://github.com/PsichiX/serde-intermediate/blob/master/core/src/tests.rs#L768)
108//! 1. DLC / episodic content [(test_dlcs)](https://github.com/PsichiX/serde-intermediate/blob/master/core/src/tests.rs#L870)
109//! 1. Data change communication between game and editor [(test_editor_communication)](https://github.com/PsichiX/serde-intermediate/blob/master/core/src/tests.rs#L1213)
110
111#[cfg(test)]
112mod tests;
113
114pub mod de;
115pub mod error;
116pub mod reflect;
117pub mod schema;
118pub mod ser;
119pub mod value;
120pub mod versioning;
121
122pub use crate::{
123    de::{
124        intermediate::{
125            deserialize as from_intermediate, deserialize_as as from_intermediate_as,
126            DeserializeMode,
127        },
128        object::deserialize as from_object,
129        text::{from_str, from_str_as, intermediate_from_str},
130    },
131    error::Error,
132    reflect::ReflectIntermediate,
133    schema::{SchemaIdContainer, SchemaIntermediate, SchemaPackage},
134    ser::{
135        intermediate::serialize as to_intermediate,
136        object::serialize as to_object,
137        text::{to_string, to_string_compact, to_string_pretty, TextConfig, TextConfigStyle},
138    },
139    value::{intermediate::Intermediate, object::Object},
140    versioning::*,
141};
142
143#[cfg(feature = "derive")]
144pub use serde_intermediate_derive::*;
serde_intermediate/lib.rs

serde_intermediate/
lib.rs
