Expand description
Load config from folders, files and in-code strings/values into one
deep-merged Value. File formats (jsonc, yaml, json, toml, ini, env,
csv, excel, ods) are individually Cargo-feature-gated, the table
formats’ cells (csv and spreadsheet sheets) carry typed values, and
every value can be traced to the source it came from.
This page is the usage reference; the README has the quick start
and the “why c4” positioning. 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 (default format: jsonc). 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.json")?; // … 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: every sources
element converts with .into(), and its shape picks the source kind
— the comments below show every form, Source has the details:
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![
// Path-like values are folders or files
"./config".into(), // a folder
"./local.yml".into(), // or a single file
Path::new("/etc/myapp").into(), // any path-like type
(Overrides { debug: true },).into(), // (1-tuple) typed override
("jsonc", r#"{ "note": "from code" }"#).into(), // (2-tuple) format id with string source
(Format::Toml, "debug = true").into(), // (2-tuple) Format with string source
("csv", "./items.csv", "db").into(), // (3-tuple) table source: format + file + layout
(Format::Excel, "./game.xlsx", "drops", "db").into(), // (4-tuple) multiple tables: Format + file + sheet + layout
],
// which formats read which extensions; the last claimer wins.
// all conversion forms — id/Format × default/custom exts,
// optionally + a table layout for every file the entry claims:
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
(Format::Csv, ["csv"], "db").into(), // + layout: all csv = record grids
],
recursive: true,
..Options::default()
})
.load()?;Every field is documented on Options, each stating up front the
mode/format it applies to.
§Merge order and custom formats
The merge rules, whatever the source kind:
- 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.
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.
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, &c4::TableLayout::Kv, 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));§Cargo features
default = ["jsonc"] — deliberately light, one parser dependency; 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); also the jsonc table cell |
yaml | YAML files |
json | strict JSON files; also the table json cell |
toml / ini / env / csv | those file formats |
excel | Excel workbooks (.xlsx/.xlsm/.xlsb/.xls) |
ods | OpenDocument spreadsheets (.ods) |
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) |
§File 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 | yaml |
json | .json (strict) | json |
toml | .toml | toml |
ini | .ini | ini |
env | .env, *.env | env |
csv | .csv | csv |
excel | .xlsx, .xlsm, .xlsb, .xls | excel |
ods | .ods | ods |
§Tree mode
With 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 } }let value: c4::Value = c4::Loader::new(c4::Options {
sources: vec!["./config".into()],
tree: true,
..c4::Options::default()
})
.load()?;
assert_eq!(value["a"]["b"]["c"].as_i64(), Some(1));The full rules — recursion, key collisions, extension handling — are
on Options::tree (with Options::auto_files and
Options::ignore_unknown_ext for the edge cases).
§Table formats
Table files (csv, and each spreadsheet sheet) parse under a
TableLayout. Each format has a default —
Format::default_layout: kv for csv, db for excel/ods
(spreadsheets are grids) — overridable per source with a table-source
tuple or per extension in formats:
kv(csv default):key,value[,format]rows, one config entry per row.db(spreadsheet default): a record grid — row 1 holds the keys, row 2 always the type ids (empty cell =auto), every following row is one record; the file parses to an array of objects, so a config sheet full of game items deserializes straight into aVec<Item>. Empty cells are omitted from their record. The type row is positional — the row right after the keys is the type row even when it is entirely blank (= every columnauto); it is never skipped as a blank row.- a
CustomLayout: your callback over the raw rows — reshape them and callparse_table. A db grid without a type row is the canonical case: insert a row ofautocells after the header and delegate todb(see thexlsx-sheetsexample).
The layout comes from a table-source tuple or a formats entry (the
forms are in the sources example above; details on Source). The
db layout on a plain csv file loads a record grid straight into a
Vec<T> (the csv-db example):
use c4::{Format, Loader, Options};
#[derive(serde::Deserialize)]
struct Item {
id: u32,
name: String,
price: f64,
}
// items.csv: key row
// id,name,price
// u32,str,f64 type row (a cell may be empty = auto)
// 1,sword,10.5 one record per row
// 2,shield,7
let items: Vec<Item> = Loader::new(Options {
sources: vec![(Format::Csv, "items.csv", "db").into()],
..Options::default()
})
.load()?;Two db sources do not concatenate: arrays replace like any array.
Rows map keys to values positionally (in kv: col 0 = key,
col 1 = value, col 2 = format; in db: the type row types its
column). With Options::dot_key (default on) a dotted key nests in
both layouts — a kv row a.b,1 gives {a:{b:1}}, and a db
stats.atk column nests inside each record — and a name[] /
name[<int>] segment builds an array (append / index, suffixes
chain for nested arrays; see Options::dot_key and the dot-key
example). The format of a
cell is one of the ids below — the column/row is optional, and a
missing or empty format means auto:
| Cell format | Aliases | Cargo feature | Notes |
|---|---|---|---|
auto (or empty) | — | — | guesses bool → date/time/dt → uuid → mac → ip → integer → float → string, using only compiled-in types; never widens past i64/u64; leading-zero numbers stay strings |
i8 i16 i32 i64 | int, integer = i64 | — | signed integers |
u8 u16 u32 u64 | uint = u64 | — | unsigned integers |
i128 u128 | — | — | explicit-only — auto never guesses them |
f32 f64 | float, double, number = f64 | — | floats (f32 rounds through f32 precision) |
bool | boolean | — | also accepts t/f, yes/no, y/n, on/off, 1/0 (case-insensitive); auto only accepts true/false |
str | string, text | — | the cell text as-is |
dt | datetime | datetime | YYYY-MM-DD, optional time part |
date, time | — | same-named | YYYY-MM-DD / hh:mm:ss[.frac] |
ipv4, ipv6 | — | same-named | IP addresses |
inet, cidr | — | same-named | PostgreSQL inet/cidr shapes (optional/required netmask) |
macaddr, macaddr8 | — | same-named | the PostgreSQL MAC spellings |
uuid | — | same-named | hyphenated or bare 32-hex |
json, jsonc | — | same-named | a whole document in one cell, parsed by exactly that format’s parser |
array<sep><format> | — | — | splits the cell into a flat list by sep (default ,), each element parsed by format (default auto): array| on 1|2|3 → [1,2,3], array|u8 types them u8, array|str keeps ["1","2","3"] |
csv<sep><layout> | — | csv | parses the whole cell as a CSV document (delimiter sep, default ,) under layout (default kv): csv,kv → object, csv,db → array of objects |
array and csv are explicit-only (like json/jsonc) — auto
never produces a list. array is always compiled (a native split);
csv needs the csv feature. Both take an optional, positional
suffix after the separator: array<sep><format> applies one type id
to every element, and csv<sep><layout> picks the inner layout — in
each case naming the suffix means writing the separator too
(array,i8, csv,db), and the separator is a single character
(ASCII for csv). array<sep><format> types every element the
same; when a list’s elements need different formats, use a csv
cell instead (one key,value,format row each: a,1,i8 / b,2,i16).
Only the built-in layout ids kv/db are nameable in csv.
An id whose feature is off is an unknown format and fails the row;
only auto degrades (it just stops guessing). The numeric feature
extends every numeric cell with 0x/0o/0b radixes, _
separators and BigInt-style 123n.
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, &c4::TableLayout::Kv, 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));§Spreadsheet formats
excel (.xlsx/.xlsm/.xlsb/.xls) and ods (.ods) read
workbooks as table formats: each sheet is a grid anchored at cell A1,
lowered to rows for the table stage — db record grids by default
(Format::default_layout). Numbers, booleans and date-formatted
cells convert to the text the stage expects (a dt/date/time
column works on real spreadsheet dates), and error messages carry
real spreadsheet row numbers. Both are binary formats, so they load
from files only — a (Format::Excel, text) string source is an
error.
Which sheets are read:
tree: false(default): exactly the sheet namedconfig; a workbook without one contributes nothing.tree: true: every sheet becomes a key under the file’s key — seeOptions::tree.- Prefixed (
#/./_) and hidden sheets are skipped — seeOptions::ignore_sheet_prefixandOptions::ignore_hidden_sheets. - A table source that names a sheet (always the 4-tuple) reads
exactly that sheet and merges it under the sheet name as key — see
Source:
use c4::{Format, Loader, Options};
// game.xlsx: sheet "items" is a record grid, "settings" is kv rows
let value: c4::Value = Loader::new(Options {
sources: vec![
(Format::Excel, "game.xlsx", "items", "db").into(),
(Format::Excel, "game.xlsx", "settings", "kv").into(),
],
..Options::default()
})
.load()?;
assert!(value["items"][0]["id"].as_u64().is_some());
assert!(!value["settings"].is_null());The xlsx-sheets example composes five sheets of one workbook this
way, CustomLayouts included.
§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. - Custom
Layout - A user-defined table layout: an id and a callback that receives the
lowered rows (
Vec<Vec<String>>— csv records, or a sheet’s cells as text) and returns anyValue. This is the rows-level escape hatch: binary formats (spreadsheets) can’t go through aCustomFormat(which parses text), but one sheet of a workbook can still get fully custom treatment via(Format::Excel, path, sheet, CustomLayout::new(…)).into(). Most custom layouts end by reshaping the rows and callingparse_table(thexlsx-sheetsexample transposes a column-oriented sheet this way). - 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.
- Table
Layout - How the table stage interprets a row grid. Chosen per table source
(
(format, path, layout)/(format, path, sheet, layout)tuples), performatsentry ((format, [exts], layout)), or passed explicitly toparse_table; everything else uses the format’s default —Format::default_layout:kvfor csv,dbfor excel/ods. Converts from a layout id string ("kv"/"kvf","db") or aCustomLayout. - 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 under an
explicit
TableLayout—&TableLayout::Kvforkey,value[,format]rows (what the csv format feeds by default),&TableLayout::Dbfor a record grid, or aCustomLayoutcallback. Public so custom table-shaped formats (markdown tables, …) and custom layouts can lower their input into rows and reuse it;pathlabels errors. The layout is always passed — there is deliberately no defaulting variant.