# manaconf

## A library for creating a layered configuration provider

This library gives you the ability to setup to read configuration to read from
multiple sources, and pull values from these sources via a key.

Inspired by dotnetcore configuration system. (Though this is no where near as deep)

```rust

// create our config to read configuration values from environment variables
// with the prefix MYAPP
let config = Builder::new()
    .with_source(sources::EnvVarSource::with_prefix("MYAPP"))
    .build();

// Read our config data in
let config_data: ConfigData = config.bind()?;

struct ConfigData {
    important_value: String,
    optional_value: Option<i32>
}

impl TryFromValueRead for ConfigData {
    fn try_from<R>(read: &R) -> Result<Self, TryFromValueReadError> {
        // As our config is set to read from the environment varibles only
        // the EnvVarSource will turn this key into `MYAPP_IMPORTANT` due
        // to the prefix set above and the key being requested here
        let important_value: String = read.get_expected_value("important")?;
        
        // and this one will be turned into `MYAPP_OPTIONAL`
        let optional_value: Option<i32> = read.get_value("optional")?;

        ConfigData {
            important_value,
            optional_value
        }
    }
}

```
# Keys

Keys are a heirachy represented as a string, i.e. `section::subsection::value`, 
which can be used to drill down into configurations that may have an arbitary 
depth of value organization.

Different sources may interpret this heirachy in different ways. For example
the `EnvVarSource` will just turn this into an uppercased string, where the
seperators are replaced with underscores. (`SECTION_SUBSECTION_VALUE`).

But a json source might use this as a way to drill down into sub objects.

# Sections

You can call the `section` method on both `Config` and `Section` types to create
a `section`. As section is simply a pre-applied prefix to your key.

Useful when some code would not or should not be aware of the parent heirachy.

For example, if we took our type above, but in fact our values `important` and
`optional` actually didn't sit at the root but was instead at `some::subsection`
we can use `Section` to give that code access to values as if the `Section`'s 
prefix was the root.

```rust
let section = config.section("some::subsection");
let config_data: ConfigData = section.bind();

// Even though ConfigData only asks for `important` and `optional` due to the
// `Section`, the actual keys being looked up is `some::subsection::important` and
// `some::subsection::optional`.
```

# Multiple sources

You can configure multiple sources by calling `Builder::add_source` or 
`Builder::add_source_with_prefix` when building your `Config`.

The order you add your sources is the priority of the sources. The first source
being the highest priority.

manaconf will check through each source in order when looking up a value, and 
return the first value or error it encounters. If no value is returned by any
source then a `None` is returned.

This allows you to configure sources such that you allow one source to override
another.

# TODO

* More sources

  At current there's only `EnvVarSource` for pulling values from environment
  variables and `CommandLineSource` for pulling from a simplified command line
  parameter scheme.

  However I'd like to provide much more than that. Such as toml/json/yml files, 
  .env files and the like.
  
  However, I'm thinking it'd be best to implement other sources as crates.

* Derive macro

  It'd be nice if `TryFromValueRead` could be implemented as a derive macro,
  though I've not looked into how to do this yet.

* Async support

  Might be worth having async support for reading from sources

* ???
  
  We'll see what else falls out with usage