clap_layers/lib.rs
1//! Correct layered configuration for [clap](https://crates.io/crates/clap).
2//!
3//! One derive macro gives a clap application layered configuration with the
4//! precedence users actually expect:
5//!
6//! | Priority | Layer | Example |
7//! | -------- | ----------------- | -------------------------------- |
8//! | 1 | Explicit CLI flag | `--port 8080` |
9//! | 2 | Environment var | `MYAPP_PORT=8080` |
10//! | 3 | Config file | `port = 8080` in `myapp.toml` |
11//! | 4 | Built-in default | `#[arg(default_value_t = 3000)]` |
12//!
13//! The subtle part — and the reason this crate exists — is layer 1 versus
14//! layer 4. A config-file value must override a clap *default*, but must lose
15//! to a flag the user *explicitly typed*, **even when the typed value happens to
16//! equal the default**. `clap-layers` gets this right by reading clap's
17//! [`ValueSource`](clap::parser::ValueSource) rather than by wrapping every
18//! field in `Option<T>`, so `--help` keeps showing real defaults.
19//!
20//! # Example
21//!
22//! ```
23//! use clap::Parser;
24//! use clap_layers::{Env, Layered};
25//!
26//! #[derive(Parser, Layered, Debug)]
27//! #[layered(file = "myapp.toml", env_prefix = "MYAPP")]
28//! struct Config {
29//! /// Port to listen on
30//! #[arg(long, default_value_t = 3000)]
31//! port: u16,
32//! }
33//!
34//! // `Config::layered()` reads the real process arguments and environment.
35//! // `layered_from` is the same engine with both injected, which is what makes
36//! // configuration testable:
37//! let env = Env::from_iter([("MYAPP_PORT", "8080")]);
38//!
39//! // No flag typed: the environment wins over the default.
40//! let cfg = Config::layered_from(["myapp"], &env)?;
41//! assert_eq!(cfg.port, 8080);
42//!
43//! // Flag explicitly typed: it beats the environment.
44//! let cfg = Config::layered_from(["myapp", "--port", "9999"], &env)?;
45//! assert_eq!(cfg.port, 9999);
46//!
47//! // Even when the typed value *equals* the default, it is still explicit.
48//! let cfg = Config::layered_from(["myapp", "--port", "3000"], &env)?;
49//! assert_eq!(cfg.port, 3000);
50//! # Ok::<(), clap_layers::LayeredError>(())
51//! ```
52//!
53//! # Reporting errors
54//!
55//! [`LayeredError`] carries its message in its [`Display`](std::fmt::Display)
56//! form. Rust prints the `Debug` form for a `Result` returned from `main`, so
57//! `let cfg = Config::layered()?` in `main` reports
58//! `Invalid { field: "port", .. }` rather than the attributed message. Print it
59//! yourself instead:
60//!
61//! ```no_run
62//! # use clap::Parser;
63//! # use clap_layers::Layered;
64//! # #[derive(Parser, Layered, Debug)]
65//! # struct Config {
66//! # #[arg(long, default_value_t = 3000)]
67//! # port: u16,
68//! # }
69//! let cfg = Config::layered().unwrap_or_else(|e| {
70//! eprintln!("configuration error: {e}");
71//! std::process::exit(1);
72//! });
73//! ```
74//!
75//! ```text
76//! configuration error: invalid value 'banana' for 'port' — from environment variable MYAPP_PORT (invalid type: string, expected u16)
77//! ```
78//!
79//! # Field types
80//!
81//! Values from the environment and config file are decoded with
82//! [`serde`], so any field type implementing [`serde::Deserialize`] works —
83//! including `u16`, `bool`, `String`, `Vec<T>`, `Option<T>`, and `#[derive(Deserialize)]`
84//! enums. No `FromStr` bound is required.
85//!
86//! # Per-field control
87//!
88//! - `#[layered(no_env)]` — never read this field from the environment.
89//! - `#[layered(no_file)]` — never read this field from the config file.
90//! - `#[layered(no_cli)]` — never expose this field as a CLI flag. Requires
91//! `#[arg(skip)]` so clap leaves the field alone; the macro enforces this.
92//!
93//! # Environment variables
94//!
95//! The environment layer is **only active when `env_prefix` is set**. Without a
96//! prefix, a field named `path` would read the ambient `PATH`, so `clap-layers`
97//! disables the layer rather than guess. Names are `PREFIX_FIELD` uppercased:
98//! `env_prefix = "MYAPP"` maps field `db_password` to `MYAPP_DB_PASSWORD`.
99
100#![forbid(unsafe_code)]
101#![deny(missing_docs)]
102// A library returns `Result`; it must not abort its caller's process. Relaxed
103// under `cfg(test)`, where unwrapping is how a test asserts.
104#![cfg_attr(
105 not(test),
106 warn(clippy::unwrap_used, clippy::expect_used, clippy::panic)
107)]
108#![cfg_attr(docsrs, feature(doc_cfg))]
109
110use std::collections::BTreeMap;
111use std::ffi::OsString;
112use std::path::PathBuf;
113
114mod source;
115
116#[doc(hidden)]
117pub mod __private;
118
119/// Re-export of the `clap` version this crate is built against.
120///
121/// [`LayeredError::Cli`] wraps a [`clap::Error`], so this re-export lets you
122/// handle it without depending on a matching `clap` version yourself.
123pub use clap;
124
125pub use clap_layers_proc::Layered;
126
127/// Which layer supplied a configuration value.
128///
129/// Used in [`LayeredError::Invalid`] to attribute a bad value to the exact
130/// layer that produced it.
131///
132/// Only the layers this crate decodes values for appear here. A malformed CLI
133/// argument is clap's to report, and surfaces as [`LayeredError::Cli`], so
134/// there is no `CliFlag` variant to construct. This enum is `#[non_exhaustive]`,
135/// so `--dump-config` can add the remaining layers in a later version without a
136/// breaking change.
137#[derive(Debug, Clone, PartialEq, Eq, Hash)]
138#[non_exhaustive]
139pub enum SourceLayer {
140 /// An environment variable, holding the variable's name.
141 EnvVar(String),
142 /// A configuration file, holding its path and the 1-based line number.
143 ConfigFile {
144 /// Path to the configuration file.
145 path: PathBuf,
146 /// 1-based line number the value appears on.
147 line: usize,
148 },
149}
150
151impl std::fmt::Display for SourceLayer {
152 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
153 match self {
154 SourceLayer::EnvVar(var) => write!(f, "environment variable {var}"),
155 SourceLayer::ConfigFile { path, line } => {
156 write!(f, "{}, line {line}", path.display())
157 }
158 }
159 }
160}
161
162/// Errors produced while loading layered configuration.
163///
164/// Every variant names the layer it came from, so a bad value is never reported
165/// as an anonymous post-merge failure.
166#[derive(thiserror::Error, Debug)]
167#[non_exhaustive]
168pub enum LayeredError {
169 /// Command-line parsing failed, or clap was asked to display help/version.
170 ///
171 /// [`Layered::layered`] never returns this — it defers to
172 /// [`clap::Error::exit`], matching [`clap::Parser::parse`]. It is only
173 /// returned by [`Layered::layered_from`].
174 #[error(transparent)]
175 Cli(#[from] clap::Error),
176
177 /// The configuration file exists but could not be read.
178 ///
179 /// A *missing* config file is not an error; the layer is simply skipped.
180 #[error("could not read config file '{}': {source}", path.display())]
181 Io {
182 /// Path to the file that could not be read.
183 path: PathBuf,
184 /// The underlying I/O error.
185 #[source]
186 source: std::io::Error,
187 },
188
189 /// The configuration file is not valid TOML.
190 #[error("could not parse config file '{}' at line {line}, column {column}: {message}", path.display())]
191 Parse {
192 /// Path to the offending file.
193 path: PathBuf,
194 /// 1-based line number of the syntax error.
195 line: usize,
196 /// 1-based column number of the syntax error.
197 column: usize,
198 /// Message from the TOML parser.
199 message: String,
200 },
201
202 /// A layer supplied a value that could not be decoded into the field's type.
203 #[error("invalid value '{value}' for '{field}' — from {layer} ({message})")]
204 Invalid {
205 /// Name of the field that could not be populated.
206 field: String,
207 /// The offending value, as written in the source.
208 value: String,
209 /// The layer that supplied the value.
210 layer: SourceLayer,
211 /// Why decoding failed, e.g. `invalid type: string, expected u16`.
212 message: String,
213 },
214}
215
216/// A snapshot of environment variables for the environment layer.
217///
218/// Taking the environment as an explicit value — rather than reading the
219/// process environment deep inside the merge engine — is what makes
220/// [`Layered::layered_from`] testable and safe to run in parallel tests.
221///
222/// # Examples
223///
224/// ```
225/// use clap_layers::Env;
226///
227/// let env = Env::from_iter([("MYAPP_PORT", "8080")]);
228/// assert_eq!(env.get("MYAPP_PORT"), Some("8080"));
229/// assert_eq!(env.get("MYAPP_HOST"), None);
230/// ```
231#[derive(Debug, Clone, Default, PartialEq, Eq)]
232pub struct Env {
233 vars: BTreeMap<String, String>,
234}
235
236impl Env {
237 /// Capture the current process environment.
238 ///
239 /// Variables whose name or value is not valid UTF-8 are skipped.
240 #[must_use]
241 pub fn from_system() -> Self {
242 Self {
243 vars: std::env::vars_os()
244 .filter_map(|(k, v)| Some((k.into_string().ok()?, v.into_string().ok()?)))
245 .collect(),
246 }
247 }
248
249 /// An environment with no variables set.
250 #[must_use]
251 pub fn empty() -> Self {
252 Self::default()
253 }
254
255 /// Look up a variable by name.
256 #[must_use]
257 pub fn get(&self, key: &str) -> Option<&str> {
258 self.vars.get(key).map(String::as_str)
259 }
260}
261
262/// Generic over the key and value types so both `("A", "1")` and owned
263/// `String` pairs work, which keeps test setup free of `to_string()` noise.
264impl<K, V> FromIterator<(K, V)> for Env
265where
266 K: Into<String>,
267 V: Into<String>,
268{
269 fn from_iter<I: IntoIterator<Item = (K, V)>>(iter: I) -> Self {
270 Self {
271 vars: iter
272 .into_iter()
273 .map(|(key, value)| (key.into(), value.into()))
274 .collect(),
275 }
276 }
277}
278
279/// Load a struct from all configuration layers.
280///
281/// Implemented by `#[derive(Layered)]`; do not implement it by hand. The
282/// derived type must also derive [`clap::Parser`].
283pub trait Layered: Sized {
284 /// Load configuration from the process arguments and environment.
285 ///
286 /// This is the entry point for applications. Like [`clap::Parser::parse`],
287 /// it does **not** return CLI errors: on a bad flag it prints a diagnostic
288 /// and exits non-zero, and on `--help` / `--version` it prints and exits
289 /// zero. Errors from the file and environment layers are still returned.
290 ///
291 /// Use [`Layered::layered_from`] in tests.
292 ///
293 /// # Errors
294 ///
295 /// Returns [`LayeredError`] if the config file is unreadable or malformed,
296 /// or if any layer supplies a value that cannot be decoded.
297 fn layered() -> Result<Self, LayeredError> {
298 match Self::layered_from(std::env::args_os(), &Env::from_system()) {
299 Err(LayeredError::Cli(e)) => e.exit(),
300 other => other,
301 }
302 }
303
304 /// Load configuration from explicit arguments and an explicit environment.
305 ///
306 /// The testable form of [`Layered::layered`]: nothing is read from process
307 /// globals, so tests are hermetic and can run in parallel. CLI errors are
308 /// returned as [`LayeredError::Cli`] rather than exiting.
309 ///
310 /// # Errors
311 ///
312 /// Returns [`LayeredError::Cli`] if argument parsing fails (including
313 /// `--help`), or another [`LayeredError`] if a layer is unreadable,
314 /// malformed, or supplies an undecodable value.
315 fn layered_from<I, T>(args: I, env: &Env) -> Result<Self, LayeredError>
316 where
317 I: IntoIterator<Item = T>,
318 T: Into<OsString> + Clone;
319}
320
321#[cfg(test)]
322mod tests {
323 use super::*;
324
325 #[test]
326 fn source_layer_display() {
327 assert_eq!(
328 SourceLayer::EnvVar("MYAPP_PORT".to_string()).to_string(),
329 "environment variable MYAPP_PORT"
330 );
331 assert_eq!(
332 SourceLayer::ConfigFile {
333 path: PathBuf::from("config.toml"),
334 line: 12,
335 }
336 .to_string(),
337 "config.toml, line 12"
338 );
339 }
340
341 /// The exact wording promised by the project's correctness bar.
342 #[test]
343 fn invalid_error_is_source_attributed() {
344 let err = LayeredError::Invalid {
345 field: "port".to_string(),
346 value: "foo".to_string(),
347 layer: SourceLayer::ConfigFile {
348 path: PathBuf::from("config.toml"),
349 line: 12,
350 },
351 message: "invalid type: string, expected u16".to_string(),
352 };
353 assert!(
354 err.to_string()
355 .starts_with("invalid value 'foo' for 'port' — from config.toml, line 12"),
356 "got: {err}"
357 );
358 }
359
360 #[test]
361 fn invalid_error_names_the_env_var() {
362 let err = LayeredError::Invalid {
363 field: "port".to_string(),
364 value: "banana".to_string(),
365 layer: SourceLayer::EnvVar("MYAPP_PORT".to_string()),
366 message: "invalid digit".to_string(),
367 };
368 assert!(
369 err.to_string()
370 .contains("from environment variable MYAPP_PORT"),
371 "got: {err}"
372 );
373 }
374
375 #[test]
376 fn io_error_names_the_path() {
377 let err = LayeredError::Io {
378 path: PathBuf::from("config.toml"),
379 source: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"),
380 };
381 assert!(err.to_string().contains("config.toml"), "got: {err}");
382 }
383
384 #[test]
385 fn env_from_iter_and_get() {
386 let env = Env::from_iter([("A".to_string(), "1".to_string())]);
387 assert_eq!(env.get("A"), Some("1"));
388 assert_eq!(env.get("B"), None);
389 assert_eq!(Env::empty().get("A"), None);
390 }
391
392 #[test]
393 fn env_from_system_reads_process_env() {
394 // `Env::from_system` is the one place that touches process globals.
395 let env = Env::from_system();
396 // PATH is set on every platform CI runs on.
397 assert!(env.get("PATH").is_some() || env.get("Path").is_some());
398 }
399}