Skip to main content

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}