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

from_static_map

Macro to generate config instance from a map of key-value pairs. The keys in the map are config keys, e.g. “port”. The values in the map are string values, e.g. “8080”. This macro will panic if any required config is missing or if any config value cannot be parsed into the expected type.

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.

Functions

from_env

Generate config instance from environment variables. The prefix is used to scope the config keys, e.g. “CFG_APP”. This function will return an error if any required config is missing or if any config value cannot be parsed into the expected type.

from_map

Generate config instance from a map of key-value pairs. The keys in the map are full config keys, e.g. “cfg.app.port”. The values in the map are string values, e.g. “8080”. The prefix is used to scope the config keys, e.g. “cfg.app”. This function will return an error if any required config is missing or if any config value cannot be parsed into the expected type.

Type Aliases

ConfigKey

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

Derive Macros

FromConfig

Automatic derive FromConfig instance.