Skip to main content

c4/
lib.rs

1//! Load config from folders, files and in-code strings/values into one
2//! deep-merged [`Value`]. Formats (jsonc, yaml, json, toml, ini, env, csv)
3//! are individually Cargo-feature-gated, the table (csv) format's cells
4//! carry typed values, and every value can be traced to the source it came
5//! from.
6//!
7//! The [README] is the quick start; this page is the full reference (and
8//! `CLAUDE.md` in the repo is the exhaustive spec). Most examples below run
9//! without any files — they load in-code string and value sources; only
10//! the `load("config")` snippets, which read the caller's filesystem, are
11//! marked `no_run`.
12//!
13//! [README]: https://github.com/up9cloud/c4#readme
14//!
15//! # Quick start
16//!
17//! One generic [`load`] takes a path — a folder whose files deep-merge, or
18//! a single file — with default options (formats: jsonc + yaml). The
19//! annotated target type decides what you get: a dynamic [`Value`] or your
20//! own serde type.
21//!
22//! ```no_run
23//! # fn main() -> Result<(), c4::Error> {
24//! let value: c4::Value = c4::load("config")?;   // a folder …
25//! let one: c4::Value = c4::load("app.yml")?;    // … or a single file
26//! let host = value["db"]["host"].as_str().unwrap_or("localhost");
27//! # Ok(())
28//! # }
29//! ```
30//!
31//! For more than one source, or any non-default option, build a [`Loader`]
32//! from [`Options`], as the next section shows.
33//!
34//! # Sources and options
35//!
36//! Everything goes through one plain-data [`Options`]; [`Loader`] has
37//! exactly [`new`](Loader::new), [`load`](Loader::load) and
38//! [`trace`](Loader::trace). You never name [`Source`]: `sources` is a
39//! `Vec<Source>` and each element converts with `.into()` — a path-like
40//! value (`&str`/`String`/`&Path`/`PathBuf`) is a folder/file source, a
41//! `(format, text)` tuple is an in-code string source, and a **1-tuple**
42//! `(value,)` wraps any serde type as a typed override (the trailing comma
43//! is what keeps it distinct — see [`Source`]).
44//!
45//! ```no_run
46//! use std::path::Path;
47//!
48//! use c4::{Format, Loader, Options};
49//!
50//! #[derive(serde::Serialize)]
51//! struct Overrides {
52//!     debug: bool,
53//! }
54//!
55//! # fn main() -> Result<(), c4::Error> {
56//! let value: c4::Value = Loader::new(Options {
57//!         sources: vec![
58//!             "./config".into(),                              // a folder (or a single file)
59//!             Path::new("/etc/myapp").into(),                 // any path-like type
60//!             "./local.yml".into(),
61//!             ("jsonc", r#"{ "note": "from code" }"#).into(), // string source, by format id
62//!             (Format::Toml, "debug = true").into(),          // string source, by Format
63//!             (Overrides { debug: true },).into(),            // typed override (1-tuple)
64//!         ],
65//!         // which formats read which extensions; the last claimer wins.
66//!         // all four conversion forms — id/Format × default/custom exts:
67//!         formats: vec![
68//!             "jsonc".into(),                                 // format id, default extensions
69//!             Format::Toml.into(),                            // Format, default extensions
70//!             (Format::Yaml, ["yml", "yaml", "conf"]).into(), // Format + custom extensions
71//!             ("jsonc", ["json", "jsonc"]).into(),            // format id + custom extensions
72//!         ],
73//!         recursive: true,
74//!         ..Options::default()
75//!     })
76//!     .load()?;
77//! # Ok(())
78//! # }
79//! ```
80//!
81//! Sources merge in the order given — later overrides earlier — whatever
82//! their kind:
83//!
84//! ```
85//! use c4::{CustomFormat, Loader, Options};
86//!
87//! # fn main() -> Result<(), c4::Error> {
88//! // a tiny `key value type` table format, lowered to `parse_table`
89//! let kv = CustomFormat::new("kv", ["kv"], |text, path, options| {
90//!     let rows = text
91//!         .lines()
92//!         .filter(|l| !l.trim().is_empty())
93//!         .map(|l| l.split_whitespace().map(str::to_owned).collect())
94//!         .collect();
95//!     c4::parse_table(rows, path, options)
96//! });
97//! let value: c4::Value = Loader::new(Options {
98//!         sources: vec![
99//!             (kv.clone(), "port 1 u16").into(),                            // earlier …
100//!             (kv, "port 8080 u16").into(),                                 // … overridden
101//!             (std::collections::BTreeMap::from([("debug", true)]),).into(),
102//!         ],
103//!         ..Options::default()
104//!     })
105//!     .load()?;
106//! assert_eq!(value["port"].as_u64(), Some(8080));
107//! assert_eq!(value["debug"].as_bool(), Some(true));
108//! # Ok(())
109//! # }
110//! ```
111//!
112//! Every [`Options`] field is documented on the struct. In brief:
113//! `sources`, `formats`, `recursive`, `flat` (merge-mode subfolder
114//! nesting), `dot_key`, `case_sensitive`, `order` (an [`Order`] or an id
115//! like `"alphabetic".into()`), and the tree-mode trio `tree`,
116//! `auto_files`, `ignore_unknown_ext`.
117//!
118//! # Cargo features
119//!
120//! `default = ["jsonc", "yaml"]`; at least one **format** feature is
121//! required (a compile error otherwise). Value-parser features are pure
122//! std (no extra dependencies). Cargo unions features across the whole
123//! build graph, so only applications should turn format features on.
124//!
125//! | Feature | Enables |
126//! | ------- | ------- |
127//! | `jsonc` *(default)* | JSONC files (comments + trailing commas) |
128//! | `yaml` *(default)* | YAML files |
129//! | `json` | strict JSON files; also the table `json` cell |
130//! | `toml` / `ini` / `env` / `csv` | those file formats |
131//! | `tree` | tree mode ([`Options::tree`]) |
132//! | `datetime` (= `date` + `time`) | the `dt` table type |
133//! | `date`, `time` | the `date` / `time` table types |
134//! | `ipv4`, `ipv6` | the `ipv4` / `ipv6` table types |
135//! | `inet` (= `ipv4` + `ipv6` + `cidr`), `cidr` | inet / cidr table types |
136//! | `macaddr` (= `macaddr8`), `macaddr8` | MAC table types |
137//! | `uuid` | the `uuid` table type |
138//! | `numeric` | extended table numeric literals (`0x`, `_`, `123n`) |
139//! | `cli` | the `c4` binary (implies all of the above) |
140//!
141//! # Formats
142//!
143//! Format and file extension are separate things: each format claims a set
144//! of default extensions, and both sides are configurable. Extension
145//! matching is case-insensitive; a hidden file `.X` counts as extension
146//! `X` (so `.env` matches `env`). Unclaimed extensions are ignored, and the
147//! **last** claimer of a contested extension wins — which is also how you
148//! reassign one: `vec![Format::Yaml.into(), (Format::Jsonc, ["yml"]).into()]`
149//! makes the jsonc parser read `.yml`. `jsonc` is a JSON superset that also
150//! claims `.json`, so with the default `formats` enabling both `json` and
151//! `jsonc` is redundant (jsonc, added last, wins `.json`).
152//!
153//! | Format  | Default extensions | Feature |
154//! | ------- | ------------------ | ------- |
155//! | `jsonc` | `.json`, `.jsonc`  | default |
156//! | `yaml`  | `.yml`, `.yaml`    | default |
157//! | `json`  | `.json` (strict)   | `json`  |
158//! | `toml`  | `.toml`            | `toml`  |
159//! | `ini`   | `.ini`             | `ini`   |
160//! | `env`   | `.env`, `*.env`    | `env`   |
161//! | `csv`   | `.csv`             | `csv`   |
162//!
163//! # Merge rules
164//!
165//! 1. Sources merge in the order given; later overrides earlier.
166//! 2. Within a folder, entries load in `order` and deep-merge: objects
167//!    merge recursively, arrays and scalars replace.
168//! 3. Override order between files is decided by **filename alone**, never
169//!    by format: `app.json` and `app.yml` sort by name, so `app.yml` loads
170//!    later and wins. Prefix filenames (`00_a.json`, `01_a.yml`) for
171//!    explicit control.
172//!
173//! # Tree mode
174//!
175//! With `Options { tree: true, .. }` (feature `tree`) a folder is not
176//! merged — its shape becomes the config: every subfolder is a key, and
177//! every file a key named after it (extension stripped):
178//!
179//! ```text
180//! config/a/b.json = {"c": 1}   ->  { "a": { "b": { "c": 1 } },
181//! config/d.json   = {"a": 123}       "d": { "a": 123 } }
182//! ```
183//!
184//! Tree mode is always recursive; `order` decides key collisions (`a.yml`
185//! next to a folder `a/`). Extension-less files are auto-detected from
186//! their content when `auto_files` is set; files with unknown extensions
187//! are skipped unless `ignore_unknown_ext` is `false`.
188//!
189//! # Table formats
190//!
191//! Table rows map to config entries **positionally** as `key,value[,format]`;
192//! the format column is optional (missing or empty = `auto`). Type ids
193//! `i8`–`u64`, `i128`/`u128`, `f32`/`f64`, `bool`, `str`, `auto` always
194//! exist; `dt`/`date`/`time`/`ipv4`/`ipv6`/`inet`/`cidr`/`macaddr`/
195//! `macaddr8`/`uuid` follow their features, and `json` (a whole JSON
196//! document as one cell) needs `json` or `jsonc`. `auto` tries
197//! bool → date/time/dt → uuid → mac → ip → integer → float → string, and
198//! never widens past `i64`/`u64` (use an explicit `i128`/`u128` cell for
199//! bigger integers). An explicit `bool` cell also accepts
200//! `t/f`, `yes/no`, `y/n`, `on/off`, `1/0` (case-insensitive).
201//!
202//! The built-in `csv` format is headerless and positional; a header row,
203//! renamed/reordered columns or a transposed layout are a [`CustomFormat`]
204//! that reshapes the file into `key,value,format` rows and calls
205//! [`parse_table`] (see the `csv-header` and `csv-transpose` examples):
206//!
207//! ```
208//! use c4::{CustomFormat, Loader, Options};
209//!
210//! # fn main() -> Result<(), c4::Error> {
211//! let table = CustomFormat::new("kv", ["kv"], |text, path, options| {
212//!     let rows = text
213//!         .lines()
214//!         .filter(|l| !l.trim().is_empty())
215//!         .map(|l| l.split_whitespace().map(str::to_owned).collect())
216//!         .collect();
217//!     c4::parse_table(rows, path, options)
218//! });
219//! let value: c4::Value = Loader::new(Options {
220//!         sources: vec![(table, "name c4 str\nport 8080 u16\ndebug true bool").into()],
221//!         ..Options::default()
222//!     })
223//!     .load()?;
224//! assert_eq!(value["name"].as_str(), Some("c4"));
225//! assert_eq!(value["port"].as_u64(), Some(8080));
226//! assert_eq!(value["debug"].as_bool(), Some(true));
227//! # Ok(())
228//! # }
229//! ```
230//!
231//! # Custom formats
232//!
233//! A [`CustomFormat`] is an id, the extensions it claims, and a parser
234//! callback. It goes into `Options.formats` like any built-in — one list,
235//! one claim order — and a string source can name one directly. See
236//! [`CustomFormat`] for a full markdown-pipe-table example.
237//!
238//! # Provenance
239//!
240//! [`Loader::trace`] returns a [`TracedValue`] tree that keeps, per leaf,
241//! the source it came from and the format it parsed as — the shape the CLI
242//! `--trace` prints and the fixtures assert. See [`Loader::trace`] and
243//! [`TracedValue`].
244
245#[cfg(not(any(
246    feature = "json",
247    feature = "jsonc",
248    feature = "yaml",
249    feature = "toml",
250    feature = "ini",
251    feature = "env",
252    feature = "csv"
253)))]
254compile_error!("c4: enable at least one format feature (json, jsonc, yaml, toml, ini, env, csv)");
255
256mod de;
257mod error;
258mod format;
259mod loader;
260mod options;
261mod ser;
262mod source;
263mod trace;
264pub(crate) mod valid;
265mod value;
266
267pub use error::{Error, Result};
268pub use loader::Loader;
269pub use options::{CustomFormat, Format, FormatKind, FormatSpec, Options, Order};
270pub use source::Source;
271pub use trace::{SourceRef, TracedValue};
272pub use value::Value;
273
274use std::path::{Path, PathBuf};
275
276use serde::de::DeserializeOwned;
277
278/// Load one path with default options — the shortest way in. An
279/// existing file loads as a single file source; anything else is
280/// treated as a folder (a missing path is [`Error::NotFound`]). The
281/// annotated target type decides what you get back:
282///
283/// ```no_run
284/// #[derive(serde::Deserialize)]
285/// struct MyConfig {
286///     host: String,
287///     port: u16,
288/// }
289///
290/// # fn main() -> Result<(), c4::Error> {
291/// let value: c4::Value = c4::load("config")?;   // a folder …
292/// let value: c4::Value = c4::load("app.yml")?;  // … or one file
293/// let cfg: MyConfig = c4::load("config")?;
294/// # Ok(())
295/// # }
296/// ```
297pub fn load<T: DeserializeOwned>(path: impl Into<PathBuf>) -> Result<T> {
298    Loader::new(Options {
299        sources: vec![Source::Path(path.into())],
300        ..Options::default()
301    })
302    .load()
303}
304
305/// The generic table stage: interpret a plain row table
306/// (`[[key, value, format], …]`) with the `options.table` semantics — the
307/// same stage the csv format feeds. Public so custom table-shaped formats
308/// (spreadsheets, markdown tables, …) can lower their file into rows and
309/// reuse it; `path` labels errors.
310pub fn parse_table(rows: Vec<Vec<String>>, path: &Path, options: &Options) -> Result<Value> {
311    format::table::parse(rows, path, options)
312}