Struct sea_orm_rocket::figment::providers::Env

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

impl Env

pub fn raw() -> Env

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

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>(self, filter: F) -> Envwhere
F: 'static + Clone + 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");

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

pub fn map<F>(self, mapper: F) -> Envwhere
F: 'static + Clone + 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");

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

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

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]) -> Env

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]) -> Env

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 self) -> impl Iterator<Item = (Uncased<'a>, 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(())
});

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

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(self) -> Env

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>(name: &str, default: S) -> Stringwhere
S: Into<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

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

impl Debug for Env

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

Formats the value using the given formatter. Read more

impl Provider for Env

fn metadata(&self) -> Metadata

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

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

Auto Trait Implementations

impl !RefUnwindSafe for Env

impl !Send for Env

Struct sea_orm_rocket::figment::providers::Env

Fields

Implementations

impl Env

pub fn raw() -> Env

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

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

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

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

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

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

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

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

pub fn global(self) -> Env

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

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

Trait Implementations

impl Clone for Env

fn clone(&self) -> Env

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

impl Debug for Env

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

impl Provider for Env

fn metadata(&self) -> Metadata

fn data( &self) -> Result<BTreeMap<Profile, BTreeMap<String, Value, Global>, Global>, Error>

fn profile(&self) -> Option<Profile>

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

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

fn type_id(&self) -> TypeId

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

fn borrow(&self) -> &T

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

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

impl<T> DynClone for Twhere T: Clone,

fn __clone_box(&self, Private) -> *mut ()

impl<T> From<T> for T

fn from(t: T) -> T

impl<T> Instrument for T

fn instrument(self, span: Span) -> Instrumented<Self>

fn in_current_span(self) -> Instrumented<Self>

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

fn into(self) -> U

impl<T> IntoCollection<T> for T

fn into_collection<A>(self) -> SmallVec<A>where A: Array<Item = T>,

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>where F: FnMut(T) -> U, A: Array<Item = U>,

impl<T> Same<T> for T

type Output = T

impl<T> ToOwned for Twhere T: Clone,

type Owned = T

fn to_owned(&self) -> T

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

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

type Error = Infallible

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

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

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

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

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

fn vzip(self) -> V

impl<T> WithSubscriber for T

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

fn with_current_subscriber(self) -> WithDispatch<Self>

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

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

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

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

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

fn data(
&self
) -> Result<BTreeMap<Profile, BTreeMap<String, Value, Global>, Global>, Error>

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

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

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

impl<T> DynClone for Twhere
T: Clone,

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

fn into_collection<A>(self) -> SmallVec<A>where
A: Array<Item = T>,

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>where
F: FnMut(T) -> U,
A: Array<Item = U>,

impl<T> ToOwned for Twhere
T: Clone,

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

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

impl<V, T> VZip<V> for Twhere
V: MultiLane<T>,

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where
S: Into<Dispatch>,