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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
//! Config sources: a filesystem path (folder or single file), an in-code
//! string (built-in or custom format), or an in-code serde value.
//!
//! You rarely name [`Source`] directly. Build the `sources` list as a
//! plain `Vec<Source>` and convert each element with `.into()` (the `From`
//! impls below): a path-like value is a folder/file source, a
//! `(format, text)` tuple is a string source, and a 1-tuple `(value,)` is
//! a typed serde override.
use ;
use crate;
use crate::;
/// One config source. Sources merge in order — later overrides earlier.
///
/// Construct sources by conversion, not by hand:
/// - a path-like value (`&str`, `String`, `&Path`, `PathBuf`) becomes
/// [`Source::Path`] — loaded as a folder or a single file, detected at
/// load time;
/// - a `(format, text)` tuple becomes [`Source::String`] — the format is a
/// [`Format`](crate::Format), a format-id string (`"jsonc"`), or a
/// [`CustomFormat`](crate::CustomFormat);
/// - a **1-tuple** `(value,)` wraps any `Serialize` type as a typed
/// override — the single-element tuple keeps it distinct from the
/// conversions above (a blanket `From<impl Serialize>` would overlap
/// them, since `&str`/`String`/tuples are all `Serialize`);
/// - a 3-tuple `(format, path, layout)` or 4-tuple
/// `(format, path, sheet, layout)` becomes [`Source::Table`] — one
/// **file** of a table format (csv, excel, ods) read with the given
/// [`TableLayout`]. The 3-tuple's third element is always the layout
/// (it suits csv — the file is the table); naming a spreadsheet sheet
/// is always the 4-tuple.
///
/// So one `Options.sources` `vec![…]` can mix all of these kinds.
/// A `(format, text)` tuple is an in-code string source. `format` is a
/// [`Format`](crate::Format), a format-id `&str`, or a
/// [`CustomFormat`](crate::CustomFormat); `text` is anything `Into<String>`.
/// A **1-tuple** `(value,)` is a typed serde override — the value is
/// serialized through the crate serializer (no format parser; works with
/// any `#[derive(Serialize)]` type). A serialization failure (e.g. a map
/// with non-string keys) surfaces at load time as
/// [`Error::Parse`](crate::Error::Parse); a `Null` root (e.g. `None`)
/// contributes nothing.
///
/// A struct field or map entry whose value is **`None` is left out**, so
/// it overrides nothing: an `Option` field you did not set (a CLI flag
/// that was not given) keeps the earlier sources' value. An explicit null
/// — `()`, `serde_json::Value::Null`, [`Value::Null`] — still overrides.
/// `None` inside a sequence stays a positional null.
///
/// The single-element tuple is what keeps this distinct: `&str`, `String`,
/// tuples and paths are all themselves `Serialize`, so a blanket
/// `From<impl Serialize>` would overlap the conversions above — but a
/// 1-tuple `(T,)` is a type of its own. Mind the trailing comma:
///
/// ```
/// #[derive(serde::Serialize)]
/// struct Overrides {
/// debug: bool,
/// }
///
/// # fn main() -> Result<(), c4::Error> {
/// let value: c4::Value = c4::Loader::new(c4::Options {
/// sources: vec![(Overrides { debug: true },).into()],
/// ..c4::Options::default()
/// })
/// .load()?;
/// assert_eq!(value["debug"].as_bool(), Some(true));
/// # Ok(())
/// # }
/// ```
/// A `(format, path, layout)` 3-tuple is a table source: one file, read
/// with that [`TableLayout`] (a `TableLayout`, a
/// [`CustomLayout`](crate::CustomLayout), or a layout-id `&str` —
/// `"kv"`/`"kvf"`, `"db"`; an unknown id **panics**, this is config-time
/// code). The third element is **always the layout** — the 3-tuple suits
/// csv, where the file is the table. To name a spreadsheet sheet use the
/// 4-tuple, which names the layout explicitly too.
/// Like the `(Format, path, layout)` tuple, with the format named by its
/// id string. Panics on an unknown format id — this is config-time code.
/// A `(format, path, sheet, layout)` 4-tuple is a table source that reads
/// exactly one sheet of a workbook (skipping the sheet-ignore filters)
/// and merges it under the sheet name as key.
/// Like the `(Format, path, sheet, layout)` tuple, with the format named
/// by its id string. Panics on an unknown format id — this is config-time
/// code.