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

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

source

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.

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

source

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§

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,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

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

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.
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.
source§

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

Performs the conversion.