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#![cfg_attr(not(feature = "default"), doc = " ```ignore")]
21#![cfg_attr(feature = "default", doc = " ```")]
22//! # use toml::value::{Datetime, Array, Table};
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//! ## Parsing TOML
35//!
36//! The easiest way to parse a TOML document is via the [`Table`] type:
37//!
38#![cfg_attr(not(feature = "default"), doc = " ```ignore")]
39#![cfg_attr(feature = "default", doc = " ```")]
40//! use toml::Table;
41//!
42//! let value = "foo = 'bar'".parse::<Table>().unwrap();
43//!
44//! assert_eq!(value["foo"].as_str(), Some("bar"));
45//! ```
46//!
47//! The [`Table`] type implements a number of convenience methods and
48//! traits; the example above uses [`FromStr`] to parse a [`str`] into a
49//! [`Table`].
50//!
51//! ## Deserialization and Serialization
52//!
53//! This crate supports [`serde`] 1.0 with a number of
54//! implementations of the `Deserialize`, `Serialize`, `Deserializer`, and
55//! `Serializer` traits. Namely, you'll find:
56//!
57//! * `Deserialize for Table`
58//! * `Serialize for Table`
59//! * `Deserialize for Value`
60//! * `Serialize for Value`
61//! * `Deserialize for Datetime`
62//! * `Serialize for Datetime`
63//! * `Deserializer for de::Deserializer`
64//! * `Serializer for ser::Serializer`
65//! * `Deserializer for Table`
66//! * `Deserializer for Value`
67//!
68//! This means that you can use Serde to deserialize/serialize the
69//! [`Table`] type as well as [`Value`] and [`Datetime`] type in this crate. You can also
70//! use the [`Deserializer`], [`Serializer`], or [`Table`] type itself to act as
71//! a deserializer/serializer for arbitrary types.
72//!
73//! An example of deserializing with TOML is:
74//!
75#![cfg_attr(not(feature = "default"), doc = " ```ignore")]
76#![cfg_attr(feature = "default", doc = " ```")]
77//! use serde::Deserialize;
78//!
79//! #[derive(Deserialize)]
80//! struct Config {
81//! ip: String,
82//! port: Option<u16>,
83//! keys: Keys,
84//! }
85//!
86//! #[derive(Deserialize)]
87//! struct Keys {
88//! github: String,
89//! travis: Option<String>,
90//! }
91//!
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//! You can serialize types in a similar fashion:
107//!
108#![cfg_attr(not(feature = "default"), doc = " ```ignore")]
109#![cfg_attr(feature = "default", doc = " ```")]
110//! use serde::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//! let config = Config {
126//! ip: "127.0.0.1".to_string(),
127//! port: None,
128//! keys: Keys {
129//! github: "xxxxxxxxxxxxxxxxx".to_string(),
130//! travis: Some("yyyyyyyyyyyyyyyyy".to_string()),
131//! },
132//! };
133//!
134//! let toml = toml::to_string(&config).unwrap();
135//! ```
136//!
137//! [TOML]: https://github.com/toml-lang/toml
138//! [Cargo]: https://crates.io/
139//! [`serde`]: https://serde.rs/
140//! [serde]: https://serde.rs/
141
142#![cfg_attr(docsrs, feature(doc_auto_cfg))]
143#![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
144#![warn(clippy::std_instead_of_core)]
145#![warn(clippy::std_instead_of_alloc)]
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#![warn(missing_docs)]
152#![warn(clippy::print_stderr)]
153#![warn(clippy::print_stdout)]
154
155#[allow(unused_extern_crates)]
156extern crate alloc;
157
158pub(crate) mod alloc_prelude {
159 pub(crate) use alloc::borrow::ToOwned as _;
160 pub(crate) use alloc::format;
161 pub(crate) use alloc::string::String;
162 pub(crate) use alloc::string::ToString as _;
163 pub(crate) use alloc::vec::Vec;
164}
165
166pub mod map;
167#[cfg(feature = "serde")]
168pub mod value;
169
170pub mod de;
171#[cfg(feature = "serde")]
172pub mod ser;
173
174#[doc(hidden)]
175#[cfg(feature = "serde")]
176pub mod macros;
177
178#[cfg(feature = "serde")]
179mod table;
180
181#[doc(inline)]
182#[cfg(feature = "parse")]
183#[cfg(feature = "serde")]
184pub use crate::de::{from_slice, from_str, Deserializer};
185#[doc(inline)]
186#[cfg(feature = "display")]
187#[cfg(feature = "serde")]
188pub use crate::ser::{to_string, to_string_pretty, Serializer};
189#[doc(inline)]
190#[cfg(feature = "serde")]
191pub use crate::value::Value;
192pub use serde_spanned::Spanned;
193#[cfg(feature = "serde")]
194pub use table::Table;
195
196// Shortcuts for the module doc-comment
197#[allow(unused_imports)]
198use core::str::FromStr;
199#[allow(unused_imports)]
200use toml_datetime::Datetime;
201
202#[doc = include_str!("../README.md")]
203#[cfg(doctest)]
204pub struct ReadmeDoctests;