de_env/lib.rs
1//! # `de_env`
2//!
3//! _**De**serialize **env**ironment variables into a struct._
4//!
5//! ---
6//!
7//! You may be looking for:
8//!
9//! - [Git repository](https://github.com/malobre/de_env)
10//! - [Crates.io](https://crates.io/crates/de_env)
11//!
12//! ## Example
13//!
14//! Assuming we have a `TIMEOUT` and `HOST` environment variable:
15//!
16//! ```rust
17//! #[derive(serde::Deserialize, Debug)]
18//! #[serde(rename_all = "SCREAMING_SNAKE_CASE")]
19//! struct Config {
20//! timeout: u16,
21//! host: std::net::IpAddr,
22//! }
23//!
24//! # std::env::set_var("TIMEOUT", "12");
25//! # std::env::set_var("HOST", "127.0.0.1");
26//! let config: Config = de_env::from_env()?;
27//!
28//! println!("{config:#?}");
29//! # Ok::<(), de_env::Error>(())
30//! ```
31//!
32//! ## Supported Primitives
33//!
34//! - String slices
35//! - Chars
36//! - Numbers (parsed with their respective [`FromStr`](std::str::FromStr) implementations)
37//! - Booleans (see [boolean parsing](#boolean-parsing))
38//!
39//! ## Boolean Parsing
40//!
41//! **Boolean parsing is case-insensitive.**
42//!
43//! If the `truthy-falsy` feature is enabled (default):
44//!
45//! - Truthy values:
46//! - `true` or its shorthand `t`
47//! - `yes` or its shorthand `y`
48//! - `on`
49//! - `1`
50//! - Falsy values:
51//! - `false` or its shorthand `f`
52//! - `no` or its shorthand `n`
53//! - `off`
54//! - `0`
55//!
56//! If the `truthy-falsy` feature is disabled, only `true` and `false` are
57//! considered valid booleans.
58//!
59//! ## Enums
60//!
61//! **Only unit variants can be deserialized.**
62//!
63//! Assuming we have a `LOG_LEVEL` environment variable set to `INFO` or `WARN`:
64//!
65//! ```rust
66//! #[derive(serde::Deserialize, Debug)]
67//! #[serde(rename_all = "SCREAMING_SNAKE_CASE")]
68//! enum Level {
69//! Info,
70//! Warn
71//! }
72//!
73//! #[derive(serde::Deserialize, Debug)]
74//! #[serde(rename_all = "SCREAMING_SNAKE_CASE")]
75//! struct Config {
76//! log_level: Level,
77//! }
78//!
79//! # std::env::set_var("LOG_LEVEL", "INFO");
80//! let config: Config = de_env::from_env()?;
81//!
82//! println!("{config:#?}");
83//! # Ok::<(), de_env::Error>(())
84//! ```
85//!
86//! ## Unsupported Types
87//!
88//! The goal of this crate is to deserialize environment variables into a **struct**, no other type
89//! is supported at top level. Custom types must be able to deserialize from [supported primitives].
90//!
91//! [supported primitives]: #supported-primitives
92
93mod de;
94mod error;
95#[cfg(test)]
96mod tests;
97
98pub use de::{from_env, from_env_prefixed, from_iter};
99pub use error::{Error, Result};