Expand description
Load config from folders, files and in-code strings/values into one
deep-merged Value. Formats (jsonc, yaml, json, toml, ini, env, csv)
are individually Cargo-feature-gated, the table (csv) format’s cells
carry typed values, and every value can be traced to the source it came
from.
The README is the quick start; this page is the full reference (and
CLAUDE.md in the repo is the exhaustive spec). Most examples below run
without any files — they load in-code string and value sources; only
the load("config") snippets, which read the caller’s filesystem, are
marked no_run.
§Quick start
One generic load takes a path — a folder whose files deep-merge, or
a single file — with default options (formats: jsonc + yaml). The
annotated target type decides what you get: a dynamic Value or your
own serde type.
let value: c4::Value = c4::load("config")?; // a folder …
let one: c4::Value = c4::load("app.yml")?; // … or a single file
let host = value["db"]["host"].as_str().unwrap_or("localhost");For more than one source, or any non-default option, build a Loader
from Options, as the next section shows.
§Sources and options
Everything goes through one plain-data Options; Loader has
exactly new, load and
trace. You never name Source: sources is a
Vec<Source> and each element converts with .into() — a path-like
value (&str/String/&Path/PathBuf) is a folder/file source, a
(format, text) tuple is an in-code string source, and a 1-tuple
(value,) wraps any serde type as a typed override (the trailing comma
is what keeps it distinct — see Source).
use std::path::Path;
use c4::{Format, Loader, Options};
#[derive(serde::Serialize)]
struct Overrides {
debug: bool,
}
let value: c4::Value = Loader::new(Options {
sources: vec![
"./config".into(), // a folder (or a single file)
Path::new("/etc/myapp").into(), // any path-like type
"./local.yml".into(),
("jsonc", r#"{ "note": "from code" }"#).into(), // string source, by format id
(Format::Toml, "debug = true").into(), // string source, by Format
(Overrides { debug: true },).into(), // typed override (1-tuple)
],
// which formats read which extensions; the last claimer wins.
// all four conversion forms — id/Format × default/custom exts:
formats: vec![
"jsonc".into(), // format id, default extensions
Format::Toml.into(), // Format, default extensions
(Format::Yaml, ["yml", "yaml", "conf"]).into(), // Format + custom extensions
("jsonc", ["json", "jsonc"]).into(), // format id + custom extensions
],
recursive: true,
..Options::default()
})
.load()?;Sources merge in the order given — later overrides earlier — whatever their kind:
use c4::{CustomFormat, Loader, Options};
// a tiny `key value type` table format, lowered to `parse_table`
let kv = CustomFormat::new("kv", ["kv"], |text, path, options| {
let rows = text
.lines()
.filter(|l| !l.trim().is_empty())
.map(|l| l.split_whitespace().map(str::to_owned).collect())
.collect();
c4::parse_table(rows, path, options)
});
let value: c4::Value = Loader::new(Options {
sources: vec![
(kv.clone(), "port 1 u16").into(), // earlier …
(kv, "port 8080 u16").into(), // … overridden
(std::collections::BTreeMap::from([("debug", true)]),).into(),
],
..Options::default()
})
.load()?;
assert_eq!(value["port"].as_u64(), Some(8080));
assert_eq!(value["debug"].as_bool(), Some(true));Every Options field is documented on the struct. In brief:
sources, formats, recursive, flat (merge-mode subfolder
nesting), dot_key, case_sensitive, order (an Order or an id
like "alphabetic".into()), and the tree-mode trio tree,
auto_files, ignore_unknown_ext.
§Cargo features
default = ["jsonc", "yaml"]; at least one format feature is
required (a compile error otherwise). Value-parser features are pure
std (no extra dependencies). Cargo unions features across the whole
build graph, so only applications should turn format features on.
| Feature | Enables |
|---|---|
jsonc (default) | JSONC files (comments + trailing commas) |
yaml (default) | YAML files |
json | strict JSON files; also the table json cell |
toml / ini / env / csv | those file formats |
tree | tree mode (Options::tree) |
datetime (= date + time) | the dt table type |
date, time | the date / time table types |
ipv4, ipv6 | the ipv4 / ipv6 table types |
inet (= ipv4 + ipv6 + cidr), cidr | inet / cidr table types |
macaddr (= macaddr8), macaddr8 | MAC table types |
uuid | the uuid table type |
numeric | extended table numeric literals (0x, _, 123n) |
cli | the c4 binary (implies all of the above) |
§Formats
Format and file extension are separate things: each format claims a set
of default extensions, and both sides are configurable. Extension
matching is case-insensitive; a hidden file .X counts as extension
X (so .env matches env). Unclaimed extensions are ignored, and the
last claimer of a contested extension wins — which is also how you
reassign one: vec![Format::Yaml.into(), (Format::Jsonc, ["yml"]).into()]
makes the jsonc parser read .yml. jsonc is a JSON superset that also
claims .json, so with the default formats enabling both json and
jsonc is redundant (jsonc, added last, wins .json).
| Format | Default extensions | Feature |
|---|---|---|
jsonc | .json, .jsonc | default |
yaml | .yml, .yaml | default |
json | .json (strict) | json |
toml | .toml | toml |
ini | .ini | ini |
env | .env, *.env | env |
csv | .csv | csv |
§Merge rules
- Sources merge in the order given; later overrides earlier.
- Within a folder, entries load in
orderand deep-merge: objects merge recursively, arrays and scalars replace. - Override order between files is decided by filename alone, never
by format:
app.jsonandapp.ymlsort by name, soapp.ymlloads later and wins. Prefix filenames (00_a.json,01_a.yml) for explicit control.
§Tree mode
With Options { tree: true, .. } (feature tree) a folder is not
merged — its shape becomes the config: every subfolder is a key, and
every file a key named after it (extension stripped):
config/a/b.json = {"c": 1} -> { "a": { "b": { "c": 1 } },
config/d.json = {"a": 123} "d": { "a": 123 } }Tree mode is always recursive; order decides key collisions (a.yml
next to a folder a/). Extension-less files are auto-detected from
their content when auto_files is set; files with unknown extensions
are skipped unless ignore_unknown_ext is false.
§Table formats
Table rows map to config entries positionally as key,value[,format];
the format column is optional (missing or empty = auto). Type ids
i8–u64, i128/u128, f32/f64, bool, str, auto always
exist; dt/date/time/ipv4/ipv6/inet/cidr/macaddr/
macaddr8/uuid follow their features, and json (a whole JSON
document as one cell) needs json or jsonc. auto tries
bool → date/time/dt → uuid → mac → ip → integer → float → string, and
never widens past i64/u64 (use an explicit i128/u128 cell for
bigger integers). An explicit bool cell also accepts
t/f, yes/no, y/n, on/off, 1/0 (case-insensitive).
The built-in csv format is headerless and positional; a header row,
renamed/reordered columns or a transposed layout are a CustomFormat
that reshapes the file into key,value,format rows and calls
parse_table (see the csv-header and csv-transpose examples):
use c4::{CustomFormat, Loader, Options};
let table = CustomFormat::new("kv", ["kv"], |text, path, options| {
let rows = text
.lines()
.filter(|l| !l.trim().is_empty())
.map(|l| l.split_whitespace().map(str::to_owned).collect())
.collect();
c4::parse_table(rows, path, options)
});
let value: c4::Value = Loader::new(Options {
sources: vec![(table, "name c4 str\nport 8080 u16\ndebug true bool").into()],
..Options::default()
})
.load()?;
assert_eq!(value["name"].as_str(), Some("c4"));
assert_eq!(value["port"].as_u64(), Some(8080));
assert_eq!(value["debug"].as_bool(), Some(true));§Custom formats
A CustomFormat is an id, the extensions it claims, and a parser
callback. It goes into Options.formats like any built-in — one list,
one claim order — and a string source can name one directly. See
CustomFormat for a full markdown-pipe-table example.
§Provenance
Loader::trace returns a TracedValue tree that keeps, per leaf,
the source it came from and the format it parsed as — the shape the CLI
--trace prints and the fixtures assert. See Loader::trace and
TracedValue.
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 viaparse_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.
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.