c4-config 0.3.3

Load a folder of config files (jsonc/yaml/json/toml/ini/env/csv/xlsx/ods) into one deep-merged value
Documentation

c4

Documentation build status Downloads

Load config from folders, files and in-code strings/values into one deep-merged value. File formats are individually selectable via Cargo features (default: just JSONC), with table formats (CSV and Excel/OpenDocument spreadsheets) whose cells carry typed values, per-value provenance tracing, and a CLI.

cargo add c4-config    # the package is c4-config; in code it is `c4`

Why c4

Honestly: in the AI era you may not need a config library at all. If your app reads one simple settings file, ask your AI assistant to write bespoke loading code instead — zero dependencies is lighter than any library, including this one. Don't add c4 for that.

What still deserves a library is a convention. node-config's real contribution was never convenience — it was a rule set a whole team could point at: multiple files, deterministic override order, deep merge. c4 exists to be that rule set for Rust:

  • Deterministic merging you don't re-invent per project — later sources override earlier, filenames decide order inside a folder, objects merge deep, arrays and scalars replace. One sentence, always true.
  • Table conventions non-programmers can own — key,value[,format] rows for settings (the CSV default), or a db record grid (keys / types / rows → an array of typed objects; the spreadsheet default) for data tables, the same whether they live in a CSV file or an Excel/OpenDocument sheet. Planners — game designers especially — edit config in the spreadsheet tools they already use, with typed cells (integers, bools, dates, IPs, UUIDs, …) instead of stringly data, and no programmer in the loop.
  • Escape hatches that are documented, not discovered — when the convention doesn't fit (header rows, transposed grids, a homegrown format), a CustomFormat or CustomLayout is a few lines reusing the same table stage. Every hatch ships as a runnable example under examples/.

Project goals — ease of use first:

  • An API you can remember: a handful of names, and most jobs are a few lines.
  • Everything optional and changeable: formats, value parsers and modes are Cargo features and plain-data Options — take only what you use.
  • Test-driven: every documented behavior is covered by tests before it is implemented.
  • An escape hatch: custom formats let you support a file format yourself before (or instead of) waiting for a release.

Usage

One call, one path — a folder whose files deep-merge, or a single file (the default build reads jsonc; every other format — yaml, toml, ini, env, csv, excel, ods, strict json — is one Cargo feature away):

let value: c4::Value = c4::load("config")?;   // a folder …
let one: c4::Value = c4::load("app.json")?;   // … or a single file

// dynamic access: index into objects/arrays — a missing key yields
// Value::Null instead of panicking — and convert with the as_* accessors
let host = value["db"]["host"].as_str().unwrap_or("localhost");
let port = value["db"]["port"].as_u64().unwrap_or(5432);
let first = value["servers"][0].as_str();

// same call — the annotated target type decides what you get:
// a dynamic c4::Value, or any serde type for typed config.
// The recommended pattern is #[serde(default)]: any key no source sets
// falls back to your Default, so partial config files just work.
#[derive(serde::Deserialize)]
#[serde(default)]
struct MyConfig {
    host: String,
    port: u16,
}

impl Default for MyConfig {
    fn default() -> Self {
        Self { host: "localhost".into(), port: 5432 }
    }
}

let cfg: MyConfig = c4::load("config")?;

Documentation

The full reference — mixed sources and every Options field, the Cargo features, format/extension mapping, merge rules, tree mode, typed table cells, custom formats and provenance tracing — lives in the crate docs, with runnable examples:

📖 docs.rs/c4-config

(CLAUDE.md in the repo is the exhaustive, normative spec.)

CLI

The cli feature builds a c4 binary (all formats and value parsers) that loads config sources and writes the merged result as one document. Every Options field is a flag (each boolean also has a --no-<name> form), plus output flags -f/-o/--trace:

c4                        # read ./config, print the Rust Debug form
c4 ./config -f yaml       # explicit sources, choose the output format
c4 --trace -f json        # provenance tree (source + format per value) as JSON
c4 --tree                 # tree mode: folders/files become keys
c4 --help                 # every flag, with examples and notes

The full flag list, defaults and examples live in c4 --help (and, if you want the exact behavior, src/main.rs). In short: -f wins over the -o extension, else output is debug (the Rust {:#?} form); output is deterministic (sorted keys, two-space json, trailing newline) so tests compare it byte-for-byte; flat formats (env/ini/csv) dot nested keys; and errors go to stderr with a non-zero exit.

Examples

Complete runnable examples live under examples/: each subfolder is a standalone crate — its own Cargo.toml, config files, source, and an output.log showing exactly what it prints:

cd examples/00_simple && cargo run
Folder Shows
00_simple the basic load from a config folder
01_advanced multi-source usage (folders + files + in-code values)
csv-db a CSV record grid (the db layout) into a Vec<Item>
csv-header reshaping a CSV with a CustomFormat (header + renamed/reordered columns)
csv-list single cells expanded into lists via the array / csv type ids
csv-transpose a column-oriented CSV transposed into rows with a CustomFormat
dot-key everything dot_key does — dotted nesting plus name[] / name[<int>] array keys
hot-reload DIY hot-reload — watch the folder with notify, re-run load()
xlsx-sheets one Excel workbook, a different table layout per sheet

Beyond that, every behavior has a fixture under tests/fixtures/: config/ is the input, expect.json the merged result, and expect.debug.json the traced form — if something is not covered in examples/, there is a fixture showing it.

Contributing

Conventions, test layout and the development workflow live in CONTRIBUTING.md.