[−][src]Trait spirit::cfg_loader::ConfigBuilder

pub trait ConfigBuilder: Sized {
    fn config_default_paths<P, I>(self, paths: I) -> Self
    where
        I: IntoIterator<Item = P>,
        P: Into<PathBuf>;

    fn config_defaults<D: Into<String>>(self, config: D) -> Self;

    fn config_env<E: Into<String>>(self, env: E) -> Self;

    fn config_filter<F: FnMut(&Path) -> bool + Send + 'static>(
        self, 
        filter: F
    ) -> Self;

    fn warn_on_unused(self, warn: bool) -> Self;

    fn config_defaults_typed<C: Serialize>(
        self, 
        config: &C
    ) -> Result<Self, AnyError> { ... }

    fn config_ext<E: Into<OsString>>(self, ext: E) -> Self { ... }

    fn config_exts<I, E>(self, exts: I) -> Self
    where
        I: IntoIterator<Item = E>,
        E: Into<OsString>,
    { ... }

    fn config_supported_exts(self) -> Self { ... }
}

Interface for configuring configuration loading options.

This is the common interface of cfg_loader::Builder and spirit Builder for configuring how and where from should configuration be loaded. The methods are available on both and do the same thing.

The interface is also implemented on Result<ConfigBuilder, AnyError>. This is both for convenience and for gathering errors to be handled within SpiritBuilder::run in uniform way.

Required methods

fn config_default_paths<P, I>(self, paths: I) -> Self where
    I: IntoIterator<Item = P>,
    P: Into<PathBuf>, 

Sets the configuration paths in case the user doesn't provide any.

This replaces any previously set default paths. If none are specified and the user doesn't specify any either, no config is loaded (but it is not an error in itself, simply the defaults will be used, if available).

This has no effect if the user does provide configuration paths on the command line.

fn config_defaults<D: Into<String>>(self, config: D) -> Self

Specifies the default configuration.

This „loads“ the lowest layer of the configuration from the passed string. The expected format is TOML.

Any user-provided configuration will be layered on top of it.

An alternative is to supply the lowest layer through the config_defaults_typed ‒ only the last one of the two wins.

fn config_env<E: Into<String>>(self, env: E) -> Self

Enables loading configuration from environment variables.

If this is used, after loading the normal configuration files, the environment of the process is examined. Variables with the provided prefix are merged into the configuration.

Examples

use serde::Deserialize;
use spirit::{AnyError, Empty};
use spirit::cfg_loader::{Builder, ConfigBuilder};

#[derive(Default, Deserialize)]
struct Cfg {
    message: String,
}

const DEFAULT_CFG: &str = r#"
message = "Hello"
"#;

fn main() -> Result<(), AnyError> {
    let (_, mut loader) = Builder::new()
        .config_defaults(DEFAULT_CFG)
        .config_env("HELLO")
        .build::<Empty>();
    let cfg: Cfg = loader.load()?;
    println!("{}", cfg.message);
    Ok(())
}

If run like this, it'll print Hi. The environment takes precedence ‒ even if there was configuration file and it set the message, the Hi here would win.

HELLO_MESSAGE="Hi" ./hello

fn config_filter<F: FnMut(&Path) -> bool + Send + 'static>(
    self,
    filter: F
) -> Self

Sets a configuration dir filter.

If the user passes a directory path instead of a file path, the directory is traversed (every time the configuration is reloaded, so if files are added or removed, it is reflected) and files passing this filter are merged into the configuration, in the lexicographical order of their file names.

There's ever only one filter and the default one passes no files (therefore, directories are ignored by default).

The filter has no effect on files passed directly, only on loading directories. Only files directly in the directory are loaded ‒ subdirectories are not traversed.

For more convenient ways to set the filter, see config_ext and config_exts.

fn warn_on_unused(self, warn: bool) -> Self

Sets if warning should be produced for each unused configuration key.

If set, a warning message is produced upon loading a configuration for each unused key. Note that this might not always work reliably.

The default is true.

Loading content...

Provided methods

fn config_defaults_typed<C: Serialize>(
    self,
    config: &C
) -> Result<Self, AnyError>

Specifies the default configuration as typed value.

This is an alternative to config_defaults. Unlike that one, this accepts a typed instance of the configuration ‒ the configuration structure.

The advantage is there's less risk of typos or malformed input and sometimes convenience. This is, however, less flexible as this needs a complete configuration, while config_defaults accepts even configurations that are missing some fields. In such case, defaults would be used (if they are available on the Deserialize level) or the configuration would fail if the user provided configuration files don't contain it.

Note that pairing between the type passed here and the type of configuration structure extracted later is not tied together at compile time (as this allows a workaround for the above described inflexibility, but also because tying them together would be too much work for very little benefit ‒ it's not likely there would be two different configuration structures in the same program and got mixed up).

Examples

use serde::{Deserialize, Serialize};
use spirit::AnyError;
use spirit::cfg_loader::{Builder, ConfigBuilder};

#[derive(Default, Deserialize, Serialize)]
struct Cfg {
    #[serde(default)]
    message: String,
}

fn main() -> Result<(), AnyError> {
    let mut loader = Builder::new()
        .config_defaults_typed(&Cfg {
            message: "hello".to_owned()
        })
        // Expect, as error here would mean a bug, not bad external conditions.
        .expect("Invalid default configuration")
        .build_no_opts();
    let cfg: Cfg = loader.load()?;
    assert_eq!(cfg.message, "hello");
    Ok(())
}

fn config_ext<E: Into<OsString>>(self, ext: E) -> Self

Configures a config dir filter for a single extension.

Sets the config directory filter (see config_filter) to one matching this single extension.

fn config_exts<I, E>(self, exts: I) -> Self where
    I: IntoIterator<Item = E>,
    E: Into<OsString>, 

Configures a config dir filter for multiple extensions.

Sets the config directory filter (see config_filter) to one matching files with any of the provided extensions.

fn config_supported_exts(self) -> Self

Sets the config dir filter for all the supported extensions.

Note that the list of extensions depends on the enabled features.

Loading content...

Implementations on Foreign Types

impl<C: ConfigBuilder, Error> ConfigBuilder for Result<C, Error>[src]

Loading content...

Implementors

impl ConfigBuilder for spirit::cfg_loader::Builder[src]

impl<O, C> ConfigBuilder for spirit::Builder<O, C>[src]

Loading content...