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 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 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
sourceimpl<St: BuilderState> ConfigBuilder<St>
impl<St: BuilderState> ConfigBuilder<St>
sourcepub fn set_default<S, T>(self, key: S, value: T) -> Result<Self, ConfigError> where
S: AsRef<str>,
T: Into<Value>,
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.
sourcepub fn set_override<S, T>(self, key: S, value: T) -> Result<Self, ConfigError> where
S: AsRef<str>,
T: Into<Value>,
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.
sourceimpl ConfigBuilder<DefaultState>
impl ConfigBuilder<DefaultState>
sourcepub fn add_source<T>(self, source: T) -> Self where
T: Source + Send + Sync + 'static,
pub fn add_source<T>(self, source: T) -> Self where
T: Source + Send + Sync + 'static,
sourcepub fn add_async_source<T>(self, source: T) -> ConfigBuilder<AsyncState> where
T: AsyncSource + Send + Sync + 'static,
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.
sourcepub fn build(self) -> Result<Config, ConfigError>
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.
sourcepub fn build_cloned(&self) -> Result<Config, ConfigError>
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.
sourceimpl ConfigBuilder<AsyncState>
impl ConfigBuilder<AsyncState>
sourcepub fn add_source<T>(self, source: T) -> Self where
T: Source + Send + Sync + 'static,
pub fn add_source<T>(self, source: T) -> Self where
T: Source + Send + Sync + 'static,
sourcepub fn add_async_source<T>(self, source: T) -> Self where
T: AsyncSource + Send + Sync + 'static,
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.
sourcepub async fn build(self) -> Result<Config, ConfigError>
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.
sourcepub async fn build_cloned(&self) -> Result<Config, ConfigError>
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
sourceimpl<St: Clone + BuilderState> Clone for ConfigBuilder<St>
impl<St: Clone + BuilderState> Clone for ConfigBuilder<St>
sourcefn clone(&self) -> ConfigBuilder<St>
fn clone(&self) -> ConfigBuilder<St>
Returns a copy of the value. Read more
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
sourceimpl<St: Debug + BuilderState> Debug for ConfigBuilder<St>
impl<St: Debug + BuilderState> Debug for ConfigBuilder<St>
sourceimpl<St: Default + BuilderState> Default for ConfigBuilder<St>
impl<St: Default + BuilderState> Default for ConfigBuilder<St>
sourcefn default() -> ConfigBuilder<St>
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
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more