1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
//! Reading a program's configuration out of environment variables.
//!
//! A program configured by the environment and nothing else — no files, no
//! defaults baked into an image, no service discovery — needs one place
//! that turns a variable into a value, so the rules that turn out to matter
//! are stated once. This is that place.
//!
//! # Three rules worth knowing before anything else
//!
//! **Blank is absent.** A variable set to `""`, or to spaces, means the
//! same thing as an unset variable. Deployments produce blank values
//! routinely — a templated value whose source was empty, an `.env` line
//! with nothing after the `=` — and treating those as "configured, to the
//! empty string" produces failures a long way from their cause. It applies
//! uniformly, including to integers, where the obvious implementation would
//! instead try to parse `""` and report a malformed number.
//!
//! **Every problem is reported at once.** [`Reader`] accumulates problems
//! rather than returning the first, so a program with four missing
//! variables says so once instead of over four restarts. Each getter
//! returns a usable value even when it failed, so a whole configuration
//! reads as one straight run of statements with no `?` after every line;
//! [`Reader::finish`] is what decides whether any of it was valid.
//!
//! **A secret never prints.** [`Secret`] holds one and renders as
//! `<redacted>` through both [`Debug`] and [`std::fmt::Display`] — not
//! `Debug` alone, which is the common half-measure that leaves every
//! `Display`-based logging macro wide open. A configuration struct ends up
//! in a log line eventually, and a connection string with an access key in
//! it must not be what is there.
//!
//! # Two smaller decisions
//!
//! **An unparseable value is never a silent fallback.** [`Reader::integer_or`]
//! takes the default *and records the problem*, because a program quietly
//! running on a default nobody chose is harder to diagnose than one that
//! will not start.
//!
//! **Booleans are read strictly.** [`parse_bool`] accepts four spellings
//! each way and answers `None` to anything else, rather than the tempting
//! "not false-ish, therefore true" — under which `ENABLED=disabled` comes
//! out true and the deployment looks configured.
//! [`parse_bool_lenient`] is there for an existing estate that already
//! depends on that behaviour.
//!
//! # Examples
//!
//! ```
//! use env_reader::Reader;
//!
//! let mut reader = Reader::from_pairs([
//! ("SERVICE_NAME", "orders"),
//! ("PORT", "8443"),
//! ("REGION", " "), // blank: the same as absent
//! ]);
//!
//! let service: String = reader.required_string("SERVICE_NAME");
//! let port: u16 = reader.integer_or("PORT", 8080);
//! let region: Option<String> = reader.optional_string("REGION");
//!
//! reader.finish().expect("the configuration is complete");
//! assert_eq!(service, "orders");
//! assert_eq!(port, 8443);
//! assert_eq!(region, None);
//! ```
//!
//! A whole configuration, with every problem reported together:
//!
//! ```
//! use env_reader::{Errors, Reader, Secret};
//!
//! #[derive(Debug)]
//! struct Config {
//! service_name: String,
//! port: u16,
//! database_password: Secret,
//! }
//!
//! fn load() -> Result<Config, Errors> {
//! let mut reader = Reader::from_pairs([("PORT", "eighty")]);
//! let config = Config {
//! service_name: reader.required_string("SERVICE_NAME"),
//! port: reader.integer_or("PORT", 8080),
//! database_password: reader.required_secret("DB_PASSWORD"),
//! };
//! reader.finish_with(config)
//! }
//!
//! let errors = load().unwrap_err();
//! assert_eq!(errors.len(), 3, "all three, not just the first");
//! ```
//!
//! # Features
//!
//! - `uuid` — adds [`Reader::required_uuid`] and
//! [`Reader::optional_uuid`]. Off by default; with it off this crate has
//! no dependencies at all.
pub use ;
pub use Reader;
pub use Secret;
pub use ;