src/vendor/toml-0.3.2/src/lib.rs

   1 //! A [TOML]-parsing library
   2 //!
   3 //! [TOML]: https://github.com/toml-lang/toml
   4 //!
   5 //! This library implements a [TOML] v0.4.0 compatible parser,
   6 //! primarily supporting the [`serde`] library for encoding/decoding
   7 //! various types in Rust.
   8 //!
   9 //! TOML itself is a simple, ergonomic, and readable configuration format:
  10 //!
  11 //! ```toml
  12 //! [package]
  13 //! name = "toml"
  14 //! version = "0.2.1"
  15 //! authors = ["Alex Crichton <alex@alexcrichton.com>"]
  16 //!
  17 //! [dependencies]
  18 //! serde = "0.9"
  19 //! ```
  20 //!
  21 //! The TOML format tends to be relatively common throughout the Rust community
  22 //! for configuration, notably being used by [Cargo], Rust's package manager.
  23 //!
  24 //! ## TOML values
  25 //!
  26 //! A value in TOML is represented with the `Value` enum in this crate:
  27 //!
  28 //! ```rust,ignore
  29 //! pub enum Value {
  30 //!     String(String),
  31 //!     Integer(i64),
  32 //!     Float(f64),
  33 //!     Boolean(bool),
  34 //!     Datetime(Datetime),
  35 //!     Array(Array),
  36 //!     Table(Table),
  37 //! }
  38 //! ```
  39 //!
  40 //! TOML is similar to JSON with the notable addition of a `Datetime`
  41 //! type. In general, TOML and JSON are interchangeable in terms of
  42 //! formats.
  43 //!
  44 //! ## Parsing TOML
  45 //!
  46 //! The easiest way to parse a TOML document is via the `Value` type:
  47 //!
  48 //! ```rust
  49 //! use toml::Value;
  50 //!
  51 //! let value = "foo = 'bar'".parse::<Value>().unwrap();
  52 //!
  53 //! assert_eq!(value["foo"].as_str(), Some("bar"));
  54 //! ```
  55 //!
  56 //! The `Value` type implements a number of convenience methods and
  57 //! traits; the example above uses `FromStr` to parse a `str` into a
  58 //! `Value`.
  59 //!
  60 //! ## Deserialization and Serialization
  61 //!
  62 //! This crate supports [`serde`] 0.9 with a number of
  63 //! implementations of the `Deserialize`, `Serialize`, `Deserializer`, and
  64 //! `Serializer` traits. Namely, you'll find:
  65 //!
  66 //! * `Deserialize for Value`
  67 //! * `Serialize for Value`
  68 //! * `Deserialize for Datetime`
  69 //! * `Serialize for Datetime`
  70 //! * `Deserializer for de::Deserializer`
  71 //! * `Serializer for ser::Serializer`
  72 //! * `Deserializer for Value`
  73 //!
  74 //! This means that you can use Serde to deserialize/serialize the
  75 //! `Value` type as well as the `Datetime` type in this crate. You can also
  76 //! use the `Deserializer`, `Serializer`, or `Value` type itself to act as
  77 //! a deserializer/serializer for arbitrary types.
  78 //!
  79 //! An example of deserializing with TOML is:
  80 //!
  81 //! ```rust
  82 //! #[macro_use]
  83 //! extern crate serde_derive;
  84 //! extern crate toml;
  85 //!
  86 //! #[derive(Deserialize)]
  87 //! struct Config {
  88 //!     ip: String,
  89 //!     port: Option<u16>,
  90 //!     keys: Keys,
  91 //! }
  92 //!
  93 //! #[derive(Deserialize)]
  94 //! struct Keys {
  95 //!     github: String,
  96 //!     travis: Option<String>,
  97 //! }
  98 //!
  99 //! fn main() {
 100 //!     let config: Config = toml::from_str(r#"
 101 //!         ip = '127.0.0.1'
 102 //!
 103 //!         [keys]
 104 //!         github = 'xxxxxxxxxxxxxxxxx'
 105 //!         travis = 'yyyyyyyyyyyyyyyyy'
 106 //!     "#).unwrap();
 107 //!
 108 //!     assert_eq!(config.ip, "127.0.0.1");
 109 //!     assert_eq!(config.port, None);
 110 //!     assert_eq!(config.keys.github, "xxxxxxxxxxxxxxxxx");
 111 //!     assert_eq!(config.keys.travis.as_ref().unwrap(), "yyyyyyyyyyyyyyyyy");
 112 //! }
 113 //! ```
 114 //!
 115 //! You can serialize types in a similar fashion:
 116 //!
 117 //! ```rust
 118 //! #[macro_use]
 119 //! extern crate serde_derive;
 120 //! extern crate toml;
 121 //!
 122 //! #[derive(Serialize)]
 123 //! struct Config {
 124 //!     ip: String,
 125 //!     port: Option<u16>,
 126 //!     keys: Keys,
 127 //! }
 128 //!
 129 //! #[derive(Serialize)]
 130 //! struct Keys {
 131 //!     github: String,
 132 //!     travis: Option<String>,
 133 //! }
 134 //!
 135 //! fn main() {
 136 //!     let config = Config {
 137 //!         ip: "127.0.0.1".to_string(),
 138 //!         port: None,
 139 //!         keys: Keys {
 140 //!             github: "xxxxxxxxxxxxxxxxx".to_string(),
 141 //!             travis: Some("yyyyyyyyyyyyyyyyy".to_string()),
 142 //!         },
 143 //!     };
 144 //!
 145 //!     let toml = toml::to_string(&config).unwrap();
 146 //! }
 147 //! ```
 148 //!
 149 //! [Cargo]: https://crates.io/
 150 //! [`serde`]: https://serde.rs/
 151
 152 #![doc(html_root_url = "https://docs.rs/toml/0.3")]
 153 #![deny(missing_docs)]
 154
 155 #[macro_use]
 156 extern crate serde;
 157
 158 pub mod value;
 159 mod datetime;
 160 #[doc(no_inline)]
 161 pub use value::Value;
 162
 163 pub mod ser;
 164 #[doc(no_inline)]
 165 pub use ser::{to_string, to_vec, Serializer};
 166 pub mod de;
 167 #[doc(no_inline)]
 168 pub use de::{from_slice, from_str, Deserializer};
 169 mod tokens;