Skip to main content

Crate argenv

Crate argenv 

Source
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

§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 String survives only for genuine prose.
  • Anything a human would forget is derived: arity from the type, modified and generated from tooling. The one exception is Input::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 — see argenv-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.
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.
Record
One input, flattened to plain JSON-friendly types.
ReviewDate
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 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.”
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 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§

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.