Skip to content
up9cloudPublic

About

"Load a folder of config files (jsonc, yaml, toml, ini, cnf, env, csv, xlsx, ods) into one deep-merged value — with typed spreadsheet tables, provenance tracing and a CLI.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

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

In the AI era, you often don't need a config library. If your application loads a single settings file, ask your AI for bespoke loading code — it is the simplest and fastest way, with zero dependencies. No library can beat that.

c4 is for projects where conventions matter.

It defines a simple, predictable rule set instead of making every project reinvent one:

  • Deterministic merging — later sources override earlier ones, files merge in filename order, objects merge deeply, arrays and scalars replace.
  • Spreadsheet-first tables — the same table conventions work in CSV, Excel and OpenDocument, with typed values instead of stringly-typed data.
  • Easy escape hatches — when the defaults don't fit, implement a CustomFormat or CustomLayout while reusing the same parsing pipeline.

Design goals

  • Easy to remember — a small API that covers most use cases.
  • Composable — formats, parsers and behavior are all optional.
  • Extensible — custom formats integrate without forking the library.
  • Test-driven — documented behavior is backed by tests.

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, cnf, 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, folder shape (depth and folder/file/sheet keying), commented-out names and keys (#/_), typed table cells, custom formats and provenance tracing — lives in the crate docs, with runnable examples:

📖 docs.rs/c4-config

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) + warnings as JSON
c4 --tree                 # key by folder/file/sheet name (a preset)
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; env and csv dot nested keys, ini writes one [section] level; and errors go to stderr with a non-zero exit.

Examples

Complete runnable examples live under examples/ — each subfolder is a standalone crate with config files, source and a committed output.log:

cd examples/00_simple && cargo run

The index of what each one shows is in examples/README.md.

Contributing

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

About

"Load a folder of config files (jsonc, yaml, toml, ini, cnf, env, csv, xlsx, ods) into one deep-merged value — with typed spreadsheet tables, provenance tracing and a CLI.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages