Struct sea_orm_rocket::figment::Figment

pub struct Figment { /* private fields */ }

Expand description

Combiner of Providers for configuration value extraction.

Overview

A Figment combines providers by merging or joining their provided data. The combined value or a subset of the combined value can be extracted into any type that implements Deserialize. Additionally, values can be nested in profiles, and a profile can be selected via Figment::select() for extraction; the profile to be extracted can be retrieved with Figment::profile() and defaults to Profile::Default. The top-level docs contain a broad overview of these topics.

Merging vs. Joining

Merging and joining control whether duplicate values are replaced or discarded. A merged value replaces an existing value with the same key, while a joined value is discarded if a value with the same key exists:

use figment::Figment;

let figment = Figment::from(("key", "original"));

let original: String = figment.extract_inner("key").unwrap();
assert_eq!(original, "original");

let figment = figment.merge(("key", "replaced"));
let replaced: String = figment.extract_inner("key").unwrap();
assert_eq!(replaced, "replaced");

let figment = figment.join(("key", "joined"));
let joined: String = figment.extract_inner("key").unwrap();
assert_eq!(joined, "replaced");

Extraction

The configuration or a subset thereof can be extracted from a Figment in one of several ways:

Figment::extract(), which extracts the complete value into any T: Deserialize.
Figment::extract_inner(), which extracts a subset of the value for a given key path.
Figment::find_value(), which returns the raw, serialized Value for a given key path.

A “key path” is a string of the form a.b.c (e.g, item, item.fruits, etc.) where each component delimited by a . is a key for the dictionary of the preceding key in the path, or the root dictionary if it is the first key in the path. See Value::find() for examples.

Metadata

Every value collected by a Figment is accompanied by the metadata produced by the value’s provider. Additionally, Metadata::provide_location is set by from, merge and join to the caller’s location. Metadata can be retrieved in one of several ways:

Figment::metadata(), which returns an iterator over all of the metadata for all values.
Figment::find_metadata(), which returns the metadata for a value at a given key path.
Figment::get_metadata(), which returns the metadata for a given Tag, itself retrieved via Tagged or Value::tag().

Implementations

impl Figment

pub fn new() -> Figment

Creates a new Figment with the default profile selected and no providers.

use figment::Figment;

let figment = Figment::new();
assert_eq!(figment.metadata().count(), 0);

pub fn from<T>(provider: T) -> Figmentwhere
T: Provider,

Creates a new Figment with the default profile selected and an initial provider.

use figment::Figment;
use figment::providers::Env;

let figment = Figment::from(Env::raw());
assert_eq!(figment.metadata().count(), 1);

pub fn join<T>(self, provider: T) -> Figmentwhere
T: Provider,

Joins provider into the current figment. See merging vs. joining for details.

use figment::Figment;
use figment::providers::Env;

let figment = Figment::new().join(Env::raw());
assert_eq!(figment.metadata().count(), 1);

pub fn merge<T>(self, provider: T) -> Figmentwhere
T: Provider,

Merges provider into the current figment. See merging vs. joining for details.

use figment::Figment;
use figment::providers::Env;

let figment = Figment::new().merge(Env::raw());
assert_eq!(figment.metadata().count(), 1);

pub fn select(self, profile: P) -> Figmentwhere
P: Into<Profile>,

Sets the profile to extract from to profile.

Example

use figment::Figment;

let figment = Figment::new().select("staging");
assert_eq!(figment.profile(), "staging");

pub fn focus(&self, key: &str) -> Figment

Returns a new Figment containing only the sub-dictionaries at key.

This “sub-figment” is a focusing of self with the property that:

self.find(key + ".sub") <=> focused.find("sub")

In other words, all values in self with a key starting with key are in focused without the prefix and vice-versa.

Example

use figment::{Figment, providers::{Format, Toml}};

figment::Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#"
        cat = [1, 2, 3]
        dog = [4, 5, 6]

        [subtree]
        cat = "meow"
        dog = "woof!"

        [subtree.bark]
        dog = true
        cat = false
    "#)?;

    let root = Figment::from(Toml::file("Config.toml"));
    assert_eq!(root.extract_inner::<Vec<u8>>("cat").unwrap(), vec![1, 2, 3]);
    assert_eq!(root.extract_inner::<Vec<u8>>("dog").unwrap(), vec![4, 5, 6]);
    assert_eq!(root.extract_inner::<String>("subtree.cat").unwrap(), "meow");
    assert_eq!(root.extract_inner::<String>("subtree.dog").unwrap(), "woof!");

    let subtree = root.focus("subtree");
    assert_eq!(subtree.extract_inner::<String>("cat").unwrap(), "meow");
    assert_eq!(subtree.extract_inner::<String>("dog").unwrap(), "woof!");
    assert_eq!(subtree.extract_inner::<bool>("bark.cat").unwrap(), false);
    assert_eq!(subtree.extract_inner::<bool>("bark.dog").unwrap(), true);

    let bark = subtree.focus("bark");
    assert_eq!(bark.extract_inner::<bool>("cat").unwrap(), false);
    assert_eq!(bark.extract_inner::<bool>("dog").unwrap(), true);

    let not_a_dict = root.focus("cat");
    assert!(not_a_dict.extract_inner::<bool>("cat").is_err());
    assert!(not_a_dict.extract_inner::<bool>("dog").is_err());

    Ok(())
});

pub fn extract<'a, T>(&self) -> Result<T, Error>where
T: Deserialize<'a>,

Deserializes the collected value into T.

Example

use serde::Deserialize;

use figment::{Figment, providers::{Format, Toml, Json, Env}};

#[derive(Debug, PartialEq, Deserialize)]
struct Config {
    name: String,
    numbers: Option<Vec<usize>>,
    debug: bool,
}

figment::Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#"
        name = "test"
        numbers = [1, 2, 3, 10]
    "#)?;

    jail.set_env("config_name", "env-test");

    jail.create_file("Config.json", r#"
        {
            "name": "json-test",
            "debug": true
        }
    "#)?;

    let config: Config = Figment::new()
        .merge(Toml::file("Config.toml"))
        .merge(Env::prefixed("CONFIG_"))
        .join(Json::file("Config.json"))
        .extract()?;

    assert_eq!(config, Config {
        name: "env-test".into(),
        numbers: vec![1, 2, 3, 10].into(),
        debug: true
    });

    Ok(())
});

pub fn extract_inner<'a, T>(&self, key: &str) -> Result<T, Error>where
T: Deserialize<'a>,

Deserializes the value at the key path in the collected value into T.

Example

use figment::{Figment, providers::{Format, Toml, Json}};

figment::Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#"
        numbers = [1, 2, 3, 10]
    "#)?;

    jail.create_file("Config.json", r#"{ "debug": true } "#)?;

    let numbers: Vec<usize> = Figment::new()
        .merge(Toml::file("Config.toml"))
        .join(Json::file("Config.json"))
        .extract_inner("numbers")?;

    assert_eq!(numbers, vec![1, 2, 3, 10]);

    Ok(())
});

pub fn metadata(&self) -> impl Iterator<Item = &Metadata>

Returns an iterator over the metadata for all of the collected values in the order in which they were added to self.

Example

use figment::{Figment, providers::{Format, Toml, Json}};

let figment = Figment::new()
    .merge(Toml::file("Config.toml"))
    .join(Json::file("Config.json"));

assert_eq!(figment.metadata().count(), 2);
for (i, md) in figment.metadata().enumerate() {
    match i {
        0 => assert!(md.name.starts_with("TOML")),
        1 => assert!(md.name.starts_with("JSON")),
        _ => unreachable!(),
    }
}

pub fn profile(&self) -> &Profile

Returns the selected profile.

Example

use figment::Figment;

let figment = Figment::new();
assert_eq!(figment.profile(), "default");

let figment = figment.select("staging");
assert_eq!(figment.profile(), "staging");

pub fn profiles(&self) -> impl Iterator<Item = &Profile>

Returns an iterator over profiles with valid configurations in this figment. Note: this may not include the selected profile if the selected profile has no configured values.

Example

use figment::{Figment, providers::Serialized};

let figment = Figment::new();
let profiles = figment.profiles().collect::<Vec<_>>();
assert_eq!(profiles.len(), 0);

let figment = Figment::new()
    .join(Serialized::default("key", "hi"))
    .join(Serialized::default("key", "hey").profile("debug"));

let mut profiles = figment.profiles().collect::<Vec<_>>();
profiles.sort();
assert_eq!(profiles, &["debug", "default"]);

let figment = Figment::new()
    .join(Serialized::default("key", "hi").profile("release"))
    .join(Serialized::default("key", "hi").profile("testing"))
    .join(Serialized::default("key", "hey").profile("staging"))
    .select("debug");

let mut profiles = figment.profiles().collect::<Vec<_>>();
profiles.sort();
assert_eq!(profiles, &["release", "staging", "testing"]);

pub fn find_value(&self, key: &str) -> Result<Value, Error>

Finds the value at key path in the combined value. See Value::find() for details on the syntax for key.

Example

use serde::Deserialize;

use figment::{Figment, providers::{Format, Toml, Json, Env}};

figment::Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#"
        name = "test"

        [package]
        name = "my-package"
    "#)?;

    jail.create_file("Config.json", r#"
        {
            "author": { "name": "Bob" }
        }
    "#)?;

    let figment = Figment::new()
        .merge(Toml::file("Config.toml"))
        .join(Json::file("Config.json"));

    let name = figment.find_value("name")?;
    assert_eq!(name.as_str(), Some("test"));

    let package_name = figment.find_value("package.name")?;
    assert_eq!(package_name.as_str(), Some("my-package"));

    let author_name = figment.find_value("author.name")?;
    assert_eq!(author_name.as_str(), Some("Bob"));

    Ok(())
});

pub fn find_metadata(&self, key: &str) -> Option<&Metadata>

Finds the metadata for the value at key path. See Value::find() for details on the syntax for key.

Example

use serde::Deserialize;

use figment::{Figment, providers::{Format, Toml, Json, Env}};

figment::Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#" name = "test" "#)?;
    jail.set_env("CONF_AUTHOR", "Bob");

    let figment = Figment::new()
        .merge(Toml::file("Config.toml"))
        .join(Env::prefixed("CONF_").only(&["author"]));

    let name_md = figment.find_metadata("name").unwrap();
    assert!(name_md.name.starts_with("TOML"));

    let author_md = figment.find_metadata("author").unwrap();
    assert!(author_md.name.contains("CONF_"));
    assert!(author_md.name.contains("environment"));

    Ok(())
});

pub fn get_metadata(&self, tag: Tag) -> Option<&Metadata>

Returns the metadata with the given tag if this figment contains a value with said metadata.

Example

use serde::Deserialize;

use figment::{Figment, providers::{Format, Toml, Json, Env}};

figment::Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#" name = "test" "#)?;
    jail.create_file("Config.json", r#" { "author": "Bob" } "#)?;

    let figment = Figment::new()
        .merge(Toml::file("Config.toml"))
        .join(Json::file("Config.json"));

    let name = figment.find_value("name").unwrap();
    let metadata = figment.get_metadata(name.tag()).unwrap();
    assert!(metadata.name.starts_with("TOML"));

    let author = figment.find_value("author").unwrap();
    let metadata = figment.get_metadata(author.tag()).unwrap();
    assert!(metadata.name.starts_with("JSON"));

    Ok(())
});

Trait Implementations

impl Clone for Figment

fn clone(&self) -> Figment

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

impl Debug for Figment

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

Formats the value using the given formatter. Read more

impl Default for Figment

fn default() -> Figment

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

impl Provider for Figment

fn metadata(&self) -> Metadata

Returns the Metadata for this provider, identifying itself and its configuration sources. Read more

fn data(
&self
) -> Result<BTreeMap<Profile, BTreeMap<String, Value, Global>, Global>, Error>

Returns the configuration data.

fn profile(&self) -> Option<Profile>

Optionally returns a profile to set on the Figment this provider is merged into. The profile is only set if self is merged. Read more

Auto Trait Implementations

impl !RefUnwindSafe for Figment

impl Send for Figment

Struct sea_orm_rocket::figment::Figment

Implementations

impl Figment

pub fn new() -> Figment

pub fn from<T>(provider: T) -> Figmentwhere T: Provider,

pub fn join<T>(self, provider: T) -> Figmentwhere T: Provider,

pub fn merge<T>(self, provider: T) -> Figmentwhere T: Provider,

pub fn select<P>(self, profile: P) -> Figmentwhere P: Into<Profile>,

pub fn focus(&self, key: &str) -> Figment

pub fn extract<'a, T>(&self) -> Result<T, Error>where T: Deserialize<'a>,

pub fn extract_inner<'a, T>(&self, key: &str) -> Result<T, Error>where T: Deserialize<'a>,

pub fn metadata(&self) -> impl Iterator<Item = &Metadata>

pub fn profile(&self) -> &Profile

pub fn profiles(&self) -> impl Iterator<Item = &Profile>

pub fn find_value(&self, key: &str) -> Result<Value, Error>

pub fn find_metadata(&self, key: &str) -> Option<&Metadata>

pub fn get_metadata(&self, tag: Tag) -> Option<&Metadata>

Trait Implementations

impl Clone for Figment

fn clone(&self) -> Figment

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

impl Debug for Figment

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

impl Default for Figment

fn default() -> Figment

impl Provider for Figment

fn metadata(&self) -> Metadata

fn data( &self) -> Result<BTreeMap<Profile, BTreeMap<String, Value, Global>, Global>, Error>

fn profile(&self) -> Option<Profile>

Auto Trait Implementations

impl !RefUnwindSafe for Figment

impl Send for Figment

impl Sync for Figment

impl Unpin for Figment

impl !UnwindSafe for Figment

Blanket Implementations

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

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Twhere T: ?Sized,

fn borrow(&self) -> &T

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

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

impl<T> DynClone for Twhere T: Clone,

fn __clone_box(&self, Private) -> *mut ()

impl<T> From<T> for T

fn from(t: T) -> T

impl<T> Instrument for T

fn instrument(self, span: Span) -> Instrumented<Self>

fn in_current_span(self) -> Instrumented<Self>

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

fn into(self) -> U

impl<T> IntoCollection<T> for T

fn into_collection<A>(self) -> SmallVec<A>where A: Array<Item = T>,

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>where F: FnMut(T) -> U, A: Array<Item = U>,

impl<T> Same<T> for T

type Output = T

impl<T> ToOwned for Twhere T: Clone,

type Owned = T

fn to_owned(&self) -> T

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

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

type Error = Infallible

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

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

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

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

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

fn vzip(self) -> V

impl<T> WithSubscriber for T

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

fn with_current_subscriber(self) -> WithDispatch<Self>

pub fn from<T>(provider: T) -> Figmentwhere
T: Provider,

pub fn join<T>(self, provider: T) -> Figmentwhere
T: Provider,

pub fn merge<T>(self, provider: T) -> Figmentwhere
T: Provider,

pub fn select<P>(self, profile: P) -> Figmentwhere
P: Into<Profile>,

pub fn extract<'a, T>(&self) -> Result<T, Error>where
T: Deserialize<'a>,

pub fn extract_inner<'a, T>(&self, key: &str) -> Result<T, Error>where
T: Deserialize<'a>,

fn data(
&self
) -> Result<BTreeMap<Profile, BTreeMap<String, Value, Global>, Global>, Error>

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

impl<T> Borrow<T> for Twhere
T: ?Sized,

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

impl<T> DynClone for Twhere
T: Clone,

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

fn into_collection<A>(self) -> SmallVec<A>where
A: Array<Item = T>,

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>where
F: FnMut(T) -> U,
A: Array<Item = U>,

impl<T> ToOwned for Twhere
T: Clone,

impl<T, U> TryFrom<U> for Twhere
U: Into<T>,

impl<T, U> TryInto<U> for Twhere
U: TryFrom<T>,

impl<V, T> VZip<V> for Twhere
V: MultiLane<T>,

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where
S: Into<Dispatch>,