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 <alex@alexcrichton.com>"]
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
152pub mod map;
153pub mod value;
154#[doc(no_inline)]
155pub use crate::value::Value;
156mod datetime;
157
158pub mod ser;
159#[doc(no_inline)]
160pub use crate::ser::{to_string, to_string_pretty, to_vec, Serializer};
161pub mod de;
162#[doc(no_inline)]
163pub use crate::de::{from_slice, from_str, Deserializer};
164mod tokens;
165
166#[doc(hidden)]
167pub mod macros;
168
169mod spanned;
170pub use crate::spanned::Spanned;
171
172// Just for rustdoc
173#[allow(unused_imports)]
174use crate::datetime::Datetime;
175#[allow(unused_imports)]
176use core::str::FromStr;
177