twelf 0.1.1

Twelf is a configuration solution for Rust including 12-Factor support. It is designed with layers in order to configure different sources and formats to build your configuration. The main goal is to be very simple using a proc macro.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

# Twelf

Twelf is a configuration solution for Rust including 12-Factor support. It is designed with `Layer`s in order to configure different sources and formats to build your configuration. The main goal is to be very simple using the proc macro `twelf::config`. For now it supports : 

+ Default settings (inside your codebase with `#[serde(default = ...)]` coming from [serde](https://serde.rs))
+ Reading from `TOML`, `YAML`, `JSON`, `DHALL`, `INI` files
+ Reading from environment variables: it supports `HashMap` structure with `MY_VARIABLE="mykey=myvalue,mykey2=myvalue2"` and also array like `MY_VARIABLE=first,second` thanks to [envy](https://github.com/softprops/envy).
+ All [serde](https://serde.rs) attributes can be used in your struct to customize your configuration as you wish
+ Reading your configuration from your command line built with [clap](https://github.com/clap-rs/clap)

# Usage 

## Simple with JSON and environment variables

```rust
use twelf::config;

#[config]
struct TestCfg {
    test: String,
    another: usize,
}

// Init configuration with layers, each layers override only existing fields
let config = TestCfg::with_layers(&[
    Layer::Json("conf.json".into()),
    Layer::Env(Some("PREFIX_"))
]).unwrap();
```

## Example with clap support

```rust
use twelf::config;

#[config]
struct TestCfg {
    /// Here is an example of documentation which is displayed in clap
    test: String,
    another: usize,
}

// Will generate global arguments for each of your fields inside your configuration struct
let app = clap::App::new("test").args(&Conf::clap_args());

// Init configuration with layers, each layers override only existing fields
let config = TestCfg::with_layers(&[
    Layer::Json("conf.json".into()),
    Layer::Env(Some("PREFIX_")),
    Layer::Clap(app.get_matches().clone())
]).unwrap();

// ... your application code
```

## Use features to improve compile time

If you don't want to include useless crates if you just use 2 of all available layers you can use features without default-features, example if you use only yaml and env layer.

```toml
[dependencies]
twelf = { version = "0.1", default-features = false, features = ["yaml"] }
```

# TODO:
+ Write an example with env + files
+ Write an example with default + env
+ Write an example with clap
+ Write an example with complex structure like hashmap, array, flattened
+ Support Vault
+ Imagine a good trait/api to extend and let users fetch config from remote
+ Refactor to let user extend layers
+ Add support of nested struct in envy
+ Fix issue with `#[serde(flatten)] when you use other type than `String` in sub types


# Alternatives

+ [config-rs](https://github.com/mehcode/config-rs) is almost doing the same except the environment layer (for example we support hashmap and array in environment variables). Also `config-rs` don't have clap support and it didn't use any proc-macros if you're not very fan of proc-macros.