Debian Codegraph @

.cargo/vendor/toml/src/lib.rs

raw
1 //! A [serde]-compatible [TOML]-parsing library
2 //!
3 //! TOML itself is a simple, ergonomic, and readable configuration format:
4 //!
5 //! ```toml
6 //! [package]
7 //! name = "toml"
8 //! version = "0.4.2"
9 //! authors = ["Alex Crichton <[email protected]>"]
10 //!
11 //! [dependencies]
12 //! serde = "1.0"
13 //! ```
14 //!
15 //! The TOML format tends to be relatively common throughout the Rust community
16 //! for configuration, notably being used by [Cargo], Rust's package manager.
17 //!
18 //! ## TOML values
19 //!
20 //! A value in TOML is represented with the [`Value`] enum in this crate:
21 //!
22 //! ```rust,ignore
23 //! pub enum Value {
24 //! String(String),
25 //! Integer(i64),
26 //! Float(f64),
27 //! Boolean(bool),
28 //! Datetime(Datetime),
29 //! Array(Array),
30 //! Table(Table),
31 //! }
32 //! ```
33 //!
34 //! TOML is similar to JSON with the notable addition of a [`Datetime`]
35 //! type. In general, TOML and JSON are interchangeable in terms of
36 //! formats.
37 //!
38 //! ## Parsing TOML
39 //!
40 //! The easiest way to parse a TOML document is via the [`Value`] type:
41 //!
42 //! ```rust
43 //! use toml::Value;
44 //!
45 //! let value = "foo = 'bar'".parse::<Value>().unwrap();
46 //!
47 //! assert_eq!(value["foo"].as_str(), Some("bar"));
48 //! ```
49 //!
50 //! The [`Value`] type implements a number of convenience methods and
51 //! traits; the example above uses [`FromStr`] to parse a [`str`] into a
52 //! [`Value`].
53 //!
54 //! ## Deserialization and Serialization
55 //!
56 //! This crate supports [`serde`] 1.0 with a number of
57 //! implementations of the `Deserialize`, `Serialize`, `Deserializer`, and
58 //! `Serializer` traits. Namely, you'll find:
59 //!
60 //! * `Deserialize for Value`
61 //! * `Serialize for Value`
62 //! * `Deserialize for Datetime`
63 //! * `Serialize for Datetime`
64 //! * `Deserializer for de::Deserializer`
65 //! * `Serializer for ser::Serializer`
66 //! * `Deserializer for Value`
67 //!
68 //! This means that you can use Serde to deserialize/serialize the
69 //! [`Value`] type as well as the [`Datetime`] type in this crate. You can also
70 //! use the [`Deserializer`], [`Serializer`], or [`Value`] type itself to act as
71 //! a deserializer/serializer for arbitrary types.
72 //!
73 //! An example of deserializing with TOML is:
74 //!
75 //! ```rust
76 //! use serde_derive::Deserialize;
77 //!
78 //! #[derive(Deserialize)]
79 //! struct Config {
80 //! ip: String,
81 //! port: Option<u16>,
82 //! keys: Keys,
83 //! }
84 //!
85 //! #[derive(Deserialize)]
86 //! struct Keys {
87 //! github: String,
88 //! travis: Option<String>,
89 //! }
90 //!
91 //! fn main() {
92 //! let config: Config = toml::from_str(r#"
93 //! ip = '127.0.0.1'
94 //!
95 //! [keys]
96 //! github = 'xxxxxxxxxxxxxxxxx'
97 //! travis = 'yyyyyyyyyyyyyyyyy'
98 //! "#).unwrap();
99 //!
100 //! assert_eq!(config.ip, "127.0.0.1");
101 //! assert_eq!(config.port, None);
102 //! assert_eq!(config.keys.github, "xxxxxxxxxxxxxxxxx");
103 //! assert_eq!(config.keys.travis.as_ref().unwrap(), "yyyyyyyyyyyyyyyyy");
104 //! }
105 //! ```
106 //!
107 //! You can serialize types in a similar fashion:
108 //!
109 //! ```rust
110 //! use serde_derive::Serialize;
111 //!
112 //! #[derive(Serialize)]
113 //! struct Config {
114 //! ip: String,
115 //! port: Option<u16>,
116 //! keys: Keys,
117 //! }
118 //!
119 //! #[derive(Serialize)]
120 //! struct Keys {
121 //! github: String,
122 //! travis: Option<String>,
123 //! }
124 //!
125 //! fn main() {
126 //! let config = Config {
127 //! ip: "127.0.0.1".to_string(),
128 //! port: None,
129 //! keys: Keys {
130 //! github: "xxxxxxxxxxxxxxxxx".to_string(),
131 //! travis: Some("yyyyyyyyyyyyyyyyy".to_string()),
132 //! },
133 //! };
134 //!
135 //! let toml = toml::to_string(&config).unwrap();
136 //! }
137 //! ```
138 //!
139 //! [TOML]: https://github.com/toml-lang/toml
140 //! [Cargo]: https://crates.io/
141 //! [`serde`]: https://serde.rs/
142 //! [serde]: https://serde.rs/
143
144 #![deny(missing_docs)]
145 #![warn(rust_2018_idioms)]
146 // Makes rustc abort compilation if there are any unsafe blocks in the crate.
147 // Presence of this annotation is picked up by tools such as cargo-geiger
148 // and lets them ensure that there is indeed no unsafe code as opposed to
149 // something they couldn't detect (e.g. unsafe added via macro expansion, etc).
150 #![forbid(unsafe_code)]
151
152 pub mod map;
153 pub mod value;
154 #[doc(no_inline)]
155 pub use crate::value::Value;
156 mod datetime;
157
158 pub mod ser;
159 #[doc(no_inline)]
160 pub use crate::ser::{to_string, to_string_pretty, to_vec, Serializer};
161 pub mod de;
162 #[doc(no_inline)]
163 pub use crate::de::{from_slice, from_str, Deserializer};
164 mod tokens;
165
166 #[doc(hidden)]
167 pub mod macros;
168
169 mod spanned;
170 pub use crate::spanned::Spanned;
171
172 // Just for rustdoc
173 #[allow(unused_imports)]
174 use crate::datetime::Datetime;
175 #[allow(unused_imports)]
176 use core::str::FromStr;