Expand description
Load config from folders, files and in-code strings/values into one
deep-merged Value. File formats (jsonc, yaml, json, toml, ini, cnf,
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
],
dir_depth: -1, // scan every subdirectory level
..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. - An empty result — an empty file or string, a workbook with no
sheets left, a
(value,)override that serializes to null — contributes nothing: it never clears what earlier sources set. The one exception is strictjson, where an empty document is a parse error (the message suggests lettingjsoncread.json, which treats it as empty).
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 / cnf / env / csv | those file formats |
excel | Excel workbooks (.xlsx/.xlsm/.xlsb/.xls) |
ods | OpenDocument spreadsheets (.ods) |
tree | default-preset: flips filename_as_key, dirname_as_key, sheetname_as_key on and dir_depth to -1 in Options::default (the fields work without it) |
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 1.1) | .toml | toml |
ini | .ini | ini |
cnf | .cnf | cnf |
env | .env, *.env | env |
csv | .csv | csv |
excel | .xlsx, .xlsm, .xlsb, .xls | excel |
ods | .ods | ods |
A leading UTF-8 byte-order mark (Windows editors, Excel exports) is ignored by every text format, custom formats included.
yaml resolves anchors, aliases and << merge keys.
env follows the dotenv conventions: export is optional, a quoted
value ends at its closing quote, and in an unquoted value # starts a
comment only after whitespace (A=1 # note is 1, C=#fff stays
#fff). Inside double quotes \n, \r, \t, \" and \\
are escapes (any other \X stays as written); single quotes are
literal. ini, env and cnf values are strings; they still load into
typed fields — see Loader::load.
§Folder shape: keys and depth
By default a folder’s files deep-merge into one flat value, scanning
the folder plus one subdirectory level (dir_depth:
-1 for unlimited, 0 for the folder only). Turning subfolders and
files into keys makes the folder’s shape the config instead:
dirname_as_key— each subfolder becomes a key.filename_as_key— each file becomes a key named after it (extension stripped).sheetname_as_key— each spreadsheet sheet becomes a key.
These fields work on any build; the tree feature is just a
convenience that flips all three on (and dir_depth to -1) in
Options::default, so an app that wants tree-shaped loading enables
the feature and keeps using the defaults.
config/a/b.json = {"c": 1} -> { "a": { "b": { "c": 1 } },
config/d.json = {"a": 123} "d": { "a": 123 } }// explicit keying — or, with the `tree` feature, just Options::default()
let value: c4::Value = c4::Loader::new(c4::Options {
sources: vec!["./config".into()],
filename_as_key: true,
dirname_as_key: true,
dir_depth: -1,
..c4::Options::default()
})
.load()?;
assert_eq!(value["a"]["b"]["c"].as_i64(), Some(1));Key collisions deep-merge (so order decides the
winner); extension handling for keyed files is on
auto_no_ext_files and
ignore_unknown_ext.
§Commented-out names and keys
A name or key starting with # or _ reads as commented out, so
draft files, work-in-progress folders, scratch sheets and one-off keys
can sit next to live config without loading (. is not a prefix —
.env is an ordinary file):
config/app.json = {"port": 8080, "_note": "wip"} -> { "port": 8080 }
config/_old.json = {"port": 1} (skipped)
config/_wip/* (skipped)Four options, all default true, split by what they filter — the
data a source parses to, or the names c4 scans:
ignore_commented_data_keys,
ignore_commented_filenames,
ignore_commented_dirnames and
ignore_commented_sheetnames.
The three name options filter scanning only — a file, folder or
sheet you name yourself always loads (naming a commented folder scans
it, though commented names inside it are still skipped) — and they,
not the data-key option, govern the keys made from names
(filename_as_key and friends).
use std::collections::BTreeMap;
let value: c4::Value = c4::Loader::new(c4::Options {
sources: vec![(BTreeMap::from([("port", 8080), ("_note", 1)]),).into()],
..c4::Options::default()
})
.load()?;
assert_eq!(value["port"].as_i64(), Some(8080));
assert!(value["_note"].is_null());§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 — each sheet is treated like a file:
sheetname_as_key: false(default): every non-ignored sheet parses and they all deep-merge into one value, inorderby sheet name (later overrides earlier). A workbook with no sheets left contributes nothing.sheetname_as_key: true: every sheet becomes a key instead (through the samedot_keyexpansion as any key, so a sheet nameda.bnests) — seeOptions::sheetname_as_key.- Commented (
#/_) and hidden sheets are skipped — seeOptions::ignore_commented_sheetnamesandOptions::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 Trace: the merged TracedValue tree
that keeps, per leaf, the source it came from and the format it parsed
as, plus the Warnings for input c4 accepted but did not act on —
the shape the CLI --trace prints. The library
never prints warnings, and load drops them.
§cnf files
.ini is read strictly — the subset the de facto ini dialects share:
[section] one level deep, key=value, ;/# comment lines, no
quoting or escapes. .cnf has no spec and several dialects, so the cnf parser is lenient enough to read my.cnf
(MySQL/MariaDB), openssl.cnf and the like as they are; where the
dialects disagree it follows MySQL. [ section ] headers; #
comments anywhere outside quotes, ; and % comments at line start
only; quotes stripped only when they wrap the whole value; MySQL
escapes (\s, \n, …, any other \X kept as written); bare keys
(skip-networking) as true; no line continuation. Everything else
is a string, and keys stay literal. Variables ($dir, $ENV::HOME)
are not expanded, and include directives (!include, .include) are
skipped,
each with a Warning in the trace:
let trace = c4::Loader::new(c4::Options {
sources: vec![("cnf", "!includedir /etc/mysql/conf.d/\n[mysqld]\nport = 3306\nskip-networking\n").into()],
..c4::Options::default()
})
.trace()?;
let value: c4::Value = trace.value.into();
assert_eq!(value["mysqld"]["port"].as_str(), Some("3306"));
assert_eq!(value["mysqld"]["skip-networking"].as_bool(), Some(true));
assert_eq!(trace.warnings.len(), 1);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.
- Trace
- The result of
Loader::trace: the merged tree plus the warnings collected while loading it. - Warning
- Input c4 accepted but did not act on. Only a
Tracecarries warnings: the library never prints them, andload()drops them.
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 merged tree of a
Trace, 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.