vendor/toml/src/lib.rs

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