argenv/binding.rs
1//! The two doors a value can arrive through: [`Arg`] and [`Env`].
2//!
3//! An input's *identity* (its `key`) is separate from how it is *addressed*.
4//! That separation is the whole reason argv and envp share one model instead of
5//! needing two: everything except addressing is common to both.
6
7/// The environment binding: the variable name a value may arrive under.
8#[derive(Clone, Copy, Debug)]
9pub struct Env {
10 /// The variable name, e.g. `"APP_LOG_LEVEL"`.
11 pub name: &'static str,
12 /// Other names still honoured, so a legacy name is recognised rather than
13 /// reported as a mistake.
14 pub aliases: &'static [&'static str],
15}
16
17impl Env {
18 /// A binding with no aliases: `Env { name: "APP_X", ..Env::EMPTY }`.
19 pub const EMPTY: Env = Env {
20 name: "",
21 aliases: &[],
22 };
23
24 /// Construct a plain binding.
25 pub const fn new(name: &'static str) -> Env {
26 Env { name, aliases: &[] }
27 }
28}
29
30/// The argument-vector binding: the flag a value may arrive under.
31///
32/// How many values the flag takes is **not** declared here — it follows from the
33/// input's [`crate::Type`]. A boolean flag takes none and means *true* by its
34/// presence; anything else takes exactly one. Deriving it removes a field that
35/// could contradict the type, and the derived arity is still written out
36/// explicitly in the published contract so no other language has to re-derive it.
37#[derive(Clone, Copy, Debug)]
38pub struct Arg {
39 /// The long form without dashes, e.g. `"log-level"` for `--log-level`.
40 /// Mutually exclusive with `position` — see [`Arg::positional`].
41 pub long: Option<&'static str>,
42 /// The short form without its dash, e.g. `'l'` for `-l`.
43 /// Mutually exclusive with `position` — see [`Arg::positional`].
44 pub short: Option<char>,
45 /// Whether `--no-<long>` is accepted to force the value off. Booleans only.
46 pub negatable: bool,
47 /// Whether the flag may be repeated, accumulating values. Lists only.
48 pub repeatable: bool,
49 /// The placeholder shown in help for the value, e.g. `"LEVEL"` in
50 /// `--log-level <LEVEL>`. Ignored for booleans, which take no value.
51 pub value_name: &'static str,
52 /// A bare positional slot instead of a `--flag`, addressed by position
53 /// rather than by name — see [`Arg::positional`].
54 ///
55 /// For an input with an empty [`crate::Input::subcommands`] list, this is
56 /// the position among all positionals in the invocation (`Some(0)` is the
57 /// first). For an input scoped to one or more subcommands, it is the
58 /// position *after* the subcommand token itself — `Some(0)` is the first
59 /// positional following the subcommand, letting two different
60 /// subcommands each use their own `Some(0)` without conflict, since only
61 /// one subcommand is ever active in a given invocation.
62 pub position: Option<u16>,
63}
64
65impl Arg {
66 /// A binding with nothing set: `Arg { long: Some("x"), ..Arg::EMPTY }`.
67 pub const EMPTY: Arg = Arg {
68 long: None,
69 short: None,
70 negatable: false,
71 repeatable: false,
72 value_name: "",
73 position: None,
74 };
75
76 /// A long flag, e.g. `Arg::long("log-level")` for `--log-level`.
77 pub const fn long(long: &'static str) -> Arg {
78 Arg {
79 long: Some(long),
80 ..Arg::EMPTY
81 }
82 }
83
84 /// A short flag, e.g. `Arg::short('l')` for `-l`.
85 pub const fn short(short: char) -> Arg {
86 Arg {
87 short: Some(short),
88 ..Arg::EMPTY
89 }
90 }
91
92 /// Both forms, e.g. `Arg::pair("log-level", 'l')`.
93 pub const fn pair(long: &'static str, short: char) -> Arg {
94 Arg {
95 long: Some(long),
96 short: Some(short),
97 ..Arg::EMPTY
98 }
99 }
100
101 /// A bare positional, e.g. `Arg::positional(0)` for the first one.
102 ///
103 /// Not a `--flag`: consumed by position in argv, the same slot a
104 /// resolver's positionals list already collects (see `argenv-resolve`)
105 /// — this lets a specific one be declared, typed, and documented like
106 /// any other input.
107 pub const fn positional(position: u16) -> Arg {
108 Arg {
109 position: Some(position),
110 ..Arg::EMPTY
111 }
112 }
113}