From 9b8377c0ca3eb352aef57bc21bdcfcb7fd229d08 Mon Sep 17 00:00:00 2001 From: Akshay Date: Thu, 2 Apr 2020 17:17:44 +0530 Subject: modify readme stubs --- fondant_deps/readme.md | 4 +- fondant_derive/readme.md | 4 +- readme.md | 112 +++++++++++++---------------------------------- 3 files changed, 37 insertions(+), 83 deletions(-) mode change 120000 => 100644 fondant_deps/readme.md mode change 120000 => 100644 fondant_derive/readme.md diff --git a/fondant_deps/readme.md b/fondant_deps/readme.md deleted file mode 120000 index 15926e3..0000000 --- a/fondant_deps/readme.md +++ /dev/null @@ -1 +0,0 @@ -../readme.md \ No newline at end of file diff --git a/fondant_deps/readme.md b/fondant_deps/readme.md new file mode 100644 index 0000000..3366f48 --- /dev/null +++ b/fondant_deps/readme.md @@ -0,0 +1,3 @@ +### fondant_deps + +> external crates and utils that `fondant` requires diff --git a/fondant_derive/readme.md b/fondant_derive/readme.md deleted file mode 120000 index 15926e3..0000000 --- a/fondant_derive/readme.md +++ /dev/null @@ -1 +0,0 @@ -../readme.md \ No newline at end of file diff --git a/fondant_derive/readme.md b/fondant_derive/readme.md new file mode 100644 index 0000000..0e32c0d --- /dev/null +++ b/fondant_derive/readme.md @@ -0,0 +1,3 @@ +### fondant_derive + +> 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 @@ # fondant +[Documentation](https://docs.rs/fondant/) · [Architecture](#Architecture) · [Usage](#Usage) · [Customization](#Customization) · [Todo](#Todo) `fondant` is a macro based library to take the boilerplate out of -configuration handling. Most of `fondant` is based off the `confy` crate. +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: @@ -12,117 +18,61 @@ configuration handling. Most of `fondant` is based off the `confy` crate. - support for custom config paths - support for custom config file names -### Architecture - -`fondant` is split into 3 separate crates: +### Usage ([Full Documentation](https://docs.rs/fondant/)) - - `fondant_deps`: external crates and utils that `fondant` requires - - `fondant_derive`: core macro definitions - - `fondant`: the user facing library that brings it all together +Drop this in your `Cargo.toml` to gets started: -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. +``` +[dependencies] +fondant = "0.1.0" +``` -### Usage +Derive the macro: ```rust // the struct has to derive Serialize, Deserialize and Default +use fondant::Configure; +use serde::{Serialize, Deserialize}; + #[derive(Configure, Serialize, Deserialize, Default)] #[config_file = "config.toml"] -// | -// `-- this attribute sets the file name to "config.toml" -// `-- the file format to "toml" -// `-- the file path to "default" (read the notes below) struct AppConfig { - version: u32, port: u32, username: String, } fn main() { - // use `load` (associated method) to load the config file + // 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; + conf.port = 7878; // call `store` to save changes conf.store().unwrap(); } ``` -**Notes**: - - `load` returns `Default::default` if the config file is not present, and stores - a serialized `Default::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` - -### Customization - -Set your own filename, for ex.: `apprc` - -```rust -#[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`: - -```rust -#[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 -``` +Find more examples and options at [docs.rs](https://docs.rs/fondant/). -Override the default config path, for ex.: the home directory -(it is not recommended to override config path): +### Architecture -```rust -#[derive(Configure, Serialize, Deserialize, Default)] -#[config_file = "~/.apprc.json"] -struct AppConfig { - // -- snip -- -} -// effective path: $HOME/.apprc.json -// effective format: json -``` +`fondant` is split into 3 separate crates: -Fondant meshes well with Serde, for ex.: -```rust -#[derive(Configure, Serialize, Deserialize, Default)] -#[config_file = "config.toml"] -struct Madagascar { - #[serde(skip)] - rating: u32, + - `fondant_deps`: external crates and utils that `fondant` requires + - `fondant_derive`: core macro definitions + - `fondant`: the user facing library that brings it all together - name: String, - penguins: u32, -} -``` +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. -Above snippet produces this config file: -```toml -name = 'Central Park Zoo' -penguins = 4 -``` ### Todo - - [ ] improve error from trait impl + - [ ] improve error types - [ ] use `syn::Error` and `syn::Result` to report macro errors - [x] write docs - - [ ] bundle and publish to crates.io + - [x] bundle and publish to crates.io -- cgit v1.2.3