Skip to main content

Crate c4

Crate c4 

Source
Expand description

Load a folder of config files into one deep-merged Value.

README.md is the user-facing overview and CLAUDE.md the complete spec; the README examples are mirrored here as doc tests. Examples that read the caller’s working directory (./config, /etc/myapp) are no_run — they compile but depend on the user’s filesystem; the CustomFormat example is fully runnable via a string source.

Simplest form — one generic load taking the path of a folder (or a single file), default options (formats: jsonc + yaml). The annotated target type decides whether you get a dynamic Value or your own struct:

let value: c4::Value = c4::load("config")?;

Advanced — explicit sources (later overrides earlier) and options:

use std::path::Path;

use c4::{Format, Loader, Options, Source};

let value: c4::Value = Loader::new(Options {
        sources: vec![
            Source::folder("./config"),
            Source::folder(Path::new("/etc/myapp")), // any path-like type
            Source::file("./local.yml"),
            Source::string(Format::Jsonc, r#"{ "debug": true }"#),
        ],
        recursive: true,
        formats: vec![
            "jsonc".into(),                              // format id, default extensions
            Format::Toml.into(),                         // enum form, default extensions
            (Format::Yaml, ["yml", "yaml", "conf"]).into(), // custom extensions
            ("jsonc", ["json", "jsonc"]).into(),         // string id + custom extensions
        ],
        ..Options::default()
    })
    .load()?;

Structs§

CustomFormat
A user-defined format: an id, the extensions it claims, and a parser callback. It goes into Options::formats like 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 via [parse_table].
FormatSpec
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.
TableColumns
Names of the key / value / format columns of a table source.
TableOptions
Options for table-shaped formats (csv today; spreadsheet formats later).
TableTypes
Which type column values a table (csv) source accepts.

Enums§

Error
Errors produced while scanning, parsing, merging or deserializing.
Format
A config file format.
FormatKind
What a FormatSpec entry parses with: a built-in format or a user-defined CustomFormat.
Order
File load order inside a folder.
Source
One config source. Sources merge in order — later overrides earlier.
SourceRef
Where a traced value came from.
TracedValue
The result of [Loader::trace]: the merged tree with per-leaf provenance. Objects recurse; every non-object value (including whole arrays) is a TracedValue::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 the options.table semantics — 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; path labels errors.

Type Aliases§

Result