pub struct Loader {
pub options: Options,
}Expand description
Loads and merges the config sources named by its Options.
Fields§
§options: OptionsImplementations§
Source§impl Loader
impl Loader
Sourcepub fn new(options: Options) -> Self
pub fn new(options: Options) -> Self
Everything — sources included — comes in through Options;
there is no separate builder step.
Sourcepub fn load<T: DeserializeOwned>(&self) -> Result<T>
pub fn load<T: DeserializeOwned>(&self) -> Result<T>
Load and merge all sources, deserializing into T.
Value implements Deserialize, so T = Value gives dynamic
access and any other serde type gives typed config. A Value —
the whole result, or a field of your struct — is handed over as
merged, typed variants (DateTime, Ipv4, …) included, exactly as
Loader::trace shows them.
A string reaching a bool, integer or float field parses with
the rules of that table type id (u16, bool, … — see the crate
docs’ table section), so ini, env and cnf values, which are all
strings, load into typed fields. The explicit bool tokens apply
(yes/no, on/off, 1/0, …), and out-of-range or malformed
text is Error::Deserialize ('70000' is not a valid u16). Untyped
targets (Value, String) keep the string.
The reverse holds too: a number or bool reaching a String field
becomes its text (password: 123456 → "123456"; a float in its
shortest round-trip form, so 1.0 stays "1.0").
Every Error::Deserialize names the key path it failed at —
db.password: invalid type: …, items[2].id: …. An empty value
(PORT=) cannot fill a number or bool field, not even an Option
one (serde picks None or Some before it sees the inner type);
the error says to remove the line instead.
To type one part of a loaded Value, use Value::into_typed.
#[derive(serde::Deserialize)]
struct Server {
port: u16,
debug: bool,
}
// the 1-tuple value source stands in for an ini/env/cnf file here
let server: Server = c4::Loader::new(c4::Options {
sources: vec![(serde_json::json!({ "port": "8080", "debug": "yes" }),).into()],
..c4::Options::default()
})
.load()?;
assert_eq!(server.port, 8080);
assert!(server.debug);Warnings are dropped — call Loader::trace to see why some
input was not used (a skipped cnf !include, for instance).
Sourcepub fn trace(&self) -> Result<Trace>
pub fn trace(&self) -> Result<Trace>
Like Loader::load, but keeps per-leaf provenance and the
Warnings — see Trace. This powers the CLI --trace mode;
source labels are a debug/testing aid, not config data.
use c4::{CustomFormat, Loader, TracedValue};
// a custom-format string source keeps this example runnable
// under every feature combination (`Loader::default()` would
// read ./config instead)
let kv = CustomFormat::new("kv", ["kv"], |text, path, options| {
let rows = text
.lines()
.map(|line| line.split('=').map(str::to_owned).collect())
.collect();
c4::parse_table(rows, &c4::TableLayout::Kv, path, options)
});
let trace = Loader::new(c4::Options {
sources: vec![(kv, "port=8080").into()],
..c4::Options::default()
})
.trace()?;
assert!(trace.warnings.is_empty());
let TracedValue::Object(root) = &trace.value else { unreachable!() };
let TracedValue::Leaf { value, source } = &root["port"] else { unreachable!() };
assert_eq!(value.as_u64(), Some(8080));
assert_eq!(source, &c4::SourceRef::String(0)); // "string:0" in traces