Struct figment::providers::Data

source · [−]

pub struct Data<F: Format> {
    pub profile: Option<Profile>,
    /* private fields */
}

Expand description

A Provider that sources values from a file or string in a given Format.

Constructing

A Data provider is typically constructed indirectly via a type that implements the Format trait via the Format::file() and Format::string() methods which in-turn defer to Data::file() and Data::string() by default:

// The `Format` trait must be in-scope to use its methods.
use figment::providers::{Format, Data, Json};

// These two are equivalent, except the former requires the explicit type.
let json = Data::<Json>::file("foo.json");
let json = Json::file("foo.json");

Provider Details

Profile

This provider does not set a profile.
Metadata

This provider is named ${NAME} file (when constructed via Data::file()) or ${NAME} source string (when constructed via Data::string()), where ${NAME} is Format::NAME. When constructed from a file, the file’s path is specified as file Source. Path interpolation is unchanged from the default.
Data (Unnested, default)

When nesting is not specified, the source file or string is read and parsed, and the parsed dictionary is emitted into the profile configurable via Data::profile(), which defaults to Profile::Default. If the source is a file and the file is not present, an empty dictionary is emitted.
Data (Nested)

When nesting is specified, the source value is expected to be a dictionary. It’s top-level keys are emitted as profiles, and the value corresponding to each key as the profile data.

Fields

profile: Option<Profile>

The profile data will be emitted to if nesting is disabled. Defaults to Profile::Default.

Implementations

source

impl<F: Format> Data<F>

source

pub fn file<P: AsRef<Path>>(path: P) -> Self

Returns a Data provider that sources its values by parsing the file at path as format F. If path is relative, the file is searched for in the current working directory and all parent directories until the root, and the first hit is used.

Nesting is not enabled by default; use Data::nested() to enable nesting.

use serde::Deserialize;
use figment::{Figment, Jail, providers::{Format, Toml}, value::Map};

#[derive(Debug, PartialEq, Deserialize)]
struct Config {
    numbers: Vec<usize>,
    untyped: Map<String, usize>,
}

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

        [untyped]
        key = 1
        other = 4
    "#)?;

    let config: Config = Figment::from(Toml::file("Config.toml")).extract()?;
    assert_eq!(config, Config {
        numbers: vec![1, 2, 3],
        untyped: figment::util::map!["key".into() => 1, "other".into() => 4],
    });

    Ok(())
});

source

pub fn string(string: &str) -> Self

Returns a Data provider that sources its values by parsing the string string as format F. Nesting is not enabled by default; use Data::nested() to enable nesting.

use serde::Deserialize;
use figment::{Figment, Jail, providers::{Format, Toml}, value::Map};

#[derive(Debug, PartialEq, Deserialize)]
struct Config {
    numbers: Vec<usize>,
    untyped: Map<String, usize>,
}

Jail::expect_with(|jail| {
    let source = r#"
        numbers = [1, 2, 3]
        untyped = { key = 1, other = 4 }
    "#;

    let config: Config = Figment::from(Toml::string(source)).extract()?;
    assert_eq!(config, Config {
        numbers: vec![1, 2, 3],
        untyped: figment::util::map!["key".into() => 1, "other".into() => 4],
    });

    Ok(())
});

source

pub fn nested(self) -> Self

Enables nesting on self, which results in top-level keys of the sourced data being treated as profiles.

use serde::Deserialize;
use figment::{Figment, Jail, providers::{Format, Toml}, value::Map};

#[derive(Debug, PartialEq, Deserialize)]
struct Config {
    numbers: Vec<usize>,
    untyped: Map<String, usize>,
}

Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#"
        [global.untyped]
        global = 0
        hi = 7

        [staging]
        numbers = [1, 2, 3]

        [release]
        numbers = [6, 7, 8]
    "#)?;

    // Enable nesting via `nested()`.
    let figment = Figment::from(Toml::file("Config.toml").nested());

    let figment = figment.select("staging");
    let config: Config = figment.extract()?;
    assert_eq!(config, Config {
        numbers: vec![1, 2, 3],
        untyped: figment::util::map!["global".into() => 0, "hi".into() => 7],
    });

    let config: Config = figment.select("release").extract()?;
    assert_eq!(config, Config {
        numbers: vec![6, 7, 8],
        untyped: figment::util::map!["global".into() => 0, "hi".into() => 7],
    });

    Ok(())
});

source

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

Set the profile to emit data to when nesting is disabled.

use serde::Deserialize;
use figment::{Figment, Jail, providers::{Format, Toml}, value::Map};

#[derive(Debug, PartialEq, Deserialize)]
struct Config { value: u8 }

Jail::expect_with(|jail| {
    let provider = Toml::string("value = 123").profile("debug");
    let config: Config = Figment::from(provider).select("debug").extract()?;
    assert_eq!(config, Config { value: 123 });

    Ok(())
});