toml/
lib.rs

Help
1//! A [TOML]-parsing library
2//!
3//! This library implements a [TOML] v0.5.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"
12//! version = "0.4.2"
13//! authors = ["Alex Crichton <alex@alexcrichton.com>"]
14//!
15//! [dependencies]
16//! serde = "1.0"
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//!
60//! This crate supports [`serde`] 1.0 with a number of
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//! use serde_derive::Deserialize;
81//!
82//! #[derive(Deserialize)]
83//! struct Config {
84//!     ip: String,
85//!     port: Option<u16>,
86//!     keys: Keys,
87//! }
88//!
89//! #[derive(Deserialize)]
90//! struct Keys {
91//!     github: String,
92//!     travis: Option<String>,
93//! }
94//!
95//! fn main() {
96//!     let config: Config = toml::from_str(r#"
97//!         ip = '127.0.0.1'
98//!
99//!         [keys]
100//!         github = 'xxxxxxxxxxxxxxxxx'
101//!         travis = 'yyyyyyyyyyyyyyyyy'
102//!     "#).unwrap();
103//!
104//!     assert_eq!(config.ip, "127.0.0.1");
105//!     assert_eq!(config.port, None);
106//!     assert_eq!(config.keys.github, "xxxxxxxxxxxxxxxxx");
107//!     assert_eq!(config.keys.travis.as_ref().unwrap(), "yyyyyyyyyyyyyyyyy");
108//! }
109//! ```
110//!
111//! You can serialize types in a similar fashion:
112//!
113//! ```rust
114//! use serde_derive::Serialize;
115//!
116//! #[derive(Serialize)]
117//! struct Config {
118//!     ip: String,
119//!     port: Option<u16>,
120//!     keys: Keys,
121//! }
122//!
123//! #[derive(Serialize)]
124//! struct Keys {
125//!     github: String,
126//!     travis: Option<String>,
127//! }
128//!
129//! fn main() {
130//!     let config = Config {
131//!         ip: "127.0.0.1".to_string(),
132//!         port: None,
133//!         keys: Keys {
134//!             github: "xxxxxxxxxxxxxxxxx".to_string(),
135//!             travis: Some("yyyyyyyyyyyyyyyyy".to_string()),
136//!         },
137//!     };
138//!
139//!     let toml = toml::to_string(&config).unwrap();
140//! }
141//! ```
142//!
143//! [TOML]: https://github.com/toml-lang/toml
144//! [Cargo]: https://crates.io/
145//! [`serde`]: https://serde.rs/
146
147#![doc(html_root_url = "https://docs.rs/toml/0.5")]
148#![deny(missing_docs)]
149#![warn(rust_2018_idioms)]
150// Makes rustc abort compilation if there are any unsafe blocks in the crate.
151// Presence of this annotation is picked up by tools such as cargo-geiger
152// and lets them ensure that there is indeed no unsafe code as opposed to
153// something they couldn't detect (e.g. unsafe added via macro expansion, etc).
154#![forbid(unsafe_code)]
155
156pub mod map;
157pub mod value;
158#[doc(no_inline)]
159pub use crate::value::Value;
160mod datetime;
161
162pub mod ser;
163#[doc(no_inline)]
164pub use crate::ser::{to_string, to_string_pretty, to_vec, Serializer};
165pub mod de;
166#[doc(no_inline)]
167pub use crate::de::{from_slice, from_str, Deserializer};
168mod tokens;
169
170#[doc(hidden)]
171pub mod macros;
172
173mod spanned;
174pub use crate::spanned::Spanned;
toml/lib.rs

toml/
lib.rs
