deserialize environment variables into typesafe structs
Add the following to your Cargo.toml
file.
[dependencies]
envy = "0.3"
A typical envy usage looks like the following. 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
๐ญ Consider this crate a cousin of envy-store, a crate for deserializing AWS parameter store values into into typesafe structs.
- error handling/reporting
Doug Tangren (softprops) 2016-2017