toml/
lib.rs

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

toml/
lib.rs
