Skip to content
This repository has been archived by the owner on Aug 25, 2024. It is now read-only.

Commit

Permalink
docs: improve README and doc comments
Browse files Browse the repository at this point in the history
  • Loading branch information
hseeberger committed Jun 8, 2022
1 parent fadd15c commit efe7ba6
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 9 deletions.
50 changes: 47 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,53 @@
# Configured

Load configuration from three layers into any struct which can be deserialized by Serde.
Utility to load configuration from three well defined layers into any type which can be deserialized by [Serde](https://serde.rs/).

First values from the mandatory default configuration file at `<CONFIG_DIR>/default.toml` are loaded.
First, values from the mandatory default configuration file at `<CONFIG_DIR>/default.toml` are loaded.

Then, if if the environment variable `CONFIG_ENVIRONMENT` is defined, values from the environment (e.g. "prod") specific configuration file at `<CONFIG_DIR>/<CONFIG_ENVIRONMENT>.toml` are loaded as an overlay.
Then, if if the environment variable `CONFIG_ENVIRONMENT` is defined, values from the environment (e.g. "prod") specific configuration file at `<CONFIG_DIR>/<CONFIG_ENVIRONMENT>.toml` are loaded as an overlay, i.e. adding or overwriting already existing values.

Finally environment variables prefixed with `<CONFIG_ENV_PREFIX>__` and separated by `__` (double underscores are used as separators because of snake_cased keys) are used as additional overlay.

## Example

```rust
#[derive(Deserialize)]
struct Config {
foo: Foo,
qux: Qux,
}

#[derive(Deserialize)]
struct Foo {
bar: String,
baz: String,
}

#[derive(Deserialize)]
struct Qux {
quux: String,
}

#[test]
fn test_load() {
env::set_var(CONFIG_DIR, "test-config");
env::set_var(CONFIG_ENVIRONMENT, "dev");
env::set_var("APP__QUX__QUUX", "Quux2");

let config = Config::load();
assert!(config.is_ok());
let config = config.unwrap();

assert_eq!(config.foo.bar.as_str(), "Bar");
assert_eq!(config.foo.baz.as_str(), "Baz2");
assert_eq!(config.qux.quux.as_str(), "Quux2");
}
```

## Attribution

This utility is built on top of the fantastic [Config](https://crates.io/crates/config) library.

## License ##

This code is open source software licensed under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html).
14 changes: 8 additions & 6 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,15 @@ pub const CONFIG_ENVIRONMENT: &str = "CONFIG_ENVIRONMENT";
pub const CONFIG_ENV_PREFIX: &str = "CONIFG_ENV_PREFIX";

pub trait Configured: Sized {
/// Load configuration from three layers into any struct which can be deserialized by Serde.
/// Utility to load configuration from three well defined layers into any type which can be deserialized by [Serde](https://serde.rs/).
///
/// First values from the mandatory default configuration file at `<CONFIG_DIR>/default.toml`
/// are loaded. Then, if if the environment variable `CONFIG_ENVIRONMENT` is defined, values
/// from the environment (e.g. "prod") specific configuration file at
/// `<CONFIG_DIR>/<CONFIG_ENVIRONMENT>.toml` are loaded as an overlay.
/// First, values from the mandatory default configuration file at `<CONFIG_DIR>/default.toml`
/// are loaded.
///
/// Then, if if the environment variable `CONFIG_ENVIRONMENT` is defined, values from the
/// environment (e.g. "prod") specific configuration file at
/// `<CONFIG_DIR>/<CONFIG_ENVIRONMENT>.toml` are loaded as an overlay, i.e. adding or
/// overwriting already existing values.
///
/// Finally environment variables prefixed with `<CONFIG_ENV_PREFIX>__` and separated by `__`
/// (double underscores are used as separators because of snake_cased keys) are used as
Expand Down Expand Up @@ -75,7 +78,6 @@ mod tests {
env::set_var("APP__QUX__QUUX", "Quux2");

let config = Config::load();

assert!(config.is_ok());
let config = config.unwrap();

Expand Down

0 comments on commit efe7ba6

Please sign in to comment.