Struct figment::providers::Data

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

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 equivalaent, 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 exepcted 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

impl<F: Format> Data<F>

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(())
});

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(())
});

pub fn nested(mut self: 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(())
});

pub fn profile<P: Into<Profile>>(mut self: 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(())
});

Trait Implementations

impl<F: Clone + Format> Clone for Data<F>

pub fn clone(&self) -> Data<F>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F: Debug + Format> Debug for Data<F>

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

Formats the value using the given formatter.

impl<F: Format> Provider for Data<F>

pub fn metadata(&self) -> Metadata

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

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

Returns the configuration data.

pub 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.