deserialize env vars into typesafe structs with rust
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples impl prefixed feature Aug 14, 2017
serde-tests impl prefixed feature Aug 14, 2017
src impl prefixed feature Aug 14, 2017
.gitignore poc Jun 28, 2016
.travis.yml allow nightly travis failures because... nightly Dec 2, 2016
CHANGELOG.md impl prefixed feature Aug 14, 2017
Cargo.toml bump version Aug 14, 2017
LICENSE update docs May 29, 2017
Makefile serde1 wip May 27, 2017
README.md update readme example Aug 14, 2017

README.md

envy Build Status Coverage Status Software License crates.io

deserialize env vars into typesafe structs

Documentation

install

Add the following to your Cargo.toml fails_with_invalid_type

[dependencies]
envy = "0.3"

usage

assuming your rust program looks something like this.

#[macro_use]
extern crate serde_derive;
extern crate envy;

#[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

#[macro_use]
extern crate serde_derive;
extern crate envy;

#[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

potential areas of improvement

  • error handling/reporting

Doug Tangren (softprops) 2016-2017