Struct figment::providers::Env

source ·
pub struct Env {
    pub profile: Profile,
    /* private fields */
}
Available on crate feature env only.
Expand description

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

Additionally, keys and strings delimited with " can contain the following escaped characters:

\b         - backspace       (U+0008)
\t         - tab             (U+0009)
\n         - linefeed        (U+000A)
\f         - form feed       (U+000C)
\r         - carriage return (U+000D)
\"         - quote           (U+0022)
\\         - backslash       (U+005C)
\uXXXX     - unicode         (U+XXXX)
\UXXXXXXXX - unicode         (U+XXXXXXXX)

For example:

APP_VAR=\"hello\\nthere\"  => (what in Rust is) "hello\nthere"
APP_VAR=\"hi\\u1234there\" => (what in Rust is) "hi\u{1234}there"
APP_VAR=\"abc\\td\\n\"     => (what in Rust is) "abc\td\n"

APP_VAR={\"key\\nkey\"=123}`)
APP_VAR={\"key.key\"=123}`)

Undelimited strings, or strings with invalid escape sequences, are interpreted exactly as written without any escaping.

Key Paths (nesting)

Because environment variables names are emitted as key paths in the provided data, a nested dictionary is created for every component of the name delimited by ., each a parent of the next, with the leaf mapping to environment variable Value. For example, the environment variable a.b.c=3 creates the mapping a -> b -> c -> 3 in the emitted data.

Environment variable names cannot typically contain the . character, but another character can be used in its place by replacing that character in the name with . with Env::map(). The Env::split() method is a convenience method that does exactly this.

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§

source§

impl Env

source

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

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

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

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");

    // We'll be left with `FOO_FOO=100` and `foobar=hi`.
    let env = Env::raw().filter(|k| k.starts_with("foo"));
    assert_eq!(env.iter().count(), 2);

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

    Ok(())
});
source

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

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");

    // This is like `prefixed("foo_")` without the filtering.
    let env = Env::raw().map(|k| match k.starts_with("foo_") {
        true => k["foo_".len()..].into(),
        false => k.into()
    });

    // We now have `FOO=100`, `BAR_FOO=hi`, and `bar=hi`.
    assert_eq!(env.clone().filter(|k| k == "foo").iter().count(), 1);

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

    // We now have `FOO=100`, `FOO=hi`, and `bar=hi`.
    assert_eq!(env.filter(|k| k == "foo").iter().count(), 2);
    Ok(())
});
source

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

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

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

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 lower-cased with leading and trailing whitespace removed. Empty keys, or partially empty keys, are not emitted.

Any non-Unicode sequences in values are replaced with U+FFFD REPLACEMENT CHARACTER. Values are otherwise unmodified.

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

pub fn profile<P: Into<Profile>>(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"));
source

pub fn global(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);
source

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

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§

source§

impl Clone for Env

source§

fn clone(&self) -> Env

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Env

source§

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

Formats the value using the given formatter. Read more
source§

impl Provider for Env

source§

fn metadata(&self) -> Metadata

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

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

Returns the configuration data.
source§

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.

Auto Trait Implementations§

§

impl !RefUnwindSafe for Env

§

impl !Send for Env

§

impl !Sync for Env

§

impl Unpin for Env

§

impl !UnwindSafe for Env

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Paint for Twhere T: ?Sized,

source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

Example
println!("{}", value.bright_green());
source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightYellow.

Example
println!("{}", value.bright_yellow());
source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlue.

Example
println!("{}", value.bright_blue());
source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightMagenta.

Example
println!("{}", value.bright_magenta());
source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightCyan.

Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

Example
println!("{}", value.bright_white());
source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to Color::Primary.

Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

Example
println!("{}", value.on_white());
source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlack.

Example
println!("{}", value.on_bright_black());
source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightRed.

Example
println!("{}", value.on_bright_red());
source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightGreen.

Example
println!("{}", value.on_bright_green());
source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightYellow.

Example
println!("{}", value.on_bright_yellow());
source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlue.

Example
println!("{}", value.on_bright_blue());
source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightMagenta.

Example
println!("{}", value.on_bright_magenta());
source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightCyan.

Example
println!("{}", value.on_bright_cyan());
source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightWhite.

Example
println!("{}", value.on_bright_white());
source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

Example
println!("{}", value.strike());
source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Clear.

Example
println!("{}", value.clear());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

Example
println!("{}", value.on_bright());
source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
source§

fn new(self) -> Painted<Self>where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S>(&self, style: S) -> Painted<&Self>where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.