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

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 alaways 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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.