fondant/
lib.rs

1//! # fondant
2//!
3//! [Documentation](https://docs.rs/fondant/) ·
4//! [Architecture](#Architecture) · [Usage](#Usage) ·
5//! [Customization](#Customization) · [Todo](#Todo)
6//!
7//! `fondant` is a macro based library to take the boilerplate out of
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.
11//!
12//! Most of `fondant` is based off the `confy` crate.
13//! `fondant` adds a couple of extra features:
14//!
15//!  - support for json, yaml and toml
16//!  - support for custom config paths
17//!  - support for custom config file names
18//!
19//! ### Architecture
20//!
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
34//! // the struct has to derive Serialize, Deserialize and Default
35//! #[derive(Configure, Serialize, Deserialize, Default)]
36//! #[config_file = "config.toml"]
37//! // `config_file` attribute sets the file name to "config.toml"
38//! // the file format to "toml"
39//! // and the file path to "default" (read the notes below)
40//! struct AppConfig {
41//!     version: u32,
42//!     port: u32,
43//!     username: String,
44//! }
45//!
46//! fn main() {
47//!     // use `load` to load the config file
48//!     // loads in Default::default if it can't find one
49//!     let mut conf = AppConfig::load().unwrap();
50//!
51//!     // do stuff with conf
52//!     conf.version = 2;
53//!
54//!     // call `store` to save changes
55//!     conf.store().unwrap();
56//! }
57//! ```
58//!
59//! **Notes**:  
60//!  - `load` returns `Default::default` if the config file is not present, and stores
61//!  a serialized `Default::default` at the specified path
62//!  - the "default" config path varies by platform:
63//!     * GNU/Linux: `$XDG_CONFIG_HOME/my_cool_crate/config.toml` (follows xdg spec)
64//!     * MacOS: `$HOME/Library/Preferences/my_cool_crate/config.toml`
65//!     * Windows: `{FOLDERID_RoamingAppData}\_project_path_\config`
66//!
67//! ### Customization
68//!
69//! Set your own filename, for ex.: `apprc`
70//!
71//! ```rust
72//! #[derive(Configure, Serialize, Deserialize, Default)]
73//! #[config_file = "apprc.toml"]
74//! struct AppConfig {
75//!     // -- snip --
76//! }
77//! // effective path: $XDG_CONFIG_HOME/my_cool_crate/apprc.toml
78//! // effective format: toml
79//! ```
80//!
81//! Change file format to `yaml`, by changing the file extension.
82//! Supported extensions are `yaml`, `toml`, `json`:
83//!
84//! ```rust
85//! #[derive(Configure, Serialize, Deserialize, Default)]
86//! #[config_file = "config.yaml"]
87//! struct AppConfig {
88//!     // -- snip --
89//! }
90//! // effective path: $XDG_CONFIG_HOME/my_cool_crate/config.yaml
91//! // effective format: yaml
92//! ```
93//!
94//! Override the default config path (not recommended),
95//! for ex.: the home directory:
96//!
97//! ```rust
98//! #[derive(Configure, Serialize, Deserialize, Default)]
99//! #[config_file = "~/.apprc.json"]
100//! struct AppConfig {
101//!     // -- snip --
102//! }
103//! // effective path: $HOME/.apprc.json
104//! // effective format: json
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//! ```
125
126pub use fondant_deps::fondant_exports;
127pub use fondant_deps::Configure;
128pub use fondant_deps::FondantError;
129pub use fondant_derive::Configure;
fondant/lib.rs

fondant/
lib.rs
