]>
Commit | Line | Data |
---|---|---|
041b39d2 XL |
1 | // Copyright 2017 Serde Developers |
2 | // | |
3 | // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or | |
4 | // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license | |
5 | // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your | |
6 | // option. This file may not be copied, modified, or distributed | |
7 | // except according to those terms. | |
8 | ||
9 | //! # Serde | |
10 | //! | |
11 | //! Serde is a framework for ***ser***ializing and ***de***serializing Rust data | |
12 | //! structures efficiently and generically. | |
13 | //! | |
14 | //! The Serde ecosystem consists of data structures that know how to serialize | |
15 | //! and deserialize themselves along with data formats that know how to | |
16 | //! serialize and deserialize other things. Serde provides the layer by which | |
17 | //! these two groups interact with each other, allowing any supported data | |
18 | //! structure to be serialized and deserialized using any supported data format. | |
19 | //! | |
20 | //! See the Serde website [https://serde.rs/] for additional documentation and | |
21 | //! usage examples. | |
22 | //! | |
23 | //! [https://serde.rs/]: https://serde.rs/ | |
24 | //! | |
25 | //! ## Design | |
26 | //! | |
27 | //! Where many other languages rely on runtime reflection for serializing data, | |
28 | //! Serde is instead built on Rust's powerful trait system. A data structure | |
29 | //! that knows how to serialize and deserialize itself is one that implements | |
30 | //! Serde's `Serialize` and `Deserialize` traits (or uses Serde's derive | |
31 | //! attribute to automatically generate implementations at compile time). This | |
32 | //! avoids any overhead of reflection or runtime type information. In fact in | |
33 | //! many situations the interaction between data structure and data format can | |
34 | //! be completely optimized away by the Rust compiler, leaving Serde | |
35 | //! serialization to perform the same speed as a handwritten serializer for the | |
36 | //! specific selection of data structure and data format. | |
37 | //! | |
38 | //! ## Data formats | |
39 | //! | |
40 | //! The following is a partial list of data formats that have been implemented | |
41 | //! for Serde by the community. | |
42 | //! | |
43 | //! - [JSON], the ubiquitous JavaScript Object Notation used by many HTTP APIs. | |
44 | //! - [Bincode], a compact binary format | |
45 | //! used for IPC within the Servo rendering engine. | |
46 | //! - [CBOR], a Concise Binary Object Representation designed for small message | |
47 | //! size without the need for version negotiation. | |
48 | //! - [YAML], a popular human-friendly configuration language that ain't markup | |
49 | //! language. | |
50 | //! - [MessagePack], an efficient binary format that resembles a compact JSON. | |
51 | //! - [TOML], a minimal configuration format used by [Cargo]. | |
52 | //! - [Pickle], a format common in the Python world. | |
53 | //! - [Hjson], a variant of JSON designed to be readable and writable by humans. | |
54 | //! - [BSON], the data storage and network transfer format used by MongoDB. | |
55 | //! - [URL], the x-www-form-urlencoded format. | |
56 | //! - [XML], the flexible machine-friendly W3C standard. | |
57 | //! *(deserialization only)* | |
58 | //! - [Envy], a way to deserialize environment variables into Rust structs. | |
59 | //! *(deserialization only)* | |
60 | //! - [Redis], deserialize values from Redis when using [redis-rs]. | |
61 | //! *(deserialization only)* | |
62 | //! | |
63 | //! [JSON]: https://github.com/serde-rs/json | |
64 | //! [Bincode]: https://github.com/TyOverby/bincode | |
65 | //! [CBOR]: https://github.com/pyfisch/cbor | |
66 | //! [YAML]: https://github.com/dtolnay/serde-yaml | |
67 | //! [MessagePack]: https://github.com/3Hren/msgpack-rust | |
68 | //! [TOML]: https://github.com/alexcrichton/toml-rs | |
69 | //! [Pickle]: https://github.com/birkenfeld/serde-pickle | |
70 | //! [Hjson]: https://github.com/laktak/hjson-rust | |
71 | //! [BSON]: https://github.com/zonyitoo/bson-rs | |
72 | //! [URL]: https://github.com/nox/serde_urlencoded | |
73 | //! [XML]: https://github.com/RReverser/serde-xml-rs | |
74 | //! [Envy]: https://github.com/softprops/envy | |
75 | //! [Redis]: https://github.com/OneSignal/serde-redis | |
76 | //! [Cargo]: http://doc.crates.io/manifest.html | |
77 | //! [redis-rs]: https://crates.io/crates/redis | |
78 | ||
79 | //////////////////////////////////////////////////////////////////////////////// | |
80 | ||
81 | // Serde types in rustdoc of other crates get linked to here. | |
ea8adc8c | 82 | #![doc(html_root_url = "https://docs.rs/serde/1.0.15")] |
041b39d2 XL |
83 | |
84 | // Support using Serde without the standard library! | |
85 | #![cfg_attr(not(feature = "std"), no_std)] | |
86 | ||
87 | // Unstable functionality only if the user asks for it. For tracking and | |
88 | // discussion of these features please refer to this issue: | |
89 | // | |
90 | // https://github.com/serde-rs/serde/issues/812 | |
91 | #![cfg_attr(feature = "unstable", feature(nonzero, specialization))] | |
041b39d2 XL |
92 | #![cfg_attr(feature = "alloc", feature(alloc))] |
93 | ||
ea8adc8c XL |
94 | #![cfg_attr(feature = "cargo-clippy", deny(clippy, clippy_pedantic))] |
95 | // Whitelisted clippy lints | |
96 | #![cfg_attr(feature = "cargo-clippy", allow( | |
97 | cast_lossless, | |
98 | doc_markdown, | |
99 | linkedlist, | |
100 | type_complexity, | |
101 | unreadable_literal, | |
102 | zero_prefixed_literal, | |
103 | ))] | |
104 | // Whitelisted clippy_pedantic lints | |
105 | #![cfg_attr(feature = "cargo-clippy", allow( | |
106 | // integer and float ser/de requires these sorts of casts | |
107 | cast_possible_truncation, | |
108 | cast_possible_wrap, | |
109 | cast_precision_loss, | |
110 | cast_sign_loss, | |
111 | // simplifies some macros | |
112 | invalid_upcast_comparisons, | |
113 | // things are often more readable this way | |
114 | option_unwrap_used, | |
115 | result_unwrap_used, | |
116 | shadow_reuse, | |
117 | single_match_else, | |
118 | stutter, | |
119 | use_self, | |
120 | // not practical | |
121 | missing_docs_in_private_items, | |
122 | // alternative is not stable | |
123 | empty_enum, | |
124 | use_debug, | |
125 | ))] | |
041b39d2 XL |
126 | |
127 | // Blacklisted Rust lints. | |
128 | #![deny(missing_docs, unused_imports)] | |
129 | ||
130 | //////////////////////////////////////////////////////////////////////////////// | |
131 | ||
132 | #[cfg(feature = "alloc")] | |
133 | extern crate alloc; | |
134 | ||
135 | #[cfg(all(feature = "unstable", feature = "std"))] | |
136 | extern crate core; | |
137 | ||
138 | /// A facade around all the types we need from the `std`, `core`, and `alloc` | |
139 | /// crates. This avoids elaborate import wrangling having to happen in every | |
140 | /// module. | |
141 | mod lib { | |
142 | mod core { | |
143 | #[cfg(feature = "std")] | |
144 | pub use std::*; | |
145 | #[cfg(not(feature = "std"))] | |
146 | pub use core::*; | |
147 | } | |
148 | ||
149 | pub use self::core::{cmp, iter, mem, ops, slice, str}; | |
150 | pub use self::core::{i8, i16, i32, i64, isize}; | |
151 | pub use self::core::{u8, u16, u32, u64, usize}; | |
152 | pub use self::core::{f32, f64}; | |
153 | ||
154 | pub use self::core::cell::{Cell, RefCell}; | |
155 | pub use self::core::clone::{self, Clone}; | |
156 | pub use self::core::convert::{self, From, Into}; | |
157 | pub use self::core::default::{self, Default}; | |
158 | pub use self::core::fmt::{self, Debug, Display}; | |
159 | pub use self::core::marker::{self, PhantomData}; | |
160 | pub use self::core::option::{self, Option}; | |
161 | pub use self::core::result::{self, Result}; | |
162 | ||
163 | #[cfg(feature = "std")] | |
164 | pub use std::borrow::{Cow, ToOwned}; | |
165 | #[cfg(all(feature = "alloc", not(feature = "std")))] | |
166 | pub use alloc::borrow::{Cow, ToOwned}; | |
167 | ||
168 | #[cfg(feature = "std")] | |
169 | pub use std::string::String; | |
170 | #[cfg(all(feature = "alloc", not(feature = "std")))] | |
171 | pub use alloc::string::{String, ToString}; | |
172 | ||
173 | #[cfg(feature = "std")] | |
174 | pub use std::vec::Vec; | |
175 | #[cfg(all(feature = "alloc", not(feature = "std")))] | |
176 | pub use alloc::vec::Vec; | |
177 | ||
178 | #[cfg(feature = "std")] | |
179 | pub use std::boxed::Box; | |
180 | #[cfg(all(feature = "alloc", not(feature = "std")))] | |
181 | pub use alloc::boxed::Box; | |
182 | ||
183 | #[cfg(all(feature = "rc", feature = "std"))] | |
184 | pub use std::rc::Rc; | |
185 | #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))] | |
186 | pub use alloc::rc::Rc; | |
187 | ||
188 | #[cfg(all(feature = "rc", feature = "std"))] | |
189 | pub use std::sync::Arc; | |
190 | #[cfg(all(feature = "rc", feature = "alloc", not(feature = "std")))] | |
191 | pub use alloc::arc::Arc; | |
192 | ||
193 | #[cfg(feature = "std")] | |
194 | pub use std::collections::{BinaryHeap, BTreeMap, BTreeSet, LinkedList, VecDeque}; | |
195 | #[cfg(all(feature = "alloc", not(feature = "std")))] | |
196 | pub use alloc::{BinaryHeap, BTreeMap, BTreeSet, LinkedList, VecDeque}; | |
197 | ||
198 | #[cfg(feature = "std")] | |
199 | pub use std::{error, net}; | |
200 | ||
201 | #[cfg(feature = "std")] | |
202 | pub use std::collections::{HashMap, HashSet}; | |
203 | #[cfg(feature = "std")] | |
204 | pub use std::ffi::{CString, CStr, OsString, OsStr}; | |
205 | #[cfg(feature = "std")] | |
206 | pub use std::hash::{Hash, BuildHasher}; | |
207 | #[cfg(feature = "std")] | |
208 | pub use std::io::Write; | |
209 | #[cfg(feature = "std")] | |
210 | pub use std::path::{Path, PathBuf}; | |
211 | #[cfg(feature = "std")] | |
212 | pub use std::time::{Duration, SystemTime, UNIX_EPOCH}; | |
213 | #[cfg(feature = "std")] | |
214 | pub use std::sync::{Mutex, RwLock}; | |
215 | ||
216 | #[cfg(feature = "unstable")] | |
217 | pub use core::nonzero::{NonZero, Zeroable}; | |
218 | } | |
219 | ||
220 | //////////////////////////////////////////////////////////////////////////////// | |
221 | ||
222 | #[macro_use] | |
223 | mod macros; | |
224 | ||
225 | pub mod ser; | |
226 | pub mod de; | |
227 | ||
228 | #[doc(inline)] | |
229 | pub use ser::{Serialize, Serializer}; | |
230 | #[doc(inline)] | |
231 | pub use de::{Deserialize, Deserializer}; | |
232 | ||
233 | // Generated code uses these to support no_std. Not public API. | |
234 | #[doc(hidden)] | |
235 | pub mod export; | |
236 | ||
237 | // Helpers used by generated code and doc tests. Not public API. | |
238 | #[doc(hidden)] | |
239 | pub mod private; | |
240 | ||
241 | // Re-export #[derive(Serialize, Deserialize)]. | |
242 | // | |
243 | // This is a workaround for https://github.com/rust-lang/cargo/issues/1286. | |
244 | // Without this re-export, crates that put Serde derives behind a cfg_attr would | |
245 | // need to use some silly feature name that depends on both serde and | |
246 | // serde_derive. | |
247 | // | |
248 | // [features] | |
249 | // serde-impls = ["serde", "serde_derive"] | |
250 | // | |
251 | // [dependencies] | |
252 | // serde = { version = "1.0", optional = true } | |
253 | // serde_derive = { version = "1.0", optional = true } | |
254 | // | |
255 | // # Used like this: | |
256 | // # #[cfg(feature = "serde-impls")] | |
257 | // # #[macro_use] | |
258 | // # extern crate serde_derive; | |
259 | // # | |
260 | // # #[cfg_attr(feature = "serde-impls", derive(Serialize, Deserialize))] | |
261 | // # struct S { /* ... */ } | |
262 | // | |
263 | // The re-exported derives allow crates to use "serde" as the name of their | |
264 | // Serde feature which is more intuitive. | |
265 | // | |
266 | // [dependencies] | |
267 | // serde = { version = "1.0", optional = true, features = ["derive"] } | |
268 | // | |
269 | // # Used like this: | |
270 | // # #[cfg(feature = "serde")] | |
271 | // # #[macro_use] | |
272 | // # extern crate serde; | |
273 | // # | |
274 | // # #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] | |
275 | // # struct S { /* ... */ } | |
276 | // | |
277 | // The reason re-exporting is not enabled by default is that disabling it would | |
278 | // be annoying for crates that provide handwritten impls or data formats. They | |
279 | // would need to disable default features and then explicitly re-enable std. | |
280 | #[cfg(feature = "serde_derive")] | |
281 | #[allow(unused_imports)] | |
282 | #[macro_use] | |
283 | extern crate serde_derive; | |
284 | #[cfg(feature = "serde_derive")] | |
285 | #[doc(hidden)] | |
286 | pub use serde_derive::*; |