Expand description
A declared, typed contract for a program’s invocation surface — argv and envp — as data.
A program is handed two things when it starts: an argument vector and an environment. Both are interfaces. Both are depended upon by scripts, images, pipelines, and users. And almost no program declares either one in a form anything can check — the names, the types, the legal values and the defaults live in prose, or in nothing at all.
This crate makes that surface an artifact: declared, typed, checkable, and emittable as a language-neutral JSON document.
This crate is data only — it declares what a program accepts and can
check that declaration and project it to a portable document, but it
does not read argv or envp. For that, see
argenv-resolve, which depends on
this crate and adds nothing else: a program’s contract never needs to
know how it gets resolved, and a resolver never needs to know anything
this crate doesn’t already say.
§The one idea
The declaration is the accessor’s contract. An Input both
describes an input and — via argenv-resolve’s extension trait — reads
it, so the published contract cannot drift from the code that consumes
the value. And because identity (Input::key) is separate from
addressing (Env, Arg), --log-level and APP_LOG_LEVEL are not
two settings — they are one setting with two doors.
use argenv::*;
pub const LOG_LEVEL: Input<LogLevel> = Input {
key: "log_level",
ty: Type::Enum,
default: Some(LogLevel::Info),
allowed: LogLevel::TOKENS, // one source for parser *and* contract
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>");A misspelled key is a compile error. A wrongly typed read is a compile
error — resolving and reading is argenv-resolve’s job, but the
Input<T> you declare here is the same value that crate’s get_from
is typed against, so a mismatch is still caught here, at declaration.
§Reading this crate
Input— the declaration. Start here; it is the surface you author.ArgandEnv— the two bindings. Arity is derived from the type.Version,ReviewDate,Type,Stability,Since,ConfigKeyRef,Deprecation— the vocabulary. Skim once.FromRaw— how a type parses itself, so declarations carry no parser.Record,document— the portable projection and its envelope.contract::json_schema(featurecontract) — the cross-language schema.
§Design rules
- No naked primitive stands for a domain value. Versions and dates parse
and compare; closed sets are enums; constrained numbers are newtypes.
Plain
Stringsurvives only for genuine prose. - Anything a human would forget is derived: arity from the type,
modifiedandgeneratedfrom tooling. The one exception isInput::reviewed, which asserts human judgement nothing can compute. - Partial entries are first-class. A key, a type and one binding are all that is required, so a harvested name is a valid entry and enrichment is a one-line pull request.
- This crate does not resolve anything. No argv, no envp, no
Invocation. That separation is deliberate — seeargenv-resolve.
Modules§
- contract
- JSON Schema emission — the cross-language contract.
Structs§
- Arg
- The argument-vector binding: the flag a value may arrive under.
- ArgBinding
- How a value may arrive from the argument vector.
- Config
KeyRef - A reference to a key in another configuration surface that this variable
bridges to (for example a
.confkey the variable overrides). - Deprecation
- Why a variable is going away and what to do instead.
- Env
- The environment binding: the variable name a value may arrive under.
- EnvBinding
- How a value may arrive from the environment.
- Input
- One input a program accepts — its identity, its domain, and the doors it can arrive through.
- Record
- One input, flattened to plain JSON-friendly types.
- Review
Date - A human review date (
YYYY-MM-DD). - Version
- A project version (
major[.minor[.patch]]).
Enums§
- LogLevel
- A conventional log-verbosity domain, provided because nearly every program exposes one. Projects with different level names should declare their own enum the same way.
- NoCommand
- The default for
Input’s second type parameter — an input with nosubcommandsscoping never needs to name a real subcommand enum. Zero variants: nothing can ever construct one, which is the type-level way of saying “this input is not scoped to anything.” - Since
- When a variable was introduced — never a bare string.
- Stability
- How much a consumer may rely on a variable.
- Tristate
- A three-state toggle. A
boolwould be a lie when “unset” is a real, distinct choice — this makes the third state explicit instead of smuggling it in asOption<bool>. - Type
- The coarse wire kind a variable exposes in the contract.
Constants§
- CONTRACT_
VERSION - Bump on any breaking change to
Record. Additive changes (a new optional field) keep the major version and stay backward-compatible. - PRECEDENCE
- The order in which bindings win when more than one supplies a value.
- THIS_
VERSION - The version of the crate currently building. Reference it via
crate::Since::Thisfor a variable added now, instead of hardcoding a number that would silently drift.
Traits§
- FromRaw
- Parse a value from the raw string an invocation carried.
Functions§
- check_
unique - Problems that only exist across a whole model: two inputs claiming the same identity, the same environment name, or the same flag.
- document
- Wrap a project’s records in the standard envelope.