# Struct config::builder::ConfigBuilder

source · [−]

    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, `Source`s 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 `Source`s

In `AsyncState` it supports both `Source`s and `AsyncSource`s 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

source

### impl<St: BuilderState> ConfigBuilder<St>

source

#### 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.

source

#### 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.

source

#### 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.

source

### impl ConfigBuilder<DefaultState>

source

#### 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.

source

#### 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.

source

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

Reads all registered `Source`s.

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.

source

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

Reads all registered `Source`s.

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.

source

### impl ConfigBuilder<AsyncState>

source

#### 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.

source

#### 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.

source

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

Reads all registered defaults, `Source`s, `AsyncSource`s 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.

source

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

Reads all registered defaults, `Source`s, `AsyncSource`s 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

source

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

source

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

Returns a copy of the value. Read more

1.0.0 · source

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

Performs copy-assignment from `source`. Read more

source

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

source

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

Formats the value using the given formatter. Read more

source

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

source

#### fn default() -> ConfigBuilder<St>

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

## Auto Trait Implementations

### impl<St> RefUnwindSafe for ConfigBuilder<St> where
St: RefUnwindSafe,

### impl<St> Send for ConfigBuilder<St> where
St: Send,

### impl<St> Sync for ConfigBuilder<St> where
St: Sync,

### impl<St> Unpin for ConfigBuilder<St> where
St: Unpin,

### impl<St> UnwindSafe for ConfigBuilder<St> where
St: UnwindSafe,

## Blanket Implementations

source

### impl<T> Any for T where
T: 'static + ?Sized,

source

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more

source

### impl<T> Borrow<T> for T where
T: ?Sized,

const: unstable · source

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

source

### impl<T> BorrowMut<T> for T where
T: ?Sized,

const: unstable · source

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

source

### impl<T> From<T> for T

const: unstable · source

#### fn from(t: T) -> T

Returns the argument unchanged.

source

### impl<T, U> Into<U> for T where
U: From<T>,

const: unstable · source

#### fn into(self) -> U

Calls `U::from(self)`.

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

source

### impl<T> ToOwned for T where
T: Clone,

#### type Owned = T

The resulting type after obtaining ownership.

source

#### fn to_owned(&self) -> T

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

source

#### fn clone_into(&self, target: &mut T)

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

source

### impl<T, U> TryFrom<U> for T where
U: Into<T>,

#### type Error = Infallible

The type returned in the event of a conversion error.

const: unstable · source

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.

source

### impl<T, U> TryInto<U> for T where
U: TryFrom<T>,

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

const: unstable · source

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.