README.md

envy

deserialize environment variables into typesafe structs

📦 install

Run cargo add envy or add the following to your Cargo.toml file.

[dependencies]
envy = "0.4"

🤸 usage

A typical envy usage looks like the following. Assuming your rust program looks something like this...

💡 These examples use Serde's derive feature

use serde::Deserialize;

#[derive(Deserialize, Debug)]
struct Config {
  foo: u16,
  bar: bool,
  baz: String,
  boom: Option<u64>
}

fn main() {
    match envy::from_env::<Config>() {
       Ok(config) => println!("{:#?}", config),
       Err(error) => panic!("{:#?}", error)
    }
}

... export some environment variables

$ FOO=8080 BAR=true BAZ=hello yourapp

You should be able to access a completely typesafe config struct deserialized from env vars.

Envy assumes an env var exists for each struct field with a matching name in all uppercase letters. i.e. A struct field foo_bar would map to an env var named FOO_BAR.

Structs with Option type fields will successfully be deserialized when their associated env var is absent.

Envy also supports deserializing Vecs from comma separated env var values.

Because envy is built on top of serde, you can use all of serde's attributes to your advantage.

For instance let's say your app requires a field but would like a sensible default when one is not provided.

/// provides default value for zoom if ZOOM env var is not set
fn default_zoom() -> u16 {
  32
}

#[derive(Deserialize, Debug)]
struct Config {
  foo: u16,
  bar: bool,
  baz: String,
  boom: Option<u64>,
  #[serde(default="default_zoom")]
  zoom: u16
}

The following will yield an application configured with a zoom of 32

$ FOO=8080 BAR=true BAZ=hello yourapp

The following will yield an application configured with a zoom of 10

$ FOO=8080 BAR=true BAZ=hello ZOOM=10 yourapp

The common pattern for prefixing env var names for a specific app is supported using the envy::prefixed(prefix) interface. Asumming your env vars are prefixed with APP_ the above example may instead look like

use serde::Deserialize;

#[derive(Deserialize, Debug)]
struct Config {
  foo: u16,
  bar: bool,
  baz: String,
  boom: Option<u64>
}

fn main() {
    match envy::prefixed("APP_").from_env::<Config>() {
       Ok(config) => println!("{:#?}", config),
       Err(error) => panic!("{:#?}", error)
    }
}

the expectation would then be to export the same environment variables prefixed with APP_

$ APP_FOO=8080 APP_BAR=true APP_BAZ=hello yourapp

👭 Consider this crate a cousin of envy-store, a crate for deserializing AWS parameter store values into typesafe structs and recap, a crate for deserializing named regex capture groups into typesafe structs.

Doug Tangren (softprops) 2016-2024