Crate config_manager

Source
Expand description

Crate to build config from environment, command line and files

§Motivation

Non-runtime data generally comes to a project from command line, environment and configuration files.
Sometimes it comes from each of the sources simultaneously, so all of them must be handled.
None of the popular crates (including clap and config) can’t handle all 3 together, so this crate has been created to solve this problem.

§Basis

The Core of the crate is an attribute-macro config.
Annotate structure with this macro and a field of it with the source attribute, so the field will be searched in one of the provided sources. The sources can be provided by using the following nested source attributes: \

  1. clap: command line argument
  2. env: environment variable
  3. config: configuration file key
  4. default: default value

Example

use config_manager::config;

#[config]
struct ApplicationConfig {
    #[source(clap(long, short = 'p'), env = "APP_MODEL_PATH", config)]
    model_path: String,
    #[source(env, config, default = 0)]
    prediction_delay: u64,
}

In the example above, to set the value of the model_path field, a user may provide:

  • command line argument --model_path
  • environment variable named model_path
  • configuration file containing field model_path

If the value is found in multiple provided sources, the value will be assigned according to the provided order (the order for the model_path field is clap -> env -> config and env -> config -> default for the prediction_delay).
If none of them (including the default value) is found, the program returns error MissingArgument.

Note: the default value is always assigned last.

§Attributes documentation

For further understanding of project syntax and features, it is recommended to visit Cookbook.

§Complex example

use std::collections::HashMap;

use config_manager::{config, ConfigInit};

const SUFFIX: &str = "_env";
/// This doc will be included to CLI long_about.
#[derive(Debug)]
#[config(
    clap(version, author, long_about),
    env_prefix = "demo",
    file(
        format = "toml",
        clap(long = "config", short = 'c', help = "path to configuration file"),
        env = "demo_config",
        default = "./config.toml"
    )
)]
struct MethodConfig {
    /// This doc will be included to CLI help.
    #[source(clap(long, short, help))]
    a: i32,
    #[source(
        env(init_from = &format!("b{}", SUFFIX)),
        default = "abc"
    )]
    b: String,
    #[source(config = "bpm")]
    c: i32,
    #[source(default = HashMap::new())]
    d: HashMap<i32, String>,
}

fn main() {
    dbg!(MethodConfig::parse().unwrap());
}

Run in the repository

cargo run --package examples --bin demo -- --config="examples/config.toml" --a=5

Result must be:

[examples/src/demo.rs:34] &*CFG = MethodConfig {
    a: 5,
    b: "qwerty",
    c: 165,
    d: {},
}

Modules§

__cookbook
Documentation: Cookbook

Structs§

FileOptions
Description of the configuration file.

Enums§

ClapSource
Replacement of the command line source.
ConfigOption
Settings to build an instance of a struct, implementing ConfigInit.
Error
Runtime initializing error.
Source
Replacement of the usual source to find values for the fields.

Traits§

ConfigInit
Config trait that constructs an instance of itself from environment, command line and configuration files. \

Type Aliases§

ConfigOptions
Set of rules to build an instance of the annotated by #[config] structure.
FileFormat
Allowed formats for the configuration files.

Attribute Macros§

config
Macro generating an implementation of the ConfigInit trait or constructing global variable. \

Derive Macros§

Flatten
Annotated with this macro structure can be used as a flatten argument in the config macro.