Expand description
Resolve an argenv contract against a real invocation — argv and
envp — with precedence, defaults, and linting.
argenv declares what a program accepts, as data, and does not read
argv or envp at all. This crate is the other half: it depends on
argenv for Input/Record and adds exactly the runtime concern
argenv deliberately leaves out. A program’s contract never needs to
know how it gets resolved; this crate never needs to know anything
argenv doesn’t already say.
Re-exports everything from argenv, so use argenv_resolve::*; is the
only import most consumers ever need.
§The common case
use argenv_resolve::*;
contract! {
LOG_LEVEL: 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
};
}
// In main(): let resolved = Contract::parse_and_lint(OnProblems::FailOnError);
let args = vec!["--log-level".to_string(), "warn".to_string()];
let env = std::collections::BTreeMap::new();
let resolved = Invocation { args: &args, env: &env }.resolve(&Contract::records());
assert_eq!(Contract::LOG_LEVEL.get_from(&resolved), Some(LogLevel::Warn));
assert_eq!(resolved.source("log_level"), Some(Source::Arg));§Reading this crate
contract!— declare a contract and getrecords(),problems(), andparse_and_lint()generated for you. Start here.parse()— the one-liner: read process argv+env, resolve, done.Invocation,Resolution,Source— resolving argv and envp directly, with provenance for every value. Use this in tests, to inject specific args/env rather than mutating global process state.lint()— what an invocation gets wrong.OnProblems,handle_problems()— named policies for what to do about it, instead of a hand-rolled loop per project.InputResolveExt— the trait givingInputitsget/get_from/ etc. methods. Implemented for everyInput<T, C>; you will not usually name this trait directly, justuse argenv_resolve::*;.
Modules§
- generate
- Everything a program ships about its invocation, derived from the declaration.
Macros§
- contract
- Declare a program’s invocation surface as a typed 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.
- Invocation
- What a program was invoked with: an argument vector and an environment.
- Lint
Policy - How serious each kind of finding is for one program.
- Process
Env - The current process’s environment.
- Record
- One input, flattened to plain JSON-friendly types.
- Resolution
- Everything an invocation resolved to, with provenance and any problems found.
- Resolved
- One resolved value and its provenance.
- Review
Date - A human review date (
YYYY-MM-DD). - Version
- A project version (
major[.minor[.patch]]).
Enums§
- Finding
- Something wrong with an invocation, relative to the declared contract.
- 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.” - OnProblems
- What to do when
crate::lintreturns findings. - Severity
- How seriously to take a
Finding. - Since
- When a variable was introduced — never a bare string.
- Source
- Which door a resolved value arrived through.
- 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§
- EnvSource
- A set of environment variables that can be read and enumerated.
- FromRaw
- Parse a value from the raw string an invocation carried.
- Input
Resolve Default Ext get_from_or_default— a separate trait because it needsT: Clone, which not everyInputvalue type provides, the same splitargenv::Input’s own impl blocks already made before this trait existed.- Input
Resolve Ext - Runtime-reading methods for
Input, added by this crate.
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.
- handle_
problems - Apply a problem-handling policy to a set of findings.
- handle_
problems_ with handle_problems, with this program’s own idea of how serious each finding is.- lint
- Check a resolved invocation against the declared contract.
- parse
- Parse the current process’s argument vector and environment against a
declared model, returning a fully resolved
Resolution.