From 4b9519d20788f9da6b82a94e036cae7c77cb4798 Mon Sep 17 00:00:00 2001 From: Ryan Leckey Date: Mon, 30 Jan 2017 14:56:49 -0800 Subject: :shirt: --- src/lib.rs | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) (limited to 'src/lib.rs') diff --git a/src/lib.rs b/src/lib.rs index 9cb8f82..3d72620 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,6 +2,52 @@ #![allow(unknown_lints)] +//! Configuration is gathered by building a `Source` and then merging that source into the +//! current state of the configuration. +//! +//! ```rust +//! fn main() { +//! // Add environment variables that begin with RUST_ +//! config::merge(config::Environment::new("RUST")); +//! +//! // Add 'Settings.json' +//! config::merge(config::File::new("Settings", config::FileFormat::Json)); +//! +//! // Add 'Settings.$(RUST_ENV).json` +//! let name = format!("Settings.{}", config::get_str("env").unwrap()); +//! config::merge(config::File::new(&name, config::FileFormat::Json)); +//! } +//! ``` +//! +//! Note that in the above example the calls to `config::merge` could have +//! been re-ordered to influence the priority as each successive merge +//! is evaluated on top of the previous. +//! +//! Configuration values can be retrieved with a call to `config::get` and then +//! coerced into a type with `as_*`. +//! +//! ```toml +//! # Settings.toml +//! debug = 1 +//! ``` +//! +//! ```rust +//! fn main() { +//! // Add 'Settings.toml' (from above) +//! config::merge(config::File::new("Settings", config::FileFormat::Toml)); +//! +//! // Get 'debug' and coerce to a boolean +//! assert_eq!(config::get("debug").unwrap().as_bool(), Some(true)); +//! +//! // You can use a type suffix on `config::get` to simplify +//! assert_eq!(config::get_bool("debug"), Some(true)); +//! assert_eq!(config::get_str("debug"), Some("true")); +//! } +//! ``` +//! +//! See the [examples](https://github.com/mehcode/config-rs/tree/master/examples) for +//! more usage information. + #[cfg(feature = "toml")] extern crate toml; -- cgit v1.2.3