Crate cfg_rs

cfg-rs: A Configuration Library for Rust Applications

Major Features

• One method to get all config objects, see get.
• Automatic derive config object, see FromConfig.
• Support default value for config object by auto deriving, see derived attr.
• Config value placeholder parsing, e.g. ${config.key}, see placeholder.
• Random config value, e.g. configuration.get::<u8>("random.u8") will get random u8 value.
• Support refreshable value type RefValue, it can be updated when refreshing.
• Support refresh Configuration.
• Easy to use, easy to add new config source, easy to organize configuration, see register_source.¹
• Not dependent with serde.

See the examples for general usage information.

Supported File Format

• Toml: toml, tml
• Yaml: yaml, yml
• Json: json
• Ini: ini

How to Initialize Configuration

• Use Predefined Source Configuration in One Line

use cfg_rs::*;
let configuration = Configuration::with_predefined().unwrap();
// use configuration.

See init for details.

• Customize Predefined Source Configuration Builder

use cfg_rs::*;
init_cargo_env!();
let configuration = Configuration::with_predefined_builder()
    .set_cargo_env(init_cargo_env())
    .init()
    .unwrap();
// use configuration.

See init for details.

• Organize Your Own Sources

use cfg_rs::*;
init_cargo_env!();
let mut configuration = Configuration::new()
    // Layer 0: Register cargo env config source.
    .register_source(init_cargo_env()).unwrap()
    // Layer 1: Register customized config.
    .register_kv("customized_config")
        .set("hello", "world")
        .finish()
        .unwrap();
    // Layer 2: Register random value config.
#[cfg(feature = "rand")]
{
configuration = configuration.register_random().unwrap();
}
    // Layer 3: Register all env variables `CFG_*`.
configuration = configuration.register_prefix_env("CFG").unwrap()
    // Layer 4: Register yaml file(Need feature yaml).
    .register_file("/conf/app.yaml", true).unwrap();

#[cfg(feature = "toml")]
{
    let toml = inline_source!("../app.toml").unwrap();
    configuration = configuration.register_source(toml).unwrap();
}

// use configuration.

See register_kv, register_file, register_random, register_prefix_env for details.

---

1. Config order is determined by the order of registering sources, register earlier have higher priority. ↩

Modules

source

Configuration sources module, see the examples for general usage information.

Macros

impl_enum

Implement FromConfig for enums.

init_cargo_env

Collect all CARGO_PKG_* env variables, and CARGO_BIN_NAME into configuration.

inline_source

Inline config file in repo, see Supported File Formats.

Structs

ConfigContext

Configuration Context.

Configuration

Configuration Instance, See Examples, How to Initialize Configuration for details.

FromStrHolder

Wrapper for all FromStr type.

PredefinedConfigurationBuilder

Predefined Configuration Builder. See init for details.

RefValue

RefValue means reference of value or refreshable value, it holds a value which can be updated when Configuration is refreshed.

Enums

ConfigError

Configuration Error.

ConfigValue

Config value, ConfigSource use this value to store config properties.

Traits

FromConfig

Generate config instance from configuration.

FromConfigWithPrefix

Config with prefix. This trait is auto derived by FromConfig.

FromStringValue

Get from string.

Type Aliases

ConfigKey

Config key, ConfigSource use this key to access config properties.

Derive Macros

FromConfig

Automatic derive FromConfig instance.