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}