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