Struct figment::Figment

pub struct Figment { /* fields omitted */ }

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() -> Self

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>(provider: T) -> Self

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: Provider>(self, provider: T) -> Self

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: Provider>(self, provider: T) -> Self

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<P: Into<Profile>>(self, profile: P) -> Self

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) -> Self

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: Deserialize<'a>>(&self) -> Result<T>

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: Deserialize<'a>>(&self, key: &str) -> Result<T>

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>

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.

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

Performs copy-assignment from source.

impl Debug for Figment

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

Formats the value using the given formatter.

impl Default for Figment

fn default() -> Self

Returns the “default value” for a type.

impl Provider for Figment

fn metadata(&self) -> Metadata

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

fn data(&self) -> Result<Map<Profile, Dict>>

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.

fn __metadata_map(&self) -> Option<Map<Tag, Metadata>>