cfgmatic-source

Layered configuration loading for cfgmatic.

cfgmatic-source is the canonical v5 entrypoint for collecting configuration layers before merge explanation and typed deserialization.

Installation

[dependencies]
cfgmatic-source = { version = "5", features = ["env", "schema"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"

Primary types

• Loader: load one source or a slice of sources.
• SourceCoordinator: register heterogeneous sources with explicit priorities.
• SourceLayer: one parsed layer before merge.
• LoadReport: canonical result containing layers, merged content, merge report, load stats, and timings.
• CascadeLoader: Git-like system -> global -> local -> worktree layering.

Canonical multi-source flow

use cfgmatic_source::prelude::*;

let defaults = MemorySource::from_json(serde_json::json!({
    "server": { "port": 8080 }
}));
let local = MemorySource::from_json(serde_json::json!({
    "server": { "port": 9090 }
}));

let mut coordinator = SourceCoordinator::builder()
    .add_source(defaults, 1)
    .add_source(local, 10)
    .build();

let report = coordinator.load_report()?;
let explanation = report.merge_report.explain_path("/server/port").unwrap();

assert_eq!(report.layers.len(), 2);
assert_eq!(explanation.winner.unwrap().source, "memory");
# Ok::<(), cfgmatic_source::SourceError>(())

Precedence contract

• higher priority sources override lower priority sources;
• equal priorities resolve by later registration order;
• collect_layers() returns merge application order;
• path explanations use JSON Pointer.

Cascading configuration

use cfgmatic_source::prelude::*;

let loader = CascadeLoader::builder()
    .add_optional_file(CascadeScope::System, "/etc/myapp/config.toml")
    .add_optional_file(CascadeScope::Global, "/home/alice/.config/myapp/config.toml")
    .add_optional_file(CascadeScope::Local, ".myapp/config.toml")
    .add_optional_file(CascadeScope::Worktree, ".myapp/config.worktree.toml")
    .default_format(Format::Toml)
    .build();

let result = loader.load()?;
assert_eq!(result.loaded_layers.len(), 0);
# Ok::<(), cfgmatic_source::SourceError>(())

This models .gitconfig-style precedence for TOML/JSON/YAML sources. It does not implement Git's INI syntax or includeIf.

Feature flags