pub struct Env {
pub profile: Profile,
/* private fields */
}
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 aSource
. 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 profileprofile
, configurable viaEnv::profile()
.
Fields§
§profile: Profile
The profile config data will be emitted to. Defaults to
Profile::Default
.
Implementations§
source§impl Env
impl Env
sourcepub fn raw() -> Self
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(())
});
sourcepub fn prefixed(prefix: &str) -> Self
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(())
});
sourcepub fn filter<F>(self, filter: F) -> Selfwhere
F: Fn(&UncasedStr) -> bool + Clone + 'static,
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(())
});
sourcepub fn map<F>(self, mapper: F) -> Selfwhere
F: Fn(&UncasedStr) -> Uncased<'_> + Clone + 'static,
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(())
});
sourcepub fn split<P: Into<String>>(self, pattern: P) -> Self
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(())
});
sourcepub fn ignore(self, keys: &[&str]) -> Self
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(())
});
sourcepub fn only(self, keys: &[&str]) -> Self
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(())
});
sourcepub fn iter<'a>(&'a self) -> impl Iterator<Item = (Uncased<'_>, String)> + 'a
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(())
});
sourcepub fn profile<P: Into<Profile>>(self, profile: P) -> Self
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"));
sourcepub fn global(self) -> Self
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);
sourcepub fn var(name: &str) -> Option<String>
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(())
});
sourcepub fn var_or<S: Into<String>>(name: &str, default: S) -> String
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§
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> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere T: ?Sized,
source§fn fg(&self, value: Color) -> Painted<&T>
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 bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
source§fn bright_yellow(&self) -> Painted<&T>
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>
fn bright_blue(&self) -> Painted<&T>
source§fn bright_magenta(&self) -> Painted<&T>
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>
fn bright_cyan(&self) -> Painted<&T>
source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
source§fn bg(&self, value: Color) -> Painted<&T>
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>
fn on_primary(&self) -> Painted<&T>
source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
source§fn on_bright_black(&self) -> Painted<&T>
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>
fn on_bright_red(&self) -> Painted<&T>
source§fn on_bright_green(&self) -> Painted<&T>
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>
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>
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>
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>
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>
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>
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 underline(&self) -> Painted<&T>
fn underline(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::Underline
.
Example
println!("{}", value.underline());
source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::RapidBlink
.
Example
println!("{}", value.rapid_blink());
source§fn quirk(&self, value: Quirk) -> Painted<&T>
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 whenever(&self, value: Condition) -> Painted<&T>
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);