pub struct Input<T, C = NoCommand>where
T: 'static,
C: 'static,{Show 18 fields
pub key: &'static str,
pub ty: Type,
pub default: Option<T>,
pub allowed: &'static [&'static str],
pub separators: &'static [char],
pub required: bool,
pub stability: Stability,
pub since: Since,
pub deprecation: Option<Deprecation>,
pub group: &'static str,
pub maps_to: Option<ConfigKeyRef>,
pub example: &'static str,
pub observe: Option<&'static str>,
pub reviewed: Option<ReviewDate>,
pub summary: &'static str,
pub env: Option<Env>,
pub arg: Option<Arg>,
pub subcommands: &'static [C],
}Expand description
One input a program accepts — its identity, its domain, and the doors it can arrive through.
A declaration is simultaneously the contract entry, the typed accessor, and a compile-checked symbol. Because there is only one artifact, the published contract cannot drift from the code that reads the value.
key is the identity and is transport-free; env and arg are bindings.
--log-level and APP_LOG_LEVEL are not two settings, they are one setting
with two doors, which is why they share a type, a domain, and a default.
use argenv::*;
pub const LOG_LEVEL: Input<LogLevel> = Input {
key: "log_level",
ty: Type::Enum,
default: Some(LogLevel::Info),
allowed: LogLevel::TOKENS,
env: Some(Env::new("APP_LOG_LEVEL")),
arg: Some(Arg { value_name: "LEVEL", ..Arg::pair("log-level", 'l') }),
summary: "Log verbosity",
..Input::EMPTY
};
assert!(LOG_LEVEL.check().is_empty());
assert_eq!(LOG_LEVEL.to_record().usage(), "-l, --log-level <LEVEL>");Fields§
§key: &'static strRequired. Transport-free identity, snake_case.
This is what the contract, the resolver, and every generated binding join on. It is deliberately not a variable name or a flag: an input keeps its identity when a binding is renamed or a second one is added.
ty: TypeRequired. The kind of value, which also fixes how many values the
argument form takes: none for Type::Bool, one for everything else.
default: Option<T>The value used when the input is absent — the real typed T, so an
impossible default cannot be written down.
allowed: &'static [&'static str]Accepted tokens for Type::Enum and Type::List.
Point this at the domain type’s own TOKENS const so the contract and
the parser cannot disagree.
separators: &'static [char]Characters that separate items in a Type::List value.
required: boolWhether the program requires this input.
stability: StabilityHow much a consumer may rely on this input.
since: SinceThe version in which this input was introduced.
deprecation: Option<Deprecation>Present if and only if stability == Stability::Deprecated.
group: &'static strA free-form grouping tag for documentation and help output.
maps_to: Option<ConfigKeyRef>A key in another configuration surface this input bridges to.
example: &'static strA copy-pasteable example, e.g. "--log-level warn".
observe: Option<&'static str>A field in the program’s resolved-configuration output that this input visibly changes — the hook for confirming a declaration empirically.
reviewed: Option<ReviewDate>The date a human last verified this entry, YYYY-MM-DD.
Hand-written on purpose: it asserts a person’s judgement, which no tool
can derive. None means nobody has vouched for the entry yet.
summary: &'static strWhat the input does, in prose.
env: Option<Env>How the value may arrive from the environment.
arg: Option<Arg>How the value may arrive from the argument vector.
subcommands: &'static [C]Restricts this input to one or more subcommands. Empty (the default) means always active, regardless of which subcommand — or none — was given.
C is the program’s own subcommand enum (the same type as the
dispatch input’s T — see the crate-level docs on subcommands), so
subcommands: &[Command::Add, Command::Import] is checked by the
compiler: a typo’d or removed variant fails to build, rather than
silently doing nothing at runtime. One option genuinely shared by
several subcommands (an --input-dir used by both build and run)
is declared once, with both listed here, instead of duplicated per
subcommand or wrongly made global.