env-reader 0.1.0

Read configuration from environment variables: blank is absent, every problem is reported at once, and a secret never prints.
Documentation
//! 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.

#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used, clippy::panic))]

mod error;
mod reader;
mod secret;
mod value;

pub use error::{Error, Errors};
pub use reader::Reader;
pub use secret::Secret;
pub use value::{
    FALSE_SPELLINGS, TRUE_SPELLINGS, parse_bool, parse_bool_lenient, parse_csv, parse_separated,
    present,
};