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
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
# fondant
`fondant` is a macro based library to take the boilerplate out of
configuration handling. Most of `fondant` is based off the `confy` crate.
`fondant` adds a couple of extra features:
- support for json, yaml and toml
- support for custom config paths
- support for custom config file names
### Sample usage
```rust
// the struct has to derive Serialize, Deserialize and Default
#[derive(Configure, Serialize, Deserialize, Default)]
#[config_file = "config.toml"]
// |
// `-- this attribute sets the file name to "config.toml"
// `-- the file format to "toml"
// `-- the file path to "default" (read the notes below)
struct AppConfig {
version: u32,
port: u32,
username: String,
}
fn main() {
// use `load` (associated method) to load the config file
let mut conf = AppConfig::load().unwrap();
// do stuff with conf
conf.version = 2;
// call `store` to save changes
conf.store().unwrap();
}
```
**Notes**:
- `load` returns `Default::default` if the config file is not present, and stores
a serialized `Default::default` at the specified path
- the "default" config path varies by platform:
* GNU/Linux: `$XDG_CONFIG_HOME/my_cool_crate/config.toml` (follows xdg spec)
* MacOS: `$HOME/Library/Preferences/my_cool_crate/config.toml`
* Windows: `{FOLDERID_RoamingAppData}\_project_path_\config`
### Customization
Set your own filename, for ex.: `apprc`
```rust
#[derive(Configure, Serialize, Deserialize, Default)]
#[config_file = "apprc.toml"]
struct AppConfig {
// -- snip --
}
// effective path: $XDG_CONFIG_HOME/my_cool_crate/apprc.toml
// effective format: toml
```
Change file format to `yaml`, by changing the file extension.
Supported extensions are `yaml`, `toml`, `json`:
```rust
#[derive(Configure, Serialize, Deserialize, Default)]
#[config_file = "config.yaml"]
struct AppConfig {
// -- snip --
}
// effective path: $XDG_CONFIG_HOME/my_cool_crate/config.yaml
// effective format: yaml
```
Override the default config path, for ex.: the home directory
(it is not recommended to override config path):
```rust
#[derive(Configure, Serialize, Deserialize, Default)]
#[config_file = "~/.apprc.json"]
struct AppConfig {
// -- snip --
}
// effective path: $HOME/.apprc.json
// effective format: json
```
Fondant meshes well with Serde, for ex.:
```rust
#[derive(Configure, Serialize, Deserialize, Default)]
#[config_file = "config.toml"]
struct Madagascar {
#[serde(skip)]
rating: u32,
name: String,
penguins: u32,
}
```
Above snippet produces this config file:
```toml
name = 'Central Park Zoo'
penguins = 4
```
### todo
- [ ] improve error from trait impl
- [ ] use `syn::Error` and `syn::Result` to report macro errors
- [x] write docs
- [ ] bundle and publish to crates.io
|
