docs(examples): Better organize examples

Author: epage

examples/async_source.rs

@@ -1,3 +1,5 @@
+//! Example below presents sample configuration server and client.
+
 use std::{error::Error, fmt::Debug};
 
 use async_trait::async_trait;
@@ -7,11 +9,6 @@ use config::{
 use futures::{FutureExt, select};
 use warp::Filter;
 
-// Example below presents sample configuration server and client.
-//
-// Server serves simple configuration on HTTP endpoint.
-// Client consumes it using custom HTTP AsyncSource built on top of reqwest.
-
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
     select! {
@@ -20,6 +17,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     }
 }
 
+/// Serve simple configuration on HTTP endpoint.
 async fn run_server() -> Result<(), Box<dyn Error>> {
     let service = warp::path("configuration").map(|| r#"{ "value" : 123 }"#);
 
@@ -30,6 +28,7 @@ async fn run_server() -> Result<(), Box<dyn Error>> {
     Ok(())
 }
 
+/// Consumes the server's configuration using custom HTTP AsyncSource built on top of reqwest.
 async fn run_client() -> Result<(), Box<dyn Error>> {
     // Good enough for an example to allow server to start
     tokio::time::sleep(tokio::time::Duration::from_secs(3)).await;
@@ -47,8 +46,7 @@ async fn run_client() -> Result<(), Box<dyn Error>> {
     Ok(())
 }
 
-// Actual implementation of AsyncSource can be found below
-
+/// `AsyncSource` to read configuration from an HTTP server
 #[derive(Debug)]
 struct HttpSource<F: Format> {
     uri: String,

examples/custom_file_format/main.rs

@@ -24,6 +24,7 @@ fn main() {
 
     // Deserialize the config object into your Settings struct:
     let settings: Settings = settings.try_deserialize().unwrap();
+
     println!("{settings:#?}");
 }
 
@@ -65,8 +66,7 @@ impl Format for PemFile {
     }
 }
 
-// A slice of extensions associated to this format, when an extension
-// is omitted from a file source, these will be tried implicitly:
+// When an extension is omitted from a file source, these will be tried implicitly:
 impl FileStoredFormat for PemFile {
     fn file_extensions(&self) -> &'static [&'static str] {
         &["pem"]

examples/custom_str_format.rs

@@ -2,8 +2,8 @@ use config::{Config, File, FileStoredFormat, Format, Map, Value, ValueKind};
 
 fn main() {
     let config = Config::builder()
-        .add_source(File::from_str("bad", MyFormat))
-        .add_source(File::from_str("good", MyFormat))
+        .add_source(File::from_str("bad", CustomFormat))
+        .add_source(File::from_str("good", CustomFormat))
         .build();
 
     match config {
@@ -13,9 +13,9 @@ fn main() {
 }
 
 #[derive(Debug, Clone)]
-pub struct MyFormat;
+pub struct CustomFormat;
 
-impl Format for MyFormat {
+impl Format for CustomFormat {
     fn parse(
         &self,
         uri: Option<&String>,
@@ -40,11 +40,14 @@ impl Format for MyFormat {
     }
 }
 
-// As strange as it seems for config sourced from a string, legacy demands its sacrifice
-// It is only required for File source, custom sources can use Format without caring for extensions
-static MY_FORMAT_EXT: Vec<&'static str> = vec![];
-impl FileStoredFormat for MyFormat {
+impl FileStoredFormat for CustomFormat {
     fn file_extensions(&self) -> &'static [&'static str] {
-        &MY_FORMAT_EXT
+        &NO_EXTS
     }
 }
+
+/// In-memory format doesn't have any file extensions
+///
+/// It is only required for File source,
+/// custom sources can use Format without caring for extensions
+static NO_EXTS: Vec<&'static str> = vec![];

examples/glob/conf/00-default.toml examples/glob/conf.d/00-default.tomlexamples/glob/conf/00-default.toml renamed to examples/glob/conf.d/00-default.toml

@@ -1,61 +1,17 @@
+//! Gather all conf files from conf.d/ using glob and put in 1 merge call.
+
 use std::collections::HashMap;
-use std::path::Path;
 
 use config::{Config, File};
 use glob::glob;
 
 fn main() {
-    // Option 1
-    // --------
-    // Gather all conf files from conf/ manually
-    let settings = Config::builder()
-        // File::with_name(..) is shorthand for File::from(Path::new(..))
-        .add_source(File::with_name("examples/glob/conf/00-default.toml"))
-        .add_source(File::from(Path::new("examples/glob/conf/05-some.yml")))
-        .add_source(File::from(Path::new("examples/glob/conf/99-extra.json")))
-        .build()
-        .unwrap();
-
-    // Print out our settings (as a HashMap)
-    println!(
-        "\n{:?} \n\n-----------",
-        settings
-            .try_deserialize::<HashMap<String, String>>()
-            .unwrap()
-    );
-
-    // Option 2
-    // --------
-    // Gather all conf files from conf/ manually, but put in 1 merge call.
-    let settings = Config::builder()
-        .add_source(vec![
-            File::with_name("examples/glob/conf/00-default.toml"),
-            File::from(Path::new("examples/glob/conf/05-some.yml")),
-            File::from(Path::new("examples/glob/conf/99-extra.json")),
-        ])
-        .build()
-        .unwrap();
-
-    // Print out our settings (as a HashMap)
-    println!(
-        "\n{:?} \n\n-----------",
-        settings
-            .try_deserialize::<HashMap<String, String>>()
-            .unwrap()
-    );
-
-    // Option 3
-    // --------
-    // Gather all conf files from conf/ using glob and put in 1 merge call.
-    let settings = Config::builder()
-        .add_source(
-            glob("examples/glob/conf/*")
-                .unwrap()
-                .map(|path| File::from(path.unwrap()))
-                .collect::<Vec<_>>(),
-        )
-        .build()
-        .unwrap();
+    // Glob results are sorted, ensuring user priority is preserved
+    let files = glob("examples/glob/conf.d/*")
+        .unwrap()
+        .map(|path| File::from(path.unwrap()))
+        .collect::<Vec<_>>();
+    let settings = Config::builder().add_source(files).build().unwrap();
 
     // Print out our settings (as a HashMap)
     println!(

examples/glob/conf/05-some.yml examples/glob/conf.d/05-some.ymlexamples/glob/conf/05-some.yml renamed to examples/glob/conf.d/05-some.yml

@@ -1,10 +1,84 @@
-mod settings;
+use std::env;
 
-use settings::Settings;
+use config::{Config, ConfigError, Environment, File};
+use serde::Deserialize;
 
 fn main() {
     let settings = Settings::new();
 
     // Print out our settings
     println!("{settings:?}");
 }
+
+#[derive(Debug, Deserialize)]
+#[allow(unused)]
+pub(crate) struct Settings {
+    debug: bool,
+    database: Database,
+    sparkpost: Sparkpost,
+    twitter: Twitter,
+    braintree: Braintree,
+}
+
+impl Settings {
+    pub(crate) fn new() -> Result<Self, ConfigError> {
+        let run_mode = env::var("RUN_MODE").unwrap_or_else(|_| "development".into());
+
+        let s = Config::builder()
+            // Start off by merging in the "default" configuration file
+            .add_source(File::with_name("examples/hierarchical-env/config/default"))
+            // Add in the current environment file
+            // Default to 'development' env
+            // Note that this file is _optional_
+            .add_source(
+                File::with_name(&format!("examples/hierarchical-env/config/{run_mode}"))
+                    .required(false),
+            )
+            // Add in a local configuration file
+            // This file shouldn't be checked in to git
+            .add_source(File::with_name("examples/hierarchical-env/config/local").required(false))
+            // Add in settings from the environment (with a prefix of APP)
+            // Eg.. `APP_DEBUG=1 ./target/app` would set the `debug` key
+            .add_source(Environment::with_prefix("APP"))
+            // You may also programmatically change settings
+            .set_override("database.url", "postgres://")?
+            .build()?;
+
+        // Now that we're done, let's access our configuration
+        println!("debug: {:?}", s.get_bool("debug"));
+        println!("database: {:?}", s.get::<String>("database.url"));
+
+        // You can deserialize (and thus freeze) the entire configuration as
+        s.try_deserialize()
+    }
+}
+
+#[derive(Debug, Deserialize)]
+#[allow(unused)]
+struct Database {
+    url: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[allow(unused)]
+struct Sparkpost {
+    key: String,
+    token: String,
+    url: String,
+    version: u8,
+}
+
+#[derive(Debug, Deserialize)]
+#[allow(unused)]
+struct Twitter {
+    consumer_token: String,
+    consumer_secret: String,
+}
+
+#[derive(Debug, Deserialize)]
+#[allow(unused)]
+struct Braintree {
+    merchant_id: String,
+    public_key: String,
+    private_key: String,
+}

examples/glob/conf/99-extra.json examples/glob/conf.d/99-extra.jsonexamples/glob/conf/99-extra.json renamed to examples/glob/conf.d/99-extra.json

@@ -1,24 +1,26 @@
+//! Use `confg` as a higher-level API over `std::env::var_os`
+
 use std::sync::OnceLock;
 
 use config::Config;
 
+fn main() {
+    println!("{:?}", get::<String>("foo"));
+}
+
+/// Get a configuration value from the environment
+pub fn get<'a, T: serde::Deserialize<'a>>(path: &str) -> T {
+    // You shouldn't probably do it like that and actually handle that error that might happen
+    // here, but for the sake of simplicity, we do it like this here
+    config().get::<T>(path).unwrap()
+}
+
 fn config() -> &'static Config {
     static CONFIG: OnceLock<Config> = OnceLock::new();
     CONFIG.get_or_init(|| {
         Config::builder()
-            .add_source(config::Environment::with_prefix("APP").separator("_"))
+            .add_source(config::Environment::with_prefix("APP"))
             .build()
             .unwrap()
     })
 }
-
-/// Get a configuration value from the static configuration object
-pub fn get<'a, T: serde::Deserialize<'a>>(key: &str) -> T {
-    // You shouldn't probably do it like that and actually handle that error that might happen
-    // here, but for the sake of simplicity, we do it like this here
-    config().get::<T>(key).unwrap()
-}
-
-fn main() {
-    println!("{:?}", get::<String>("foo"));
-}