aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--fondant_derive/.gitignore10
-rw-r--r--readme.md106
2 files changed, 86 insertions, 30 deletions
diff --git a/fondant_derive/.gitignore b/fondant_derive/.gitignore
deleted file mode 100644
index 088ba6b..0000000
--- a/fondant_derive/.gitignore
+++ /dev/null
@@ -1,10 +0,0 @@
1# Generated by Cargo
2# will have compiled files and executables
3/target/
4
5# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
6# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
7Cargo.lock
8
9# These are backup files generated by rustfmt
10**/*.rs.bk
diff --git a/readme.md b/readme.md
index 3445327..9f239c5 100644
--- a/readme.md
+++ b/readme.md
@@ -1,47 +1,113 @@
1# fondant 1# fondant
2 2
3> an experimental, macro-only, boilerplate free, configuration management library 3`fondant` is a macro based library to take the boilerplate out of
4configuration handling. Most of `fondant` is based off the `confy` crate.
4 5
5### example 6`fondant` adds a couple of extra features:
7
8 - support for json, yaml and toml
9 - support for custom config paths
10 - support for custom config file names
11
12### Sample usage
6 13
7```rust 14```rust
8// derive the `Configure` trait, and specify the 15// the struct has to derive Serialize, Deserialize and Default
9// `config_file` attribute 16#[derive(Configure, Serialize, Deserialize, Default)]
10#[derive(Configure, Default, Serialize, Deserialize)]
11#[config_file = "config.toml"] 17#[config_file = "config.toml"]
18// |
19// `-- this attribute sets the file name to "config.toml"
20// `-- the file format to "toml"
21// `-- the file path to "default" (read the notes below)
12struct AppConfig { 22struct AppConfig {
13 -- snip -- 23 version: u32,
24 port: u32,
25 username: String,
14} 26}
15 27
16// `Configure` exposes `load` and `store`
17fn main() { 28fn main() {
18 let mut config = AppConfig::load().unwrap(); 29 // use `load` (associated method) to load the config file
19 config.version = 2; 30 let mut conf = AppConfig::load().unwrap();
20 config.path = "/home/np".to_string(); 31
21 config.store(); 32 // do stuff with conf
33 conf.version = 2;
34
35 // call `store` to save changes
36 conf.store().unwrap();
37}
38```
39
40**Notes**:
41 - `load` returns `Default::default` if the config file is not present, and stores
42 a serialized `Default::default` at the specified path
43 - the "default" config path varies by platform:
44 * GNU/Linux: `$XDG_CONFIG_HOME/my_cool_crate/config.toml` (follows xdg spec)
45 * MacOS: `$HOME/Library/Preferences/my_cool_crate/config.toml`
46 * Windows: `{FOLDERID_RoamingAppData}\_project_path_\config`
47
48### Customization
49
50Set your own filename, for ex.: `apprc`
51
52```rust
53#[derive(Configure, Serialize, Deserialize, Default)]
54#[config_file = "apprc.toml"]
55struct AppConfig {
56 // -- snip --
22} 57}
58// effective path: $XDG_CONFIG_HOME/my_cool_crate/apprc.toml
59// effective format: toml
23``` 60```
24 61
25You can specify a path to be used, unless you want to stick 62Change file format to `yaml`, by changing the file extension.
26with the defaults: 63Supported extensions are `yaml`, `toml`, `json`:
27 64
28```rust 65```rust
29// load from and store in user's home directory 66#[derive(Configure, Serialize, Deserialize, Default)]
30#[config_file = "~/config.toml"] 67#[config_file = "config.yaml"]
68struct AppConfig {
69 // -- snip --
70}
71// effective path: $XDG_CONFIG_HOME/my_cool_crate/config.yaml
72// effective format: yaml
31``` 73```
32 74
33`fondant` supports `yaml`, `toml` and `json`, defaults to 75Override the default config path, for ex.: the home directory
34`toml`: 76(it is not recommended to override config path):
77
78```rust
79#[derive(Configure, Serialize, Deserialize, Default)]
80#[config_file = "~/.apprc.json"]
81struct AppConfig {
82 // -- snip --
83}
84// effective path: $HOME/.apprc.json
85// effective format: json
86```
35 87
88Fondant meshes well with Serde, for ex.:
36```rust 89```rust
90#[derive(Configure, Serialize, Deserialize, Default)]
37#[config_file = "config.toml"] 91#[config_file = "config.toml"]
38#[config_file = "my_app_config.yaml"] 92struct Madagascar {
39#[config_file = "~/.app.conf.json"] 93 #[serde(skip)]
94 rating: u32,
95
96 name: String,
97 penguins: u32,
98}
99```
100
101Above snippet produces this config file:
102```toml
103name = 'Central Park Zoo'
104penguins = 4
40``` 105```
41 106
42### todo 107### todo
43 108
44 - [ ] improve error from trait impl 109 - [ ] improve error from trait impl
45 - [ ] use `syn::Error` and `syn::Result` to report macro errors 110 - [ ] use `syn::Error` and `syn::Result` to report macro errors
46 - [ ] write docs 111 - [x] write docs
47 - [ ] bundle and publish to crates.io 112 - [ ] bundle and publish to crates.io
113