Expand description
Load a folder of config files into one deep-merged Value.
README.md is the user-facing overview and CLAUDE.md the complete
spec; the README examples are mirrored here as doc tests. Examples
that read the caller’s working directory (./config, /etc/myapp)
are no_run — they compile but depend on the user’s filesystem; the
CustomFormat example is fully runnable via a string source.
Simplest form — one generic load taking the path of a folder (or
a single file), default options (formats: jsonc + yaml). The
annotated target type decides whether you get a dynamic Value or
your own struct:
let value: c4::Value = c4::load("config")?;Advanced — explicit sources (later overrides earlier) and options:
use std::path::Path;
use c4::{Format, Loader, Options, Source};
let value: c4::Value = Loader::new(Options {
sources: vec![
Source::folder("./config"),
Source::folder(Path::new("/etc/myapp")), // any path-like type
Source::file("./local.yml"),
Source::string(Format::Jsonc, r#"{ "debug": true }"#),
],
recursive: true,
formats: vec![
"jsonc".into(), // format id, default extensions
Format::Toml.into(), // enum form, default extensions
(Format::Yaml, ["yml", "yaml", "conf"]).into(), // custom extensions
("jsonc", ["json", "jsonc"]).into(), // string id + custom extensions
],
..Options::default()
})
.load()?;Structs§
- Custom
Format - A user-defined format: an id, the extensions it claims, and a parser
callback. It goes into
Options::formatslike any built-in format (formats: [..the defaults, md.into()]), so the usual rule applies — the last claimer of an extension owns it, and a custom format can take over a built-in extension. Table-shaped custom formats can lower their file into rows and reuse the generic table stage via [parse_table]. - Format
Spec - A format plus the extensions it reads — one entry of
Options::formats. - Loader
- Loads and merges the config sources named by its
Options. - Options
- All loader options.
- Table
Columns - Names of the key / value / format columns of a table source.
- Table
Options - Options for table-shaped formats (csv today; spreadsheet formats later).
- Table
Types - Which
typecolumn values a table (csv) source accepts.
Enums§
- Error
- Errors produced while scanning, parsing, merging or deserializing.
- Format
- A config file format.
- Format
Kind - What a
FormatSpecentry parses with: a built-in format or a user-definedCustomFormat. - Order
- File load order inside a folder.
- Source
- One config source. Sources merge in order — later overrides earlier.
- Source
Ref - Where a traced value came from.
- Traced
Value - The result of [
Loader::trace]: the merged tree with per-leaf provenance. Objects recurse; every non-object value (including whole arrays) is aTracedValue::Leaf. - Value
- Dynamic config value.
Functions§
- load
- Load one path with default options — the shortest way in. An
existing file loads as a single file source; anything else is
treated as a folder (a missing path is
Error::NotFound). The annotated target type decides what you get back: - parse_
table - The generic table stage: interpret a plain row table
(
[[key, value, format], …]) with theoptions.tablesemantics — the same stage the csv format feeds. Public so custom table-shaped formats (spreadsheets, markdown tables, …) can lower their file into rows and reuse it;pathlabels errors.