aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--fondant/src/lib.rs69
1 files changed, 56 insertions, 13 deletions
diff --git a/fondant/src/lib.rs b/fondant/src/lib.rs
index d5758dc..ddf29c9 100644
--- a/fondant/src/lib.rs
+++ b/fondant/src/lib.rs
@@ -1,22 +1,42 @@
1//! # fondant
2//!
3//! [Documentation](https://docs.rs/fondant/) ·
4//! [Architecture](#Architecture) · [Usage](#Usage) ·
5//! [Customization](#Customization) · [Todo](#Todo)
6//!
1//! `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
2//! configuration handling. Most of `fondant` is based off the `confy` crate. 8//! configuration handling. All you need to do is derive the
9//! `Configure` trait on your struct, and `fondant` will decide
10//! where to store it and and how to do so safely.
3//! 11//!
12//! Most of `fondant` is based off the `confy` crate.
4//! `fondant` adds a couple of extra features: 13//! `fondant` adds a couple of extra features:
5//! 14//!
6//! - support for json, yaml and toml 15//! - support for json, yaml and toml
7//! - support for custom config paths 16//! - support for custom config paths
8//! - support for custom config file names 17//! - support for custom config file names
9//! 18//!
10//! ### Sample usage 19//! ### Architecture
11//! 20//!
12//! ``` 21//! `fondant` is split into 3 separate crates:
22//!
23//! - `fondant_deps`: external crates and utils that `fondant` requires
24//! - `fondant_derive`: core macro definitions
25//! - `fondant`: the user facing library that brings it all together
26//!
27//! This slightly strange architecture arose because of some
28//! limitations with proc-macro crates and strict cyclic
29//! dependencies in cargo. All you need is the `fondant` crate.
30//!
31//! ### Usage
32//!
33//! ```rust
13//! // the struct has to derive Serialize, Deserialize and Default 34//! // the struct has to derive Serialize, Deserialize and Default
14//! #[derive(Configure, Serialize, Deserialize, Default)] 35//! #[derive(Configure, Serialize, Deserialize, Default)]
15//! #[config_file = "config.toml"] 36//! #[config_file = "config.toml"]
16//! // | 37//! // `config_file` attribute sets the file name to "config.toml"
17//! // `-- this attribute sets the file name to "config.toml" 38//! // the file format to "toml"
18//! // `-- the file format to "toml" 39//! // and the file path to "default" (read the notes below)
19//! // `-- the file path to "default" (read the notes below)
20//! struct AppConfig { 40//! struct AppConfig {
21//! version: u32, 41//! version: u32,
22//! port: u32, 42//! port: u32,
@@ -24,7 +44,8 @@
24//! } 44//! }
25//! 45//!
26//! fn main() { 46//! fn main() {
27//! // use `load` (associated method) to load the config file 47//! // use `load` to load the config file
48//! // loads in Default::default if it can't find one
28//! let mut conf = AppConfig::load().unwrap(); 49//! let mut conf = AppConfig::load().unwrap();
29//! 50//!
30//! // do stuff with conf 51//! // do stuff with conf
@@ -34,6 +55,7 @@
34//! conf.store().unwrap(); 55//! conf.store().unwrap();
35//! } 56//! }
36//! ``` 57//! ```
58//!
37//! **Notes**: 59//! **Notes**:
38//! - `load` returns `Default::default` if the config file is not present, and stores 60//! - `load` returns `Default::default` if the config file is not present, and stores
39//! a serialized `Default::default` at the specified path 61//! a serialized `Default::default` at the specified path
@@ -46,7 +68,7 @@
46//! 68//!
47//! Set your own filename, for ex.: `apprc` 69//! Set your own filename, for ex.: `apprc`
48//! 70//!
49//! ``` 71//! ```rust
50//! #[derive(Configure, Serialize, Deserialize, Default)] 72//! #[derive(Configure, Serialize, Deserialize, Default)]
51//! #[config_file = "apprc.toml"] 73//! #[config_file = "apprc.toml"]
52//! struct AppConfig { 74//! struct AppConfig {
@@ -58,7 +80,8 @@
58//! 80//!
59//! Change file format to `yaml`, by changing the file extension. 81//! Change file format to `yaml`, by changing the file extension.
60//! Supported extensions are `yaml`, `toml`, `json`: 82//! Supported extensions are `yaml`, `toml`, `json`:
61//! ``` 83//!
84//! ```rust
62//! #[derive(Configure, Serialize, Deserialize, Default)] 85//! #[derive(Configure, Serialize, Deserialize, Default)]
63//! #[config_file = "config.yaml"] 86//! #[config_file = "config.yaml"]
64//! struct AppConfig { 87//! struct AppConfig {
@@ -68,9 +91,10 @@
68//! // effective format: yaml 91//! // effective format: yaml
69//! ``` 92//! ```
70//! 93//!
71//! Override the default config path, for ex.: the home directory 94//! Override the default config path (not recommended),
72//! (it is not recommended to override config path): 95//! for ex.: the home directory:
73//! ``` 96//!
97//! ```rust
74//! #[derive(Configure, Serialize, Deserialize, Default)] 98//! #[derive(Configure, Serialize, Deserialize, Default)]
75//! #[config_file = "~/.apprc.json"] 99//! #[config_file = "~/.apprc.json"]
76//! struct AppConfig { 100//! struct AppConfig {
@@ -79,6 +103,25 @@
79//! // effective path: $HOME/.apprc.json 103//! // effective path: $HOME/.apprc.json
80//! // effective format: json 104//! // effective format: json
81//! ``` 105//! ```
106//!
107//! Fondant meshes well with Serde, for ex.:
108//! ```rust
109//! #[derive(Configure, Serialize, Deserialize, Default)]
110//! #[config_file = "config.toml"]
111//! struct Madagascar {
112//! #[serde(skip)]
113//! rating: u32,
114//!
115//! name: String,
116//! penguins: u32,
117//! }
118//! ```
119//!
120//! Above snippet produces this config file:
121//! ```toml
122//! name = 'Central Park Zoo'
123//! penguins = 4
124//! ```
82 125
83pub use fondant_deps::fondant_exports; 126pub use fondant_deps::fondant_exports;
84pub use fondant_deps::Configure; 127pub use fondant_deps::Configure;