Skip to main content

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}