Struct Data

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

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

impl<F> Data<F>

where F: Format,

pub fn file<P>(path: P) -> Data<F>

where P: AsRef<Path>,

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. If you don’t want parent directories to be searched, use Data::file_exact() instead.

Nesting is disabled by default. Use Data::nested() to enable it.

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 file_exact<P>(path: P) -> Data<F>

where P: AsRef<Path>,

Returns a Data provider that sources its values by parsing the file at path as format F. If path is relative, it is located relative to the current working directory. No other directories are searched.

If you want to search parent directories for path, use Data::file() instead.

Nesting is disabled by default. Use Data::nested() to enable it.

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

#[derive(Debug, PartialEq, Deserialize)]
struct Config {
    foo: usize,
}

Jail::expect_with(|jail| {
    // Create 'subdir/config.toml' and set `cwd = subdir`.
    jail.create_file("config.toml", "foo = 123")?;
    jail.change_dir(jail.create_dir("subdir")?)?;

    // We are in `subdir`. `config.toml` is in `../`. `file()` finds it.
    let config = Figment::from(Toml::file("config.toml")).extract::<Config>()?;
    assert_eq!(config.foo, 123);

    // `file_exact()` doesn't search, so it doesn't find it.
    let config = Figment::from(Toml::file_exact("config.toml")).extract::<Config>();
    assert!(config.is_err());
    Ok(())
});

pub fn string(string: &str) -> Data<F>

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(self) -> Data<F>

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>(self, profile: P) -> Data<F>

where P: Into<Profile>,

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 for Data<F>

where F: Clone + Format,

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F> Debug for Data<F>

where F: Debug + Format,

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

Formats the value using the given formatter.

impl<F> Provider for Data<F>

where F: Format,

fn metadata(&self) -> Metadata

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

fn data(&self) -> Result<BTreeMap<Profile, BTreeMap<String, Value>>, 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.