Struct config::builder::ConfigBuilder

pub struct ConfigBuilder<St: BuilderState> { /* private fields */ }

A configuration builder

It registers ordered sources of configuration to later build consistent Config from them. Configuration sources it defines are defaults, Sources and overrides.

Defaults are always loaded first and can be overwritten by any of two other sources. Overrides are always loaded last, thus cannot be overridden. Both can be only set explicitly key by key in code using set_default or set_override.

An intermediate category, Source, set groups of keys at once implicitly using data coming from external sources like files, environment variables or others that one implements. Defining a Source is as simple as implementing a trait for a struct.

Adding sources, setting defaults and overrides does not invoke any I/O nor builds a config. It happens on demand when build (or its alternative) is called. Therefore all errors, related to any of the Source will only show up then.

Sync and async builder

ConfigBuilder uses type parameter to keep track of builder state.

In DefaultState builder only supports Sources

In AsyncState it supports both Sources and AsyncSources at the price of building using async fn.

Examples

let mut builder = Config::builder()
    .set_default("default", "1")?
    .add_source(File::new("config/settings", FileFormat::Json))
//  .add_async_source(...)
    .set_override("override", "1")?;

match builder.build() {
    Ok(config) => {
        // use your config
    },
    Err(e) => {
        // something went wrong
    }
}

If any AsyncSource is used, the builder will transition to AsyncState. In such case, it is required to await calls to build and its non-consuming sibling.

Calls can be not chained as well

let mut builder = Config::builder();
builder = builder.set_default("default", "1")?;
builder = builder.add_source(File::new("config/settings", FileFormat::Json));
builder = builder.add_source(File::new("config/settings.prod", FileFormat::Json));
builder = builder.set_override("override", "1")?;

Calling Config::builder yields builder in the default state. If having an asynchronous state as the initial state is desired, turbofish notation needs to be used.

let mut builder = ConfigBuilder::<AsyncState>::default();

If for some reason acquiring builder in default state is required without calling Config::builder it can also be achieved.

let mut builder = ConfigBuilder::<DefaultState>::default();

Implementations

impl<St: BuilderState> ConfigBuilder<St>

pub fn set_default<S, T>(self, key: S, value: T) -> Result<Self, ConfigError>

where S: AsRef<str>, T: Into<Value>,

Set a default value at key

This value can be overwritten by any Source, AsyncSource or override.

Errors

Fails if Expression::from_str(key) fails.

pub fn set_override<S, T>(self, key: S, value: T) -> Result<Self, ConfigError>

where S: AsRef<str>, T: Into<Value>,

Set an override

This function sets an overwrite value. It will not be altered by any default, Source nor AsyncSource

Errors

Fails if Expression::from_str(key) fails.

pub fn set_override_option<S, T>( self, key: S, value: Option<T> ) -> Result<Self, ConfigError>

where S: AsRef<str>, T: Into<Value>,

Sets an override if value is Some(_)

This function sets an overwrite value if Some(_) is passed. If None is passed, this function does nothing. It will not be altered by any default, Source nor AsyncSource

Errors

Fails if Expression::from_str(key) fails.

impl ConfigBuilder<DefaultState>

pub fn add_source<T>(self, source: T) -> Self

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

Registers new Source in this builder.

Calling this method does not invoke any I/O. Source is only saved in internal register for later use.

pub fn add_async_source<T>(self, source: T) -> ConfigBuilder<AsyncState>

where T: AsyncSource + Send + Sync + 'static,

Registers new AsyncSource in this builder and forces transition to AsyncState.

Calling this method does not invoke any I/O. AsyncSource is only saved in internal register for later use.

pub fn build(self) -> Result<Config, ConfigError>

Reads all registered Sources.

This is the method that invokes all I/O operations. For a non consuming alternative see build_cloned

Errors

If source collection fails, be it technical reasons or related to inability to read data as Config for different reasons, this method returns error.

pub fn build_cloned(&self) -> Result<Config, ConfigError>

Reads all registered Sources.

Similar to build, but it does not take ownership of ConfigBuilder to allow later reuse. Internally it clones data to achieve it.

Errors

If source collection fails, be it technical reasons or related to inability to read data as Config for different reasons, this method returns error.

impl ConfigBuilder<AsyncState>

pub fn add_source<T>(self, source: T) -> Self

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

Registers new Source in this builder.

Calling this method does not invoke any I/O. Source is only saved in internal register for later use.

pub fn add_async_source<T>(self, source: T) -> Self

where T: AsyncSource + Send + Sync + 'static,

Registers new AsyncSource in this builder.

Calling this method does not invoke any I/O. AsyncSource is only saved in internal register for later use.

pub async fn build(self) -> Result<Config, ConfigError>

Reads all registered defaults, Sources, AsyncSources and overrides.

This is the method that invokes all I/O operations. For a non consuming alternative see build_cloned

Errors

If source collection fails, be it technical reasons or related to inability to read data as Config for different reasons, this method returns error.

pub async fn build_cloned(&self) -> Result<Config, ConfigError>

Reads all registered defaults, Sources, AsyncSources and overrides.

Similar to build, but it does not take ownership of ConfigBuilder to allow later reuse. Internally it clones data to achieve it.

Errors

If source collection fails, be it technical reasons or related to inability to read data as Config for different reasons, this method returns error.

Trait Implementations

impl<St: Clone + BuilderState> Clone for ConfigBuilder<St>

fn clone(&self) -> ConfigBuilder<St>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<St: Debug + BuilderState> Debug for ConfigBuilder<St>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<St: Default + BuilderState> Default for ConfigBuilder<St>

fn default() -> ConfigBuilder<St>

Returns the “default value” for a type.