aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--[l---------]fondant_deps/readme.md4
-rw-r--r--[l---------]fondant_derive/readme.md4
-rw-r--r--readme.md112
3 files changed, 37 insertions, 83 deletions
diff --git a/fondant_deps/readme.md b/fondant_deps/readme.md
index 15926e3..3366f48 120000..100644
--- a/fondant_deps/readme.md
+++ b/fondant_deps/readme.md
@@ -1 +1,3 @@
1../readme.md \ No newline at end of file 1### fondant_deps
2
3> external crates and utils that `fondant` requires
diff --git a/fondant_derive/readme.md b/fondant_derive/readme.md
index 15926e3..0e32c0d 120000..100644
--- a/fondant_derive/readme.md
+++ b/fondant_derive/readme.md
@@ -1 +1,3 @@
1../readme.md \ No newline at end of file 1### fondant_derive
2
3> core macro definitions
diff --git a/readme.md b/readme.md
index f76f63c..753faba 100644
--- a/readme.md
+++ b/readme.md
@@ -1,10 +1,16 @@
1# fondant 1# fondant
2 2
3[Documentation](https://docs.rs/fondant/) ·
3[Architecture](#Architecture) · [Usage](#Usage) · 4[Architecture](#Architecture) · [Usage](#Usage) ·
4[Customization](#Customization) · [Todo](#Todo) 5[Customization](#Customization) · [Todo](#Todo)
5 6
6`fondant` is a macro based library to take the boilerplate out of 7`fondant` is a macro based library to take the boilerplate out of
7configuration handling. Most of `fondant` is based off the `confy` crate. 8configuration handling. All you need to do is derive the
9`Configure` trait on your struct, and fondant will decide
10where to store it and and how to do so safely.
11
12
13Most of `fondant` is based off the `confy` crate.
8 14
9`fondant` adds a couple of extra features: 15`fondant` adds a couple of extra features:
10 16
@@ -12,117 +18,61 @@ configuration handling. Most of `fondant` is based off the `confy` crate.
12 - support for custom config paths 18 - support for custom config paths
13 - support for custom config file names 19 - support for custom config file names
14 20
15### Architecture 21### Usage ([Full Documentation](https://docs.rs/fondant/))
16
17`fondant` is split into 3 separate crates:
18 22
19 - `fondant_deps`: external crates and utils that `fondant` requires 23Drop this in your `Cargo.toml` to gets started:
20 - `fondant_derive`: core macro definitions
21 - `fondant`: the user facing library that brings it all together
22 24
23This slightly strange architecture arose because of some 25```
24limitations with proc-macro crates and strict cyclic 26[dependencies]
25dependencies in cargo. All you need is the `fondant` crate. 27fondant = "0.1.0"
28```
26 29
27### Usage 30Derive the macro:
28 31
29```rust 32```rust
30// the struct has to derive Serialize, Deserialize and Default 33// the struct has to derive Serialize, Deserialize and Default
34use fondant::Configure;
35use serde::{Serialize, Deserialize};
36
31#[derive(Configure, Serialize, Deserialize, Default)] 37#[derive(Configure, Serialize, Deserialize, Default)]
32#[config_file = "config.toml"] 38#[config_file = "config.toml"]
33// |
34// `-- this attribute sets the file name to "config.toml"
35// `-- the file format to "toml"
36// `-- the file path to "default" (read the notes below)
37struct AppConfig { 39struct AppConfig {
38 version: u32,
39 port: u32, 40 port: u32,
40 username: String, 41 username: String,
41} 42}
42 43
43fn main() { 44fn main() {
44 // use `load` (associated method) to load the config file 45 // use `load` to load the config file
46 // loads in Default::default if it can't find one
45 let mut conf = AppConfig::load().unwrap(); 47 let mut conf = AppConfig::load().unwrap();
46 48
47 // do stuff with conf 49 // do stuff with conf
48 conf.version = 2; 50 conf.port = 7878;
49 51
50 // call `store` to save changes 52 // call `store` to save changes
51 conf.store().unwrap(); 53 conf.store().unwrap();
52} 54}
53``` 55```
54 56
55**Notes**: 57Find more examples and options at [docs.rs](https://docs.rs/fondant/).
56 - `load` returns `Default::default` if the config file is not present, and stores
57 a serialized `Default::default` at the specified path
58 - the "default" config path varies by platform:
59 * GNU/Linux: `$XDG_CONFIG_HOME/my_cool_crate/config.toml` (follows xdg spec)
60 * MacOS: `$HOME/Library/Preferences/my_cool_crate/config.toml`
61 * Windows: `{FOLDERID_RoamingAppData}\_project_path_\config`
62
63### Customization
64
65Set your own filename, for ex.: `apprc`
66
67```rust
68#[derive(Configure, Serialize, Deserialize, Default)]
69#[config_file = "apprc.toml"]
70struct AppConfig {
71 // -- snip --
72}
73// effective path: $XDG_CONFIG_HOME/my_cool_crate/apprc.toml
74// effective format: toml
75```
76
77Change file format to `yaml`, by changing the file extension.
78Supported extensions are `yaml`, `toml`, `json`:
79
80```rust
81#[derive(Configure, Serialize, Deserialize, Default)]
82#[config_file = "config.yaml"]
83struct AppConfig {
84 // -- snip --
85}
86// effective path: $XDG_CONFIG_HOME/my_cool_crate/config.yaml
87// effective format: yaml
88```
89 58
90Override the default config path, for ex.: the home directory 59### Architecture
91(it is not recommended to override config path):
92 60
93```rust 61`fondant` is split into 3 separate crates:
94#[derive(Configure, Serialize, Deserialize, Default)]
95#[config_file = "~/.apprc.json"]
96struct AppConfig {
97 // -- snip --
98}
99// effective path: $HOME/.apprc.json
100// effective format: json
101```
102 62
103Fondant meshes well with Serde, for ex.: 63 - `fondant_deps`: external crates and utils that `fondant` requires
104```rust 64 - `fondant_derive`: core macro definitions
105#[derive(Configure, Serialize, Deserialize, Default)] 65 - `fondant`: the user facing library that brings it all together
106#[config_file = "config.toml"]
107struct Madagascar {
108 #[serde(skip)]
109 rating: u32,
110 66
111 name: String, 67This slightly strange architecture arose because of some
112 penguins: u32, 68limitations with proc-macro crates and strict cyclic
113} 69dependencies in cargo. All you need is the `fondant` crate.
114```
115 70
116Above snippet produces this config file:
117```toml
118name = 'Central Park Zoo'
119penguins = 4
120```
121 71
122### Todo 72### Todo
123 73
124 - [ ] improve error from trait impl 74 - [ ] improve error types
125 - [ ] use `syn::Error` and `syn::Result` to report macro errors 75 - [ ] use `syn::Error` and `syn::Result` to report macro errors
126 - [x] write docs 76 - [x] write docs
127 - [ ] bundle and publish to crates.io 77 - [x] bundle and publish to crates.io
128 78