Struct Config 

pub struct Config { /* private fields */ }

A builder that collects Sources in priority order, then merges them.

Sources are applied in the order they are added; a later source overrides an earlier one for any leaf it sets. Unset leaves keep the earlier value, and a leaf no source sets falls back to the compiled-in defaults layer.

// `EXTRA` is added after `BASE`, so it wins for `host`.
let settings = Config::new()
    .add_env("BASE")
    .add_env("EXTRA")
    .build::<SettingsProv>()
    .unwrap();

assert_eq!(settings.host.value(), "from-extra");

Implementations

impl Config

pub fn new() -> Config

Create a Config with no sources yet.

pub fn add_source<S>(self, source: S) -> Config

where S: Source + Send + Sync + 'static,

Append any custom Source. The typed add_* helpers wrap the built-in sources; reach for this to plug in your own.

pub fn add_toml_file(self, path: impl AsRef<Path>) -> Result<Config, Error>

Add a TOML file source. The file is read immediately; a read failure is surfaced as Error::Io.

Errors

Returns Error::Io if path cannot be read.

pub fn add_toml_str( self, name: impl Into<String>, content: impl Into<String>, ) -> Config

Add an in-memory TOML source. name is a human-readable label used in error messages.

let settings = Config::new()
    .add_toml_str("app.toml", "host = \"localhost\"\nport = 8080")
    .build::<SettingsProv>()
    .unwrap();

assert_eq!(settings.host.value(), "localhost");
assert_eq!(settings.host.source().category(), Category::File);

pub fn add_env(self, prefix: impl AsRef<str>) -> Config

Add an environment-variable source reading <PREFIX>_* variables. Nested fields use __ as the separator. The variables are read now, not when the config is built.

let settings = Config::new()
    .add_env("MYAPP")
    .build::<SettingsProv>()
    .unwrap();

assert_eq!(settings.host.value(), "db.internal");
assert_eq!(settings.host.source().category(), Category::Env);

pub fn add_env_with_list_keys<I, S>( self, prefix: impl AsRef<str>, list_keys: I, ) -> Config

where I: IntoIterator<Item = S>, S: Into<String>,

Add an environment-variable source where the given dotted paths are treated as comma-separated lists. See sources::EnvSource::with_list_keys.

// `SVC_HOSTS` is a comma-separated list; name it so the source splits it.
let settings = Config::new()
    .add_env_with_list_keys("SVC", ["hosts"])
    .build::<SettingsProv>()
    .unwrap();

assert_eq!(settings.hosts.value(), &["a.example", "b.example"]);

pub fn add_cli<P>(self, partial: P) -> Config

where P: Serialize + Send + Sync + 'static,

Add a CLI source from a pre-built partial (every field an Option). Typically produced from clap via the provcfg-clap ClapArgs derive.

let from_cli = SettingsPartial { host: Some("cli.example".to_string()), port: None };

let settings = Config::new()
    .add_cli(from_cli)
    .build::<SettingsProv>()
    .unwrap();

assert_eq!(settings.host.value(), "cli.example");
assert_eq!(settings.host.source().category(), Category::Cli);
// `port` was `None` on the partial, so it falls back to the default.
assert_eq!(settings.port.source().category(), Category::Default);

pub fn build<T>(&self) -> Result<T, Error>

where T: Provenance,

Merge every added source plus the implicit defaults layer into T, a generated *Prov struct.

Errors

Returns Error::Deserialize if a source’s data does not fit T.

Trait Implementations

impl Default for Config

fn default() -> Config

Returns the “default value” for a type.