Skip to main content

Input

Struct Input 

Source
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 str

Required. 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: Type

Required. 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: bool

Whether the program requires this input.

§stability: Stability

How much a consumer may rely on this input.

§since: Since

The version in which this input was introduced.

§deprecation: Option<Deprecation>

Present if and only if stability == Stability::Deprecated.

§group: &'static str

A 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 str

A 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 str

What 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.

Implementations§

Source§

impl<T, C> Input<T, C>
where T: 'static, C: 'static,

Source

pub const EMPTY: Input<T, C>

The empty baseline: Input { key: "...", ty: ..., ..Input::EMPTY }.

Source

pub const fn arity(&self) -> u8

How many values the argument form consumes: 0 for a boolean flag whose presence is the value, 1 otherwise. Derived, never declared.

Source

pub fn check(&self) -> Vec<String>

Validate this declaration against the contract’s rules.

Returns human-readable problems; empty means valid. Run it in a test so a bad declaration fails the build rather than a user’s launch.

Source§

impl<T, C> Input<T, C>
where T: 'static + Serialize, C: 'static + Serialize,

Source

pub fn to_record(&self) -> Record

Project this declaration down to the portable Record the contract describes.

Trait Implementations§

Source§

impl<T, C> Debug for Input<T, C>
where T: Debug + 'static, C: Debug + 'static,

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
Source§

impl<T, C> InputResolveDefaultExt<T> for Input<T, C>
where T: 'static + FromRaw + Clone,

Source§

fn get_from_or_default(&self, resolution: &Resolution) -> Option<T>

Read from a resolved invocation, falling back to the declared default.
Source§

impl<T, C> InputResolveExt<T> for Input<T, C>
where T: 'static + FromRaw,

Source§

fn env_names(&self) -> Vec<&'static str>

Every environment name this input answers to.
Source§

fn get(&self) -> Option<T>

Read and parse from the process environment. None means absent or invalid — never a silent empty string.
Source§

fn get_in(&self, env: &impl EnvSource) -> Option<T>

Read and parse from env. Read more
Source§

fn get_from(&self, resolution: &Resolution) -> Option<T>

Read and parse from a resolved invocation, honouring precedence across both bindings.
Source§

fn is_set(&self) -> bool

Whether the input is present in the process environment.
Source§

fn is_set_in(&self, env: &impl EnvSource) -> bool

Whether the input is present in env.
Source§

fn raw(&self) -> Option<String>

The raw, unparsed value from the process environment, if set.
Source§

fn raw_in(&self, env: &impl EnvSource) -> Option<String>

The raw, unparsed value from env, if set.

Auto Trait Implementations§

§

impl<T, C> Forget for Input<T, C>

§

impl<T, C> Freeze for Input<T, C>
where Option<T>: Freeze, &'static [C]: Freeze,

§

impl<T, C> Move for Input<T, C>

§

impl<T, C> RefUnwindSafe for Input<T, C>
where Option<T>: RefUnwindSafe, &'static [C]: RefUnwindSafe,

§

impl<T, C> Send for Input<T, C>
where Option<T>: Send, &'static [C]: Send,

§

impl<T, C> Sync for Input<T, C>
where Option<T>: Sync, &'static [C]: Sync,

§

impl<T, C> Unpin for Input<T, C>
where Option<T>: Unpin, &'static [C]: Unpin,

§

impl<T, C> UnsafeUnpin for Input<T, C>
where Option<T>: UnsafeUnpin, &'static [C]: UnsafeUnpin,

§

impl<T, C> UnwindSafe for Input<T, C>
where Option<T>: UnwindSafe, &'static [C]: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.