Skip to main content

argenv_resolve/
ext.rs

1//! [`InputResolveExt`] — [`Input`]'s runtime-reading methods, added from
2//! outside the data crate.
3//!
4//! `argenv::Input<T, C>` cannot have methods that take a [`Resolution`]
5//! defined on it directly: `Resolution` lives in this crate, which already
6//! depends on `argenv` for `Input` — a dependency back the other way would
7//! be circular. An extension trait is the standard, idiomatic way around
8//! this in Rust: implemented here, for a type declared elsewhere, callable
9//! with ordinary method syntax the moment this trait is in scope (which
10//! `use argenv_resolve::*;` already brings in for every consumer).
11
12use crate::{EnvSource, ProcessEnv, Resolution};
13use argenv::{FromRaw, Input};
14
15/// Runtime-reading methods for [`Input`], added by this crate.
16///
17/// Implemented for every `Input<T, C>` whose `T` implements [`FromRaw`] —
18/// which is every `Input` that could ever have a value read out of it.
19/// `use argenv_resolve::*;` brings this into scope automatically; you will
20/// not usually name it directly, just call `.get_from(&resolution)` etc.
21pub trait InputResolveExt<T> {
22    /// Every environment name this input answers to.
23    fn env_names(&self) -> Vec<&'static str>;
24
25    /// Read and parse from the process environment. `None` means absent
26    /// **or** invalid — never a silent empty string.
27    fn get(&self) -> Option<T>;
28
29    /// Read and parse from `env`.
30    ///
31    /// Use this to check an environment being assembled for a child
32    /// process, to read a snapshot captured elsewhere, or to test without
33    /// mutating global process state.
34    fn get_in(&self, env: &impl EnvSource) -> Option<T>;
35
36    /// Read and parse from a resolved invocation, honouring precedence
37    /// across both bindings.
38    fn get_from(&self, resolution: &Resolution) -> Option<T>;
39
40    /// Whether the input is present in the process environment.
41    fn is_set(&self) -> bool;
42
43    /// Whether the input is present in `env`.
44    fn is_set_in(&self, env: &impl EnvSource) -> bool;
45
46    /// The raw, unparsed value from the process environment, if set.
47    fn raw(&self) -> Option<String>;
48
49    /// The raw, unparsed value from `env`, if set.
50    fn raw_in(&self, env: &impl EnvSource) -> Option<String>;
51}
52
53impl<T, C> InputResolveExt<T> for Input<T, C>
54where
55    T: 'static + FromRaw,
56{
57    fn env_names(&self) -> Vec<&'static str> {
58        self.env
59            .into_iter()
60            .flat_map(|e| std::iter::once(e.name).chain(e.aliases.iter().copied()))
61            .collect()
62    }
63
64    fn get(&self) -> Option<T> {
65        self.get_in(&ProcessEnv)
66    }
67
68    fn get_in(&self, env: &impl EnvSource) -> Option<T> {
69        InputResolveExt::raw_in(self, env).and_then(|s| T::from_raw(&s))
70    }
71
72    fn get_from(&self, resolution: &Resolution) -> Option<T> {
73        resolution.raw(self.key).and_then(T::from_raw)
74    }
75
76    fn is_set(&self) -> bool {
77        self.is_set_in(&ProcessEnv)
78    }
79
80    fn is_set_in(&self, env: &impl EnvSource) -> bool {
81        InputResolveExt::env_names(self)
82            .into_iter()
83            .any(|n| env.get(n).is_some())
84    }
85
86    fn raw(&self) -> Option<String> {
87        self.raw_in(&ProcessEnv)
88    }
89
90    fn raw_in(&self, env: &impl EnvSource) -> Option<String> {
91        InputResolveExt::env_names(self)
92            .into_iter()
93            .find_map(|n| env.get(n))
94    }
95}
96
97/// [`get_from_or_default`](InputResolveDefaultExt::get_from_or_default) — a
98/// separate trait because it needs `T: Clone`, which not every `Input` value
99/// type provides, the same split `argenv::Input`'s own impl blocks already
100/// made before this trait existed.
101pub trait InputResolveDefaultExt<T> {
102    /// Read from a resolved invocation, falling back to the declared default.
103    fn get_from_or_default(&self, resolution: &Resolution) -> Option<T>;
104}
105
106impl<T, C> InputResolveDefaultExt<T> for Input<T, C>
107where
108    T: 'static + FromRaw + Clone,
109{
110    fn get_from_or_default(&self, resolution: &Resolution) -> Option<T> {
111        self.get_from(resolution).or_else(|| self.default.clone())
112    }
113}