Expand description
§fondant
Documentation · Architecture · Usage · Customization · Todo
fondant
is a macro based library to take the boilerplate out of
configuration handling. All you need to do is derive the
Configure
trait on your struct, and fondant
will decide
where to store it and and how to do so safely.
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
§Architecture
fondant
is split into 3 separate crates:
fondant_deps
: external crates and utils thatfondant
requiresfondant_derive
: core macro definitionsfondant
: the user facing library that brings it all together
This slightly strange architecture arose because of some
limitations with proc-macro crates and strict cyclic
dependencies in cargo. All you need is the fondant
crate.
§Usage
// the struct has to derive Serialize, Deserialize and Default
#[derive(Configure, Serialize, Deserialize, Default)]
#[config_file = "config.toml"]
// `config_file` attribute sets the file name to "config.toml"
// the file format to "toml"
// and the file path to "default" (read the notes below)
struct AppConfig {
version: u32,
port: u32,
username: String,
}
fn main() {
// use `load` to load the config file
// loads in Default::default if it can't find one
let mut conf = AppConfig::load().unwrap();
// do stuff with conf
conf.version = 2;
// call `store` to save changes
conf.store().unwrap();
}
Notes:
load
returnsDefault::default
if the config file is not present, and stores a serializedDefault::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
- GNU/Linux:
§Customization
Set your own filename, for ex.: apprc
#[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
:
#[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 (not recommended), for ex.: the home directory:
#[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.:
#[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:
name = 'Central Park Zoo'
penguins = 4
Modules§
Enums§
- Errors that
load
andstore
can result in
Traits§
- Derive this trait on a struct to mark it as a ‘configuration’ struct.