From 73796ae676d32810d46e293c2c93f0536da8f9ee Mon Sep 17 00:00:00 2001 From: Lukas Kalbertodt Date: Fri, 21 Oct 2022 18:27:05 +0200 Subject: [PATCH] Adjust README --- README.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 98 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 0ef4ca2..22d58c1 100644 --- a/README.md +++ b/README.md @@ -13,26 +13,28 @@ Confique is a rather light-weight library that helps with configuration manageme - **Layered configuration**: you can load from and then merge multiple sources of configuration. - **Load config values from**: - Environment variables - - Files: TOML & YAML - - Anything with a `serde` Deserializer (built-in support for more formats coming soon) + - Files: [TOML](https://toml.io/), [YAML](https://yaml.org/), and [JSON5](https://json5.org/) + - Anything with a `serde` Deserializer - **Based on `serde`**: less code in `confique` (more light-weight) and access to a huge ecosystem of high quality parsers. -- Easily generate configuration "templates" to describe all available config values to your users. +- **Easily generate configuration "templates"**: describe all available config values to your users without repeating yourself. ## Simple example ```rust -use std::path::PathBuf; +use std::{net::IpAddr, path::PathBuf}; use confique::Config; #[derive(Config)] struct Conf { - #[config(env = "EXAMPLE_APP_USERNAME")] - username: String, + /// Port to listen on. + #[config(env = "PORT", default = 8080)] + port: u16, - #[config(env = "EXAMPLE_APP_BUFFER_SIZE", default = 4096)] - buffer_size: u32, + /// Bind address. + #[config(default = "127.0.0.1")] + address: IpAddr, #[config(nested)] log: LogConf, @@ -44,6 +46,9 @@ struct LogConf { stdout: bool, file: Option, + + #[config(default = ["debug"])] + ignored_modules: Vec, } @@ -56,11 +61,91 @@ let config = Conf::builder() See [**the documentation**](https://docs.rs/confique) for more information. +### Configuration Template + +With the above example, you can automatically generate a configuration template: +a file in a chosen format that lists all values with their description, default values, and env values. + + + + + + + + + + + + +
toml::template::<Conf>()yaml::template::<Conf>()json5::template::<Conf>()
+ +```toml +# Port to listen on. +# +# Can also be specified via +# environment variable `PORT`. +# +# Default value: 8080 +#port = 8080 + +# Bind address. +# +# Default value: "127.0.0.1" +#address = "127.0.0.1" + +[log] +# +``` + + + +```yaml +# Port to listen on. +# +# Can also be specified via +# environment variable `PORT`. +# +# Default value: 8080 +#port: 8080 + +# Bind address. +# +# Default value: 127.0.0.1 +#address: 127.0.0.1 + +log: + # +``` + + + +```json5 +{ + // Port to listen on. + // + // Can also be specified via + // environment variable `PORT`. + // + // Default value: 8080 + //port: 8080, + + // Bind address. + // + // Default value: "127.0.0.1" + //address: "127.0.0.1", + + log: { + // + }, +} +``` + +
+ +(Note: The "environment variable" sentence is on a single line; I just split it into two lines for readability in this README.) ## Comparison with other libraries/solutions -Obviously, all other libraries are more mature than confique. - ### [`config`](https://crates.io/crates/config) - Loosely typed: @@ -86,9 +171,9 @@ With `confique` you also get some other handy helpers. ## Status of this project -Confique is still a very young project. -There are lots of features and improvements already planned. -I'm developing this library alongside a web project that uses it. +There is still some design space to explore and there are certainly still many features one could add. +However, the core interface (the derive macro and the core traits) probably won't change a lot anymore. +Confique is used by a web project (that's already used in production) which I'm developing alongside of confique.