Struct figment::providers::Env

pub struct Env {
    pub profile: Profile,
    // some fields omitted
}

This is supported on crate feature env only.

A Provider that sources its values from environment variables.

All key-lookups and comparisons are case insensitive, facilitated by the UncasedStr and Uncased types. Environment variables names are converted to lowercase before being emitted as key paths in the provided data. Environment variable values can contain structured data, parsed as a Value, with syntax resembling TOML:

• Bool: true, false (e.g, APP_VAR=true)
• Num::F64: any float containing .: (e.g, APP_VAR=1.2, APP_VAR=-0.002)
• Num::USize: any unsigned integer (e.g, APP_VAR=10)
• Num::Isize: any negative integer (e.g, APP_VAR=-10)
• Array: delimited by [] (e.g, APP_VAR=[true, 1.0, -1])
• Dict: in the form {key=value} (e.g, APP_VAR={key="value",num=10})
• String: delimited by "" (e.g, APP_VAR="hi")
• String: anything else (e.g, APP_VAR=hi, APP_VAR=[hi)

Provider Details

• Profile

  This provider does not set a profile.

• Metadata

  This provider is named environment variable(s). It does not specify a Source. Interpolation makes path parts uppercase and delimited with a ..

• Data

  The data emitted by this provider is single-level dictionary with the keys and values returned by Env::iter(), which reads from the currently set environment variables and is customizable via the various inherent methods. The dictionary is emitted to the profile profile, configurable via Env::profile().

Fields

profile: Profile

The profile config data will be emitted to. Defaults to Profile::Default.

Implementations

impl Env

pub fn raw() -> Self

Constructs and Env provider that does not filter or map any environment variables.

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

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

Jail::expect_with(|jail| {
    jail.set_env("NUMBERS", "[1, 2, 3]");
    jail.set_env("APP_BAR", "hi");

    let config: Config = Figment::from(Env::raw()).extract()?;
    assert_eq!(config, Config {
        numbers: vec![1, 2, 3],
        app_bar: "hi".into(),
    });

    Ok(())
});

pub fn prefixed(prefix: &str) -> Self

Return an Env provider that filters environment variables to those with the prefix prefix and maps to one without the prefix.

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

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

Jail::expect_with(|jail| {
    jail.set_env("APP_FOO", 100);
    jail.set_env("APP_BAR", "hi");

    let config: Config = Figment::from(Env::prefixed("APP_")).extract()?;
    assert_eq!(config, Config { foo: 100, bar: "hi".into() });

    Ok(())
});

pub fn filter<F: Clone + 'static>(self, filter: F) -> Self where
    F: Fn(&UncasedStr) -> bool, 

Applys an additional filter to the keys of environment variables being considered.

use figment::{Jail, providers::Env};

Jail::expect_with(|jail| {
    jail.set_env("FOO_FOO", 100);
    jail.set_env("BAR_BAR", "hi");
    jail.set_env("foobar", "hi");

    let env = Env::raw().filter(|k| k.starts_with("foo"));
    assert_eq!(env.iter().count(), 2);

    // Filters chains, like iterator adapters.
    let env = env.filter(|k| k.as_str().contains('_'));
    assert_eq!(env.iter().count(), 1);

    Ok(())
});

pub fn map<F: Clone + 'static>(self, mapper: F) -> Self where
    F: Fn(&UncasedStr) -> Uncased<'_>, 

Applys an additional mapping to the keys of environment variables being considered.

use figment::{Jail, providers::Env};

Jail::expect_with(|jail| {
    jail.set_env("FOO_FOO", 100);
    jail.set_env("BAR_FOO", "hi");
    jail.set_env("foobar", "hi");

    let env = Env::raw().map(|k| match k.starts_with("foo_") {
        true => k["foo_".len()..].into(),
        false => k.into()
    });

    assert_eq!(env.clone().filter(|k| k == "foo").iter().count(), 1);

    // Mappings chains, like iterator adapters.
    let env = env.map(|k| match k.starts_with("bar_") {
        true => k["bar_".len()..].into(),
        false => k.into()
    });

    assert_eq!(env.filter(|k| k == "foo").iter().count(), 2);
    Ok(())
});

pub fn split<P: Into<String>>(self, pattern: P) -> Self

Splits each environment variable key at pattern, creating nested dictionaries for each split. Specifically, nested dictionaries are created for components delimited by pattern in the environment variable string (3 in A_B_C if pattern is _), each dictionary mapping to its parent.

This is equivalent to: self.map(|key| key.replace(pattern, ".")).

Example

use serde::Deserialize;
use figment::{Figment, Jail, util::map, value::Dict, providers::Env};

#[derive(Debug, PartialEq, Deserialize)]
struct Foo {
    key: usize,
}

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

Jail::expect_with(|jail| {
    // Without splitting: using structured data.
    jail.set_env("APP_FOO", "{key=10}");
    jail.set_env("APP_MAP", "{one=1,two=2.0}");

    let config: Config = Figment::from(Env::prefixed("APP_")).extract()?;
    assert_eq!(config, Config {
        foo: Foo { key: 10 },
        map: map!["one".into() => 1u8.into(), "two".into() => 2.0.into()],
    });

    // With splitting.
    jail.set_env("APP_FOO_KEY", 20);
    jail.set_env("APP_MAP_ONE", "1.0");
    jail.set_env("APP_MAP_TWO", "dos");

    let config: Config = Figment::new()
        .merge(Env::prefixed("APP_").split("_"))
        .extract()?;

    assert_eq!(config, Config {
        foo: Foo { key: 20 },
        map: map!["one".into() => 1.0.into(), "two".into() => "dos".into()],
    });

    Ok(())
});

pub fn ignore(self, keys: &[&str]) -> Self

Filters out all environment variable keys contained in keys.

use figment::{Jail, providers::Env};

Jail::expect_with(|jail| {
    jail.set_env("FOO_FOO", 1);
    jail.set_env("FOO_BAR", 2);
    jail.set_env("FOO_BAZ", 3);
    jail.set_env("FOO_BAM", 4);

    let env = Env::prefixed("FOO_").ignore(&["bar", "baz"]);
    assert_eq!(env.clone().iter().count(), 2);

    // Ignores chain.
    let env = env.ignore(&["bam"]);
    assert_eq!(env.iter().count(), 1);
    Ok(())
});

pub fn only(self, keys: &[&str]) -> Self

Filters out all environment variables keys not contained in keys.

use figment::{Jail, providers::Env};

Jail::expect_with(|jail| {
    jail.set_env("FOO_FOO", 1);
    jail.set_env("FOO_BAR", 2);
    jail.set_env("FOO_BAZ_BOB", 3);
    jail.set_env("FOO_BAM_BOP", 4);

    let env = Env::prefixed("FOO_").only(&["bar", "baz_bob", "zoo"]);
    assert_eq!(env.iter().count(), 2);

    jail.set_env("FOO_ZOO", 5);
    assert_eq!(env.iter().count(), 3);

    let env = Env::prefixed("FOO_").split("_");
    assert_eq!(env.clone().only(&["bar", "baz.bob"]).iter().count(), 2);
    assert_eq!(env.clone().only(&["bar", "bam_bop"]).iter().count(), 1);

    Ok(())
});

pub fn iter<'a>(&'a self) -> impl Iterator<Item = (Uncased<'_>, String)> + 'a

Returns an iterator over all of the environment variable (key, value) pairs that will be considered by self. The order is not specified. Keys are always lower-case. Empty keys are not emitted.

use figment::{Jail, providers::Env};

Jail::expect_with(|jail| {
    jail.set_env("FOO_B", 2);
    jail.set_env("FOO_A", 1);
    jail.set_env("FOO_C", 3);

    let env = Env::prefixed("FOO_");
    let mut pairs: Vec<_> = env.iter().collect();
    pairs.sort_by(|(k1, _), (k2, _)| k1.cmp(k2));

    assert_eq!(pairs.len(), 3);
    assert_eq!(pairs[0], ("a".into(), "1".into()));
    assert_eq!(pairs[1], ("b".into(), "2".into()));
    assert_eq!(pairs[2], ("c".into(), "3".into()));

    jail.set_env("FOO_D", 4);
    let mut pairs: Vec<_> = env.iter().collect();
    pairs.sort_by(|(k1, _), (k2, _)| k1.cmp(k2));

    assert_eq!(pairs.len(), 4);
    assert_eq!(pairs[3], ("d".into(), "4".into()));

    Ok(())
});

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

Sets the profile config data will be emitted to.

use figment::{Profile, providers::Env};

let env = Env::raw();
assert_eq!(env.profile, Profile::Default);

let env = env.profile("debug");
assert_eq!(env.profile, Profile::from("debug"));

pub fn global(mut self: Self) -> Self

Sets the profile config data will be emitted to to global.

use figment::{Profile, providers::Env};

let env = Env::raw();
assert_eq!(env.profile, Profile::Default);

let env = env.global();
assert_eq!(env.profile, Profile::Global);

pub fn var(name: &str) -> Option<String>

A convenience method to retrieve the value for an environment variable with name name. Retrieval is case-insensitive.

use figment::{Jail, providers::Env};

Jail::expect_with(|jail| {
    jail.set_env("TESTING", 123);
    assert_eq!(Env::var("testing"), Some("123".to_string()));
    Ok(())
});

pub fn var_or<S: Into<String>>(name: &str, default: S) -> String

A convenience method to retrieve the value for an environment variable with name name or a default default if one is not set. Retrieval is case-insensitive.

use figment::{Jail, providers::Env};

Jail::expect_with(|jail| {
    jail.set_env("TESTING", 123);
    assert_eq!(Env::var_or("testing", "whoops"), "123");
    assert_eq!(Env::var_or("hi", "whoops"), "whoops");
    Ok(())
});

Trait Implementations

impl Clone for Env

pub fn clone(&self) -> Env

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Env

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

Formats the value using the given formatter.

impl Provider for Env

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.