Skip to main content

consumer/
consumer.rs

1//! A fully-documented model using every argenv feature.
2//!
3//! This is what a real program looks like end to end: declare the model with
4//! doc comments, call `parse_and_lint`, read typed values. Nothing else.
5//!
6//! ```text
7//! cargo run -p argenv --example consumer -- --log-level warn -v
8//! cargo run -p argenv --example consumer -- --bogus-flag
9//! cargo test -p argenv --example consumer
10//! ```
11use argenv_resolve::*;
12use std::path::PathBuf;
13
14/// A render scale constrained to `0.1..=1.0`, stored as per-mille.
15///
16/// A bare `f32` would admit `5.0` and `NaN`, which are not render scales.
17/// Storing the bounded decimal as an integer makes the range check
18/// `const`-evaluable and sidesteps float equality entirely.
19#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize)]
20#[serde(into = "f32")]
21pub struct RenderScale(u16);
22
23impl RenderScale {
24    pub const FULL: RenderScale = RenderScale::from_permille(1000);
25
26    pub const fn from_permille(p: u16) -> RenderScale {
27        assert!(
28            p >= 100 && p <= 1000,
29            "render scale must be within 0.1..=1.0"
30        );
31        RenderScale(p)
32    }
33
34    pub fn as_f32(self) -> f32 {
35        self.0 as f32 / 1000.0
36    }
37}
38impl From<RenderScale> for f32 {
39    fn from(r: RenderScale) -> f32 {
40        r.as_f32()
41    }
42}
43impl FromRaw for RenderScale {
44    fn from_raw(s: &str) -> Option<RenderScale> {
45        let v: f32 = s.trim().parse().ok()?;
46        if !(0.1..=1.0).contains(&v) {
47            return None;
48        }
49        Some(RenderScale((v * 1000.0).round() as u16))
50    }
51}
52
53// Compile-checked successor reference: rename or delete `HUD` and this stops
54// compiling, so the pointer can never dangle.
55fn hud_replacement() -> &'static str {
56    Contract::HUD.key
57}
58
59contract! {
60    /// Both doors: a flag and a variable, one setting.
61    LOG_LEVEL: LogLevel = Input {
62        key:       "log_level",
63        ty:        Type::Enum,
64        default:   Some(LogLevel::Info),
65        allowed:   LogLevel::TOKENS,
66        env:       Some(Env::new("MYAPP_LOG_LEVEL")),
67        arg:       Some(Arg { value_name: "LEVEL", ..Arg::pair("log-level", 'l') }),
68        stability: Stability::Stable,
69        since:     Since::This,
70        group:     "logging",
71        example:   "--log-level warn",
72        reviewed:  Some(ReviewDate::parse("2026-07-21")),
73        summary:   "Log verbosity",
74        ..Input::EMPTY
75    };
76
77    /// A boolean flag: presence is the value, and it can be negated.
78    HDR: bool = Input {
79        key:       "hdr",
80        ty:        Type::Bool,
81        default:   Some(false),
82        env:       Some(Env::new("MYAPP_HDR")),
83        arg:       Some(Arg { negatable: true, ..Arg::long("hdr") }),
84        stability: Stability::Stable,
85        since:     Since::This,
86        group:     "display",
87        maps_to:   Some(ConfigKeyRef::new("display.enableHDR")),
88        example:   "--hdr",
89        observe:   Some("hdr_enabled"),
90        reviewed:  Some(ReviewDate::parse("2026-07-21")),
91        summary:   "Expose HDR output to the application",
92        ..Input::EMPTY
93    };
94
95    /// A repeatable list: `--hud fps --hud gpuload` accumulates.
96    HUD: String = Input {
97        key:        "hud",
98        ty:         Type::List,
99        allowed:    &["fps", "frametimes", "gpuload", "memory", "version"],
100        separators: &[',', ';'],
101        env:        Some(Env::new("MYAPP_HUD")),
102        arg:        Some(Arg { repeatable: true, value_name: "ELEMENT", ..Arg::long("hud") }),
103        stability:  Stability::Stable,
104        since:      Since::This,
105        group:      "display",
106        example:    "--hud fps --hud gpuload",
107        reviewed:   Some(ReviewDate::parse("2026-07-21")),
108        summary:    "Overlay elements to display",
109        ..Input::EMPTY
110    };
111
112    /// Environment only: no flag, because it is set by a launcher, not a person.
113    LOG_PATH: PathBuf = Input {
114        key:   "log_path",
115        ty:    Type::Path,
116        // The variable was renamed; the old name is still honoured.
117        env:   Some(Env { name: "MYAPP_LOG_PATH", aliases: &["MYAPP_LOGFILE"] }),
118        group: "logging",
119        ..Input::EMPTY
120    };
121
122    /// Argument only: a bounded decimal, using a program-local domain type.
123    RENDER_SCALE: RenderScale = Input {
124        key:       "render_scale",
125        ty:        Type::Float,
126        default:   Some(RenderScale::FULL),
127        arg:       Some(Arg { value_name: "FACTOR", ..Arg::long("render-scale") }),
128        stability: Stability::Stable,
129        since:     Since::This,
130        group:     "display",
131        example:   "--render-scale 0.75",
132        reviewed:  Some(ReviewDate::parse("2026-07-21")),
133        summary:   "Internal render scale before upscaling",
134        ..Input::EMPTY
135    };
136
137    /// Three states, where a boolean would be a lie.
138    ACCEL: Tristate = Input {
139        key:       "accel",
140        ty:        Type::Enum,
141        default:   Some(Tristate::Auto),
142        allowed:   Tristate::TOKENS,
143        env:       Some(Env::new("MYAPP_ACCEL")),
144        arg:       Some(Arg { value_name: "MODE", ..Arg::long("accel") }),
145        stability: Stability::Stable,
146        since:     Since::This,
147        group:     "display",
148        example:   "--accel auto",
149        reviewed:  Some(ReviewDate::parse("2026-07-21")),
150        summary:   "Hardware acceleration; auto enables it when available",
151        ..Input::EMPTY
152    };
153
154    /// On its way out, pointing at its successor.
155    PROFILE: bool = Input {
156        key:       "profile",
157        ty:        Type::Bool,
158        default:   Some(false),
159        env:       Some(Env::new("MYAPP_PROFILE")),
160        arg:       Some(Arg::long("profile")),
161        stability: Stability::Deprecated,
162        since:     Since::This,
163        deprecation: Some(Deprecation {
164            since:       THIS_VERSION,
165            replaced_by: Some(hud_replacement),
166            migration:   "use --hud gpuload,frametimes instead",
167        }),
168        group:    "display",
169        reviewed: Some(ReviewDate::parse("2026-07-21")),
170        summary:  "Deprecated profiling overlay",
171        ..Input::EMPTY
172    };
173}
174
175fn main() {
176    // One call: parse argv+env, lint the result, fail on errors.
177    let resolved = Contract::parse_and_lint(OnProblems::FailOnError);
178
179    // Read typed values as often as needed — the resolution is cheap to clone.
180    let level = Contract::LOG_LEVEL.get_from_or_default(&resolved);
181    let hdr = Contract::HDR.get_from_or_default(&resolved);
182
183    eprintln!(
184        "log_level = {level:?} (from {:?}), hdr = {hdr:?} (from {:?})",
185        resolved.source("log_level"),
186        resolved.source("hdr")
187    );
188
189    // Emit the machine-readable contract — what `argenv lint` reads.
190    println!(
191        "{}",
192        serde_json::to_string_pretty(&document("myapp@a1b2c3d", &Contract::records())).unwrap()
193    );
194}
195
196#[cfg(test)]
197mod tests {
198    use super::*;
199    use std::collections::BTreeMap;
200
201    #[test]
202    fn the_model_satisfies_every_rule() {
203        assert!(
204            Contract::problems().is_empty(),
205            "{:#?}",
206            Contract::problems()
207        );
208    }
209
210    #[test]
211    fn an_argument_beats_an_environment_variable() {
212        let env: BTreeMap<String, String> =
213            [("MYAPP_LOG_LEVEL".to_string(), "error".to_string())].into();
214        let args = vec!["--log-level".to_string(), "warn".to_string()];
215        let r = Invocation {
216            args: &args,
217            env: &env,
218        }
219        .resolve(&Contract::records());
220        assert_eq!(Contract::LOG_LEVEL.get_from(&r), Some(LogLevel::Warn));
221        assert_eq!(r.source("log_level"), Some(Source::Arg));
222    }
223}