#serde #env

envy

deserialize env vars into typesafe structs

9 releases

✓ Uses Rust 2018 edition

0.4.0 Feb 18, 2019
0.3.3 Oct 22, 2018
0.3.2 Aug 14, 2017
0.3.1 May 30, 2017
0.1.1 Jul 11, 2016

#6 in Configuration

Download history 1107/week @ 2019-07-26 417/week @ 2019-08-02 634/week @ 2019-08-09 1335/week @ 2019-08-16 1265/week @ 2019-08-23 1529/week @ 2019-08-30 1756/week @ 2019-09-06 2210/week @ 2019-09-13 2365/week @ 2019-09-20 4521/week @ 2019-09-27 2712/week @ 2019-10-04 3484/week @ 2019-10-11 3363/week @ 2019-10-18 3629/week @ 2019-10-25 2764/week @ 2019-11-01

2,612 downloads per month
Used in 9 crates (8 directly)

MIT license

20KB
416 lines

envy Build Status Coverage Status Software License crates.io Master API docs

deserialize environment variables into typesafe structs

📦 install

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 take use all of serde's attributes to your advantage.

For instance let's say you're 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() -> {
  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 into typesafe structs.

Doug Tangren (softprops) 2016-2019

Dependencies

~195–305KB