diff options
Diffstat (limited to 'fondant')
-rw-r--r-- | fondant/Cargo.toml | 9 | ||||
-rw-r--r-- | fondant/src/lib.rs | 86 |
2 files changed, 95 insertions, 0 deletions
diff --git a/fondant/Cargo.toml b/fondant/Cargo.toml new file mode 100644 index 0000000..d6886b1 --- /dev/null +++ b/fondant/Cargo.toml | |||
@@ -0,0 +1,9 @@ | |||
1 | [package] | ||
2 | name = "fondant" | ||
3 | version = "0.1.0" | ||
4 | authors = ["Akshay <[email protected]>"] | ||
5 | edition = "2018" | ||
6 | |||
7 | [dependencies] | ||
8 | fondant_derive = {version = "0.1.0", path = "../fondant_derive"} | ||
9 | fondant_deps = {version = "0.1.0", path = "../fondant_deps"} | ||
diff --git a/fondant/src/lib.rs b/fondant/src/lib.rs new file mode 100644 index 0000000..d5758dc --- /dev/null +++ b/fondant/src/lib.rs | |||
@@ -0,0 +1,86 @@ | |||
1 | //! `fondant` is a macro based library to take the boilerplate out of | ||
2 | //! configuration handling. Most of `fondant` is based off the `confy` crate. | ||
3 | //! | ||
4 | //! `fondant` adds a couple of extra features: | ||
5 | //! | ||
6 | //! - support for json, yaml and toml | ||
7 | //! - support for custom config paths | ||
8 | //! - support for custom config file names | ||
9 | //! | ||
10 | //! ### Sample usage | ||
11 | //! | ||
12 | //! ``` | ||
13 | //! // the struct has to derive Serialize, Deserialize and Default | ||
14 | //! #[derive(Configure, Serialize, Deserialize, Default)] | ||
15 | //! #[config_file = "config.toml"] | ||
16 | //! // | | ||
17 | //! // `-- this attribute sets the file name to "config.toml" | ||
18 | //! // `-- the file format to "toml" | ||
19 | //! // `-- the file path to "default" (read the notes below) | ||
20 | //! struct AppConfig { | ||
21 | //! version: u32, | ||
22 | //! port: u32, | ||
23 | //! username: String, | ||
24 | //! } | ||
25 | //! | ||
26 | //! fn main() { | ||
27 | //! // use `load` (associated method) to load the config file | ||
28 | //! let mut conf = AppConfig::load().unwrap(); | ||
29 | //! | ||
30 | //! // do stuff with conf | ||
31 | //! conf.version = 2; | ||
32 | //! | ||
33 | //! // call `store` to save changes | ||
34 | //! conf.store().unwrap(); | ||
35 | //! } | ||
36 | //! ``` | ||
37 | //! **Notes**: | ||
38 | //! - `load` returns `Default::default` if the config file is not present, and stores | ||
39 | //! a serialized `Default::default` at the specified path | ||
40 | //! - the "default" config path varies by platform: | ||
41 | //! * GNU/Linux: `$XDG_CONFIG_HOME/my_cool_crate/config.toml` (follows xdg spec) | ||
42 | //! * MacOS: `$HOME/Library/Preferences/my_cool_crate/config.toml` | ||
43 | //! * Windows: `{FOLDERID_RoamingAppData}\_project_path_\config` | ||
44 | //! | ||
45 | //! ### Customization | ||
46 | //! | ||
47 | //! Set your own filename, for ex.: `apprc` | ||
48 | //! | ||
49 | //! ``` | ||
50 | //! #[derive(Configure, Serialize, Deserialize, Default)] | ||
51 | //! #[config_file = "apprc.toml"] | ||
52 | //! struct AppConfig { | ||
53 | //! // -- snip -- | ||
54 | //! } | ||
55 | //! // effective path: $XDG_CONFIG_HOME/my_cool_crate/apprc.toml | ||
56 | //! // effective format: toml | ||
57 | //! ``` | ||
58 | //! | ||
59 | //! Change file format to `yaml`, by changing the file extension. | ||
60 | //! Supported extensions are `yaml`, `toml`, `json`: | ||
61 | //! ``` | ||
62 | //! #[derive(Configure, Serialize, Deserialize, Default)] | ||
63 | //! #[config_file = "config.yaml"] | ||
64 | //! struct AppConfig { | ||
65 | //! // -- snip -- | ||
66 | //! } | ||
67 | //! // effective path: $XDG_CONFIG_HOME/my_cool_crate/config.yaml | ||
68 | //! // effective format: yaml | ||
69 | //! ``` | ||
70 | //! | ||
71 | //! Override the default config path, for ex.: the home directory | ||
72 | //! (it is not recommended to override config path): | ||
73 | //! ``` | ||
74 | //! #[derive(Configure, Serialize, Deserialize, Default)] | ||
75 | //! #[config_file = "~/.apprc.json"] | ||
76 | //! struct AppConfig { | ||
77 | //! // -- snip -- | ||
78 | //! } | ||
79 | //! // effective path: $HOME/.apprc.json | ||
80 | //! // effective format: json | ||
81 | //! ``` | ||
82 | |||
83 | pub use fondant_deps::fondant_exports; | ||
84 | pub use fondant_deps::Configure; | ||
85 | pub use fondant_deps::FondantError; | ||
86 | pub use fondant_derive::Configure; | ||