Skip to main content

Crate argenv_resolve

Crate argenv_resolve 

Source
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 get records(), problems(), and parse_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 giving Input its get/get_from/ etc. methods. Implemented for every Input<T, C>; you will not usually name this trait directly, just use argenv_resolve::*;.

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.
ConfigKeyRef
A reference to a key in another configuration surface that this variable bridges to (for example a .conf key 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.
LintPolicy
How serious each kind of finding is for one program.
ProcessEnv
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.
ReviewDate
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 no subcommands scoping 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::lint returns 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 bool would be a lie when “unset” is a real, distinct choice — this makes the third state explicit instead of smuggling it in as Option<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::This for 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.
InputResolveDefaultExt
get_from_or_default — a separate trait because it needs T: Clone, which not every Input value type provides, the same split argenv::Input’s own impl blocks already made before this trait existed.
InputResolveExt
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.