1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
//! 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`](https://docs.rs/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.
//! * [`Arg`] and [`Env`] — 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` (feature `contract`) — 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 `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`.
pub use ;
pub use ReviewDate;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;