Struct serde_env_field::EnvField

pub struct EnvField<T, Variant = UseFromStr>(/* private fields */);

A field that deserializes either as T or as String with all environment variables expanded via the shellexpand crate.

By default, it requires T to implement the FromStr trait for deserialization from String after environment variables expansion.

You can use the UseDeserialize to bypass the FromStr and deserialize the T directly from the string with all environment variables expanded.

The EnvField serializes transparently as the T type if the T is serializable.

Works nicely with Option, Vec, and #[serde(default)].

Note: if you want to wrap all the fields of a struct or an enum with the EnvField, you might want to use the env_field_wrap attribute.

Examples

Basic

#[derive(Serialize, Deserialize)]
struct Example {
    name: EnvField<String>,
    size: EnvField<usize>,
    num: EnvField<i32>,
}

std::env::set_var("SIZE", "100");

let de: Example = toml::from_str(r#"
    name = "${NAME:-Default Name}"

    size = "$SIZE"

    num = 42
"#).unwrap();

assert_eq!(&de.name, "Default Name");
assert_eq!(de.size, 100);
assert_eq!(de.num, 42);

Optional fields

#[derive(Serialize, Deserialize)]
struct Example {
    required: EnvField<i32>,
    optional: Option<EnvField<i32>>,
}

let de: Example = toml::from_str(r#"
    required = 512
"#).unwrap();

assert_eq!(de.required, 512);
assert!(de.optional.is_none());

std::env::set_var("OPTIONAL", "-1024");
let de: Example = toml::from_str(r#"
    required = 512
    optional = "$OPTIONAL"
"#).unwrap();

assert_eq!(de.required, 512);
assert_eq!(de.optional.unwrap(), -1024);

let de: Example = toml::from_str(r#"
    required = 512
    optional = 42
"#).unwrap();

assert_eq!(de.required, 512);
assert_eq!(de.optional.unwrap(), 42);

Sequences

#[derive(Serialize, Deserialize)]
struct Example {
    seq: Vec<EnvField<i32>>,
}

std::env::set_var("NUM", "1000");
let de: Example = toml::from_str(r#"
    seq = [
        12, "$NUM", 145,
    ]
"#).unwrap();

assert_eq!(de.seq[0], 12);
assert_eq!(de.seq[1], 1000);
assert_eq!(de.seq[2], 145);

Defaults

use derive_more::FromStr;

#[derive(Serialize, Deserialize)]
struct Example {
    #[serde(default)]
    num: EnvField<NumWithDefault>,
}

#[derive(Serialize, Deserialize, FromStr)]
#[serde(transparent)]
struct NumWithDefault(i32);
impl Default for NumWithDefault {
    fn default() -> Self {
        Self(42)
    }
}

let de: Example = toml::from_str("").unwrap();
assert_eq!(de.num.0, 42);

let de: Example = toml::from_str(r#"
    num = 100
"#).unwrap();
assert_eq!(de.num.0, 100);

std::env::set_var("SOME_NUM", "555");
let de: Example = toml::from_str(r#"
    num = "$SOME_NUM"
"#).unwrap();
assert_eq!(de.num.0, 555);

Deserialization without FromStr

use serde_env_field::UseDeserialize;

#[derive(Serialize, Deserialize)]
struct Example {
    variant: EnvField<Variants, UseDeserialize>
}

#[derive(Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
enum Variants {
    AUsefullVariant,
    AnotherCoolVariant,
}

let de: Example = toml::from_str(r#"
    variant = "a-usefull-variant"
"#).unwrap();
assert!(matches!(*de.variant, Variants::AUsefullVariant));

std::env::set_var("SELECTED_VARIANT", "another-cool-variant");
let de: Example = toml::from_str(r#"
    variant = "$SELECTED_VARIANT"
"#).unwrap();
assert!(matches!(*de.variant, Variants::AnotherCoolVariant));

Deserialization with FromStr

#[derive(Serialize, Deserialize)]
struct Example {
    inner: EnvField<Inner>,
}

#[derive(Serialize, Deserialize)]
struct Inner {
    // We can use `EnvField` in inner structs
    num: EnvField<i32>,

    sym: EnvField<String>,
}

impl FromStr for Inner {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let mut split = s.split(';');

        let num = split
            .next()
            .unwrap()
            .parse()
            .map_err(|err: ParseIntError| err.to_string())?;

        let sym = split
            .next()
            .unwrap()
            .to_string()
            .into();

        Ok(Self {
            num,
            sym
        })
    }
}

std::env::set_var("INNER_NUM", "2048");
std::env::set_var("INNER_SYM", "Hi");
let de: Example = toml::from_str(r#"
    inner = "$INNER_NUM;$INNER_SYM"
"#).unwrap();

assert_eq!(de.inner.num, 2048);
assert_eq!(&de.inner.sym, "Hi");


let de: Example = toml::from_str(r#"
    [inner]
    num = -500
    sym = "Hello"
"#).unwrap();

assert_eq!(de.inner.num, -500);
assert_eq!(&de.inner.sym, "Hello");

Implementations

impl<T, V> EnvField<T, V>

pub fn into_inner(self) -> T

Unwraps the value, consuming the env field.

Trait Implementations

impl<T: Add, V> Add<T> for EnvField<T, V>

type Output = <T as Add>::Output

The resulting type after applying the + operator.

fn add(self, rhs: T) -> Self::Output

Performs the + operation.

impl<T: Add, V> Add for EnvField<T, V>

type Output = <T as Add>::Output

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl<T: AddAssign, V> AddAssign<T> for EnvField<T, V>

fn add_assign(&mut self, rhs: T)

Performs the += operation.

impl<T: AddAssign, V> AddAssign for EnvField<T, V>

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl<T: BitAnd, V> BitAnd<T> for EnvField<T, V>

type Output = <T as BitAnd>::Output

The resulting type after applying the & operator.

fn bitand(self, rhs: T) -> Self::Output

Performs the & operation.

impl<T: BitAnd, V> BitAnd for EnvField<T, V>

type Output = <T as BitAnd>::Output

The resulting type after applying the & operator.

fn bitand(self, rhs: Self) -> Self::Output

Performs the & operation.

impl<T: BitAndAssign, V> BitAndAssign<T> for EnvField<T, V>

fn bitand_assign(&mut self, rhs: T)

Performs the &= operation.

impl<T: BitAndAssign, V> BitAndAssign for EnvField<T, V>

fn bitand_assign(&mut self, rhs: Self)

Performs the &= operation.

impl<T: BitOr, V> BitOr<T> for EnvField<T, V>

type Output = <T as BitOr>::Output

The resulting type after applying the | operator.

fn bitor(self, rhs: T) -> Self::Output

Performs the | operation.

impl<T: BitOr, V> BitOr for EnvField<T, V>

type Output = <T as BitOr>::Output

The resulting type after applying the | operator.

fn bitor(self, rhs: Self) -> Self::Output

Performs the | operation.

impl<T: BitOrAssign, V> BitOrAssign<T> for EnvField<T, V>

fn bitor_assign(&mut self, rhs: T)

Performs the |= operation.

impl<T: BitOrAssign, V> BitOrAssign for EnvField<T, V>

fn bitor_assign(&mut self, rhs: Self)

Performs the |= operation.

impl<T: BitXor, V> BitXor<T> for EnvField<T, V>

type Output = <T as BitXor>::Output

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: T) -> Self::Output

Performs the ^ operation.

impl<T: BitXor, V> BitXor for EnvField<T, V>

type Output = <T as BitXor>::Output

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: Self) -> Self::Output

Performs the ^ operation.

impl<T: BitXorAssign, V> BitXorAssign<T> for EnvField<T, V>

fn bitxor_assign(&mut self, rhs: T)

Performs the ^= operation.

impl<T: BitXorAssign, V> BitXorAssign for EnvField<T, V>

fn bitxor_assign(&mut self, rhs: Self)

Performs the ^= operation.

impl<T: Clone, V> Clone for EnvField<T, V>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug, V> Debug for EnvField<T, V>

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

Formats the value using the given formatter.

impl<T: Default, V> Default for EnvField<T, V>

fn default() -> Self

Returns the “default value” for a type.

impl<T, V> Deref for EnvField<T, V>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, V> DerefMut for EnvField<T, V>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de, T> Deserialize<'de> for EnvField<T, UseFromStr>

where T: Deserialize<'de> + FromStr, <T as FromStr>::Err: Display,

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'de, T> Deserialize<'de> for EnvField<T, UseDeserialize>

where T: Deserialize<'de>,

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T: Div, V> Div<T> for EnvField<T, V>

type Output = <T as Div>::Output

The resulting type after applying the / operator.

fn div(self, rhs: T) -> Self::Output

Performs the / operation.

impl<T: Div, V> Div for EnvField<T, V>

type Output = <T as Div>::Output

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self::Output

Performs the / operation.

impl<T: DivAssign, V> DivAssign<T> for EnvField<T, V>

fn div_assign(&mut self, rhs: T)

Performs the /= operation.

impl<T: DivAssign, V> DivAssign for EnvField<T, V>

fn div_assign(&mut self, rhs: Self)

Performs the /= operation.

impl<T, V> From<T> for EnvField<T, V>

fn from(value: T) -> Self

Converts to this type from the input type.

impl<T: FromStr, V> FromStr for EnvField<T, V>

type Err = <T as FromStr>::Err

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<T: Mul, V> Mul<T> for EnvField<T, V>

type Output = <T as Mul>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: T) -> Self::Output

Performs the * operation.

impl<T: Mul, V> Mul for EnvField<T, V>

type Output = <T as Mul>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl<T: MulAssign, V> MulAssign<T> for EnvField<T, V>

fn mul_assign(&mut self, rhs: T)

Performs the *= operation.

impl<T: MulAssign, V> MulAssign for EnvField<T, V>

fn mul_assign(&mut self, rhs: Self)

Performs the *= operation.

impl<T: Neg, V> Neg for EnvField<T, V>

type Output = <T as Neg>::Output

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<T: Not, V> Not for EnvField<T, V>

type Output = <T as Not>::Output

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

impl<T: Ord, V> Ord for EnvField<T, V>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<T: PartialEq, V> PartialEq<T> for EnvField<T, V>

fn eq(&self, other: &T) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq<str>, V> PartialEq<str> for EnvField<T, V>

fn eq(&self, other: &str) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialEq, V> PartialEq for EnvField<T, V>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialOrd, V> PartialOrd<T> for EnvField<T, V>

fn partial_cmp(&self, other: &T) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: PartialOrd, V> PartialOrd for EnvField<T, V>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: Rem, V> Rem<T> for EnvField<T, V>

type Output = <T as Rem>::Output

The resulting type after applying the % operator.

fn rem(self, rhs: T) -> Self::Output

Performs the % operation.

impl<T: Rem, V> Rem for EnvField<T, V>

type Output = <T as Rem>::Output

The resulting type after applying the % operator.

fn rem(self, rhs: Self) -> Self::Output

Performs the % operation.

impl<T: RemAssign, V> RemAssign<T> for EnvField<T, V>

fn rem_assign(&mut self, rhs: T)

Performs the %= operation.

impl<T: RemAssign, V> RemAssign for EnvField<T, V>

fn rem_assign(&mut self, rhs: Self)

Performs the %= operation.

impl<T: Serialize, V> Serialize for EnvField<T, V>

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: Shl, V> Shl<T> for EnvField<T, V>

type Output = <T as Shl>::Output

The resulting type after applying the << operator.

fn shl(self, rhs: T) -> Self::Output

Performs the << operation.

impl<T: Shl, V> Shl for EnvField<T, V>

type Output = <T as Shl>::Output

The resulting type after applying the << operator.

fn shl(self, rhs: Self) -> Self::Output

Performs the << operation.

impl<T: ShlAssign, V> ShlAssign<T> for EnvField<T, V>

fn shl_assign(&mut self, rhs: T)

Performs the <<= operation.

impl<T: ShlAssign, V> ShlAssign for EnvField<T, V>

fn shl_assign(&mut self, rhs: Self)

Performs the <<= operation.

impl<T: Shr, V> Shr<T> for EnvField<T, V>

type Output = <T as Shr>::Output

The resulting type after applying the >> operator.

fn shr(self, rhs: T) -> Self::Output

Performs the >> operation.

impl<T: Shr, V> Shr for EnvField<T, V>

type Output = <T as Shr>::Output

The resulting type after applying the >> operator.

fn shr(self, rhs: Self) -> Self::Output

Performs the >> operation.

impl<T: ShrAssign, V> ShrAssign<T> for EnvField<T, V>

fn shr_assign(&mut self, rhs: T)

Performs the >>= operation.

impl<T: ShrAssign, V> ShrAssign for EnvField<T, V>

fn shr_assign(&mut self, rhs: Self)

Performs the >>= operation.

impl<T: Sub, V> Sub<T> for EnvField<T, V>

type Output = <T as Sub>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: T) -> Self::Output

Performs the - operation.

impl<T: Sub, V> Sub for EnvField<T, V>

type Output = <T as Sub>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl<T: SubAssign, V> SubAssign<T> for EnvField<T, V>

fn sub_assign(&mut self, rhs: T)

Performs the -= operation.

impl<T: SubAssign, V> SubAssign for EnvField<T, V>

fn sub_assign(&mut self, rhs: Self)

Performs the -= operation.

impl<T: Copy, V> Copy for EnvField<T, V>

impl<T: Eq, V> Eq for EnvField<T, V>