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
99
//! A declared, typed contract for a program's **invocation surface** — argv and
//! envp.
//!
//! 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.
//!
//! # The one idea
//!
//! **The declaration is the accessor.** An [`Input`] both describes an input and
//! 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
//! };
//!
//! let model = vec![LOG_LEVEL.to_record()];
//! let args = vec!["--log-level".to_string(), "warn".to_string()];
//! let env = std::collections::BTreeMap::new();
//! let resolved = Invocation { args: &args, env: &env }.resolve(&model);
//!
//! assert_eq!(LOG_LEVEL.get_from(&resolved), Some(LogLevel::Warn));
//! assert_eq!(resolved.source("log_level"), Some(Source::Arg));
//! ```
//!
//! A misspelled key is a compile error. A wrongly typed read is a compile error.
//! A misspelled *flag or variable* is a [`Finding`] instead of silence.
//!
//! # 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.
//! * [`Invocation`], [`Resolution`], [`Source`] — resolving argv and envp, with
//! provenance for every value.
//! * [`lint()`] — what an invocation gets wrong.
//! * [`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.
pub use ;
pub use ReviewDate;
pub use ;
pub use Input;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;