Skip to main content

c4/
lib.rs

1//! Load config from folders, files and in-code strings/values into one
2//! deep-merged [`Value`]. File formats (jsonc, yaml, json, toml, ini, env,
3//! csv, excel, ods) are individually Cargo-feature-gated, the table
4//! formats' cells (csv and spreadsheet sheets) carry typed values, and
5//! every value can be traced to the source it came from.
6//!
7//! This page is the usage reference; the [README] has the quick start
8//! and the "why c4" positioning. Most examples below run without any
9//! files — they load in-code string and value sources; only the
10//! `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 (default format: jsonc). 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.json")?;   // … 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`]: every `sources`
39//! element converts with `.into()`, and its shape picks the source kind
40//! — the comments below show every form, [`Source`] has the details:
41//!
42//! ```no_run
43//! use std::path::Path;
44//!
45//! use c4::{Format, Loader, Options};
46//!
47//! #[derive(serde::Serialize)]
48//! struct Overrides {
49//!     debug: bool,
50//! }
51//!
52//! # fn main() -> Result<(), c4::Error> {
53//! let value: c4::Value = Loader::new(Options {
54//!         sources: vec![
55//!             // Path-like values are folders or files
56//!             "./config".into(),                              // a folder
57//!             "./local.yml".into(),                           // or a single file
58//!             Path::new("/etc/myapp").into(),                 // any path-like type
59//!             (Overrides { debug: true },).into(),            // (1-tuple) typed override
60//!             ("jsonc", r#"{ "note": "from code" }"#).into(), // (2-tuple) format id with string source
61//!             (Format::Toml, "debug = true").into(),          // (2-tuple) Format with string source
62//!             ("csv", "./items.csv", "db").into(),            // (3-tuple) table source: format + file + layout
63//!             (Format::Excel, "./game.xlsx", "drops", "db").into(), // (4-tuple) multiple tables: Format + file + sheet + layout
64//!         ],
65//!         // which formats read which extensions; the last claimer wins.
66//!         // all conversion forms — id/Format × default/custom exts,
67//!         // optionally + a table layout for every file the entry claims:
68//!         formats: vec![
69//!             "jsonc".into(),                                 // format id, default extensions
70//!             Format::Toml.into(),                            // Format, default extensions
71//!             (Format::Yaml, ["yml", "yaml", "conf"]).into(), // Format + custom extensions
72//!             ("jsonc", ["json", "jsonc"]).into(),            // format id + custom extensions
73//!             (Format::Csv, ["csv"], "db").into(),            // + layout: all csv = record grids
74//!         ],
75//!         dir_depth: -1, // scan every subdirectory level
76//!         ..Options::default()
77//!     })
78//!     .load()?;
79//! # Ok(())
80//! # }
81//! ```
82//!
83//! Every field is documented on [`Options`], each stating up front the
84//! mode/format it applies to.
85//!
86//! # Merge order and custom formats
87//!
88//! The merge rules, whatever the source kind:
89//!
90//! 1. Sources merge in the order given; later overrides earlier.
91//! 2. Within a folder, entries load in `order` and deep-merge: objects
92//!    merge recursively, arrays and scalars replace.
93//! 3. Override order between files is decided by **filename alone**, never
94//!    by format: `app.json` and `app.yml` sort by name, so `app.yml` loads
95//!    later and wins. Prefix filenames (`00_a.json`, `01_a.yml`) for
96//!    explicit control.
97//!
98//! A [`CustomFormat`] is an id, the extensions it claims, and a parser
99//! callback. It goes into `Options.formats` like any built-in — one list,
100//! one claim order — and a string source can name one directly. See
101//! [`CustomFormat`] for a full markdown-pipe-table example.
102//!
103//! ```
104//! use c4::{CustomFormat, Loader, Options};
105//!
106//! # fn main() -> Result<(), c4::Error> {
107//! // a tiny `key value type` table format, lowered to `parse_table`
108//! let kv = CustomFormat::new("kv", ["kv"], |text, path, options| {
109//!     let rows = text
110//!         .lines()
111//!         .filter(|l| !l.trim().is_empty())
112//!         .map(|l| l.split_whitespace().map(str::to_owned).collect())
113//!         .collect();
114//!     c4::parse_table(rows, &c4::TableLayout::Kv, path, options)
115//! });
116//! let value: c4::Value = Loader::new(Options {
117//!         sources: vec![
118//!             (kv.clone(), "port 1 u16").into(),                            // earlier …
119//!             (kv, "port 8080 u16").into(),                                 // … overridden
120//!             (std::collections::BTreeMap::from([("debug", true)]),).into(),
121//!         ],
122//!         ..Options::default()
123//!     })
124//!     .load()?;
125//! assert_eq!(value["port"].as_u64(), Some(8080));
126//! assert_eq!(value["debug"].as_bool(), Some(true));
127//! # Ok(())
128//! # }
129//! ```
130//!
131//! # Cargo features
132//!
133//! `default = ["jsonc"]` — deliberately light, one parser dependency; at
134//! least one **format** feature is required (a compile error otherwise).
135//! Value-parser features are pure std (no extra dependencies). Cargo
136//! unions features across the whole build graph, so only applications
137//! should turn format features on.
138//!
139//! | Feature | Enables |
140//! | ------- | ------- |
141//! | `jsonc` *(default)* | JSONC files (comments + trailing commas); also the `jsonc` table cell |
142//! | `yaml` | YAML files |
143//! | `json` | strict JSON files; also the table `json` cell |
144//! | `toml` / `ini` / `env` / `csv` | those file formats |
145//! | `excel` | Excel workbooks (`.xlsx`/`.xlsm`/`.xlsb`/`.xls`) |
146//! | `ods` | OpenDocument spreadsheets (`.ods`) |
147//! | `tree` | default-preset: flips [`filename_as_key`](Options::filename_as_key), [`dirname_as_key`](Options::dirname_as_key), [`sheetname_as_key`](Options::sheetname_as_key) on and [`dir_depth`](Options::dir_depth) to `-1` in [`Options::default`] (the fields work without it) |
148//! | `datetime` (= `date` + `time`) | the `dt` table type |
149//! | `date`, `time` | the `date` / `time` table types |
150//! | `ipv4`, `ipv6` | the `ipv4` / `ipv6` table types |
151//! | `inet` (= `ipv4` + `ipv6` + `cidr`), `cidr` | inet / cidr table types |
152//! | `macaddr` (= `macaddr8`), `macaddr8` | MAC table types |
153//! | `uuid` | the `uuid` table type |
154//! | `numeric` | extended table numeric literals (`0x`, `_`, `123n`) |
155//! | `cli` | the `c4` binary (implies all of the above) |
156//!
157//! # File formats
158//!
159//! Format and file extension are separate things: each format claims a set
160//! of default extensions, and both sides are configurable. Extension
161//! matching is case-insensitive; a hidden file `.X` counts as extension
162//! `X` (so `.env` matches `env`). Unclaimed extensions are ignored, and the
163//! **last** claimer of a contested extension wins — which is also how you
164//! reassign one: `vec![Format::Yaml.into(), (Format::Jsonc, ["yml"]).into()]`
165//! makes the jsonc parser read `.yml`. `jsonc` is a JSON superset that also
166//! claims `.json`, so with the default `formats` enabling both `json` and
167//! `jsonc` is redundant (jsonc, added last, wins `.json`).
168//!
169//! | Format  | Default extensions | Feature |
170//! | ------- | ------------------ | ------- |
171//! | `jsonc` | `.json`, `.jsonc`  | default |
172//! | `yaml`  | `.yml`, `.yaml`    | `yaml`  |
173//! | `json`  | `.json` (strict)   | `json`  |
174//! | `toml`  | `.toml`            | `toml`  |
175//! | `ini`   | `.ini`             | `ini`   |
176//! | `env`   | `.env`, `*.env`    | `env`   |
177//! | `csv`   | `.csv`             | `csv`   |
178//! | `excel` | `.xlsx`, `.xlsm`, `.xlsb`, `.xls` | `excel` |
179//! | `ods`   | `.ods`             | `ods`   |
180//!
181//! # Folder shape: keys and depth
182//!
183//! By default a folder's files deep-merge into one flat value, scanning
184//! the folder plus one subdirectory level ([`dir_depth`](Options::dir_depth):
185//! `-1` for unlimited, `0` for the folder only). Turning subfolders and
186//! files into **keys** makes the folder's *shape* the config instead:
187//!
188//! - [`dirname_as_key`](Options::dirname_as_key) — each subfolder becomes
189//!   a key.
190//! - [`filename_as_key`](Options::filename_as_key) — each file becomes a
191//!   key named after it (extension stripped).
192//! - [`sheetname_as_key`](Options::sheetname_as_key) — each spreadsheet
193//!   sheet becomes a key.
194//!
195//! These fields work on any build; the `tree` **feature** is just a
196//! convenience that flips all three on (and `dir_depth` to `-1`) in
197//! [`Options::default`], so an app that wants tree-shaped loading enables
198//! the feature and keeps using the defaults.
199//!
200//! ```text
201//! config/a/b.json = {"c": 1}   ->  { "a": { "b": { "c": 1 } },
202//! config/d.json   = {"a": 123}       "d": { "a": 123 } }
203//! ```
204//!
205//! ```no_run
206//! # fn main() -> Result<(), c4::Error> {
207//! // explicit keying — or, with the `tree` feature, just Options::default()
208//! let value: c4::Value = c4::Loader::new(c4::Options {
209//!         sources: vec!["./config".into()],
210//!         filename_as_key: true,
211//!         dirname_as_key: true,
212//!         dir_depth: -1,
213//!         ..c4::Options::default()
214//!     })
215//!     .load()?;
216//! assert_eq!(value["a"]["b"]["c"].as_i64(), Some(1));
217//! # Ok(())
218//! # }
219//! ```
220//!
221//! Key collisions deep-merge (so [`order`](Options::order) decides the
222//! winner); extension handling for keyed files is on
223//! [`auto_no_ext_files`](Options::auto_no_ext_files) and
224//! [`ignore_unknown_ext`](Options::ignore_unknown_ext).
225//!
226//! # Table formats
227//!
228//! Table files (csv, and each spreadsheet sheet) parse under a
229//! [`TableLayout`]. Each format has a default —
230//! [`Format::default_layout`]: **`kv` for csv, `db` for excel/ods**
231//! (spreadsheets are grids) — overridable per source with a table-source
232//! tuple or per extension in `formats`:
233//!
234//! - **`kv`** (csv default): `key,value[,format]` rows, one config entry
235//!   per row.
236//! - **`db`** (spreadsheet default): a record grid — row 1 holds the
237//!   keys, row 2 always the
238//!   type ids (empty cell = `auto`), every following row is one record;
239//!   the file parses to an **array** of objects, so a config sheet full
240//!   of game items deserializes straight into a `Vec<Item>`. Empty cells
241//!   are omitted from their record. The type row is positional — the
242//!   row right after the keys is the type row even when it is entirely
243//!   blank (= every column `auto`); it is never skipped as a blank row.
244//! - **a [`CustomLayout`]**: your callback over the raw rows — reshape
245//!   them and call [`parse_table`]. A db grid
246//!   *without* a type row is the canonical case: insert a row of `auto`
247//!   cells after the header and delegate to `db` (see the `xlsx-sheets`
248//!   example).
249//!
250//! The layout comes from a table-source tuple or a `formats` entry (the
251//! forms are in the sources example above; details on [`Source`]). The
252//! db layout on a plain csv file loads a record grid straight into a
253//! `Vec<T>` (the `csv-db` example):
254//!
255//! ```no_run
256//! use c4::{Format, Loader, Options};
257//!
258//! #[derive(serde::Deserialize)]
259//! struct Item {
260//!     id: u32,
261//!     name: String,
262//!     price: f64,
263//! }
264//!
265//! # fn main() -> Result<(), c4::Error> {
266//! // items.csv:          key row
267//! //   id,name,price
268//! //   u32,str,f64       type row (a cell may be empty = auto)
269//! //   1,sword,10.5      one record per row
270//! //   2,shield,7
271//! let items: Vec<Item> = Loader::new(Options {
272//!         sources: vec![(Format::Csv, "items.csv", "db").into()],
273//!         ..Options::default()
274//!     })
275//!     .load()?;
276//! # Ok(())
277//! # }
278//! ```
279//!
280//! Two db sources do not concatenate: arrays replace like any array.
281//!
282//! Rows map keys to values **positionally** (in `kv`: col 0 = key,
283//! col 1 = value, col 2 = format; in `db`: the type row types its
284//! column). With [`Options::dot_key`] (default on) a dotted key nests in
285//! both layouts — a kv row `a.b,1` gives `{a:{b:1}}`, and a db
286//! `stats.atk` column nests inside each record — and a `name[]` /
287//! `name[<int>]` segment builds an **array** (append / index, suffixes
288//! chain for nested arrays; see [`Options::dot_key`] and the `dot-key`
289//! example). The **format** of a
290//! cell is one of the ids below — the column/row is optional, and a
291//! missing or empty format means `auto`:
292//!
293//! | Cell format | Aliases | Cargo feature | Notes |
294//! | ----------- | ------- | ------------- | ----- |
295//! | `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 |
296//! | `i8` `i16` `i32` `i64` | `int`, `integer` = `i64` | — | signed integers |
297//! | `u8` `u16` `u32` `u64` | `uint` = `u64` | — | unsigned integers |
298//! | `i128` `u128` | — | — | explicit-only — `auto` never guesses them |
299//! | `f32` `f64` | `float`, `double`, `number` = `f64` | — | floats (`f32` rounds through f32 precision) |
300//! | `bool` | `boolean` | — | also accepts `t/f`, `yes/no`, `y/n`, `on/off`, `1/0` (case-insensitive); `auto` only accepts `true`/`false` |
301//! | `str` | `string`, `text` | — | the cell text as-is |
302//! | `dt` | `datetime` | `datetime` | `YYYY-MM-DD`, optional time part |
303//! | `date`, `time` | — | same-named | `YYYY-MM-DD` / `hh:mm:ss[.frac]` |
304//! | `ipv4`, `ipv6` | — | same-named | IP addresses |
305//! | `inet`, `cidr` | — | same-named | PostgreSQL inet/cidr shapes (optional/required netmask) |
306//! | `macaddr`, `macaddr8` | — | same-named | the PostgreSQL MAC spellings |
307//! | `uuid` | — | same-named | hyphenated or bare 32-hex |
308//! | `json`, `jsonc` | — | same-named | a whole document in one cell, parsed by exactly that format's parser |
309//! | `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"]` |
310//! | `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 |
311//!
312//! `array` and `csv` are explicit-only (like `json`/`jsonc`) — `auto`
313//! never produces a list. `array` is always compiled (a native split);
314//! `csv` needs the `csv` feature. Both take an optional, **positional**
315//! suffix after the separator: `array<sep><format>` applies one type id
316//! to every element, and `csv<sep><layout>` picks the inner layout — in
317//! each case naming the suffix means writing the separator too
318//! (`array,i8`, `csv,db`), and the separator is a single character
319//! (ASCII for `csv`). `array<sep><format>` types **every** element the
320//! same; when a list's elements need **different** formats, use a `csv`
321//! cell instead (one `key,value,format` row each: `a,1,i8` / `b,2,i16`).
322//! Only the built-in layout ids `kv`/`db` are nameable in `csv`.
323//!
324//! An id whose feature is off is an unknown format and fails the row;
325//! only `auto` degrades (it just stops guessing). The `numeric` feature
326//! extends every numeric cell with `0x`/`0o`/`0b` radixes, `_`
327//! separators and BigInt-style `123n`.
328//!
329//! The built-in `csv` format is headerless and positional; a header row,
330//! renamed/reordered columns or a transposed layout are a [`CustomFormat`]
331//! that reshapes the file into `key,value,format` rows and calls
332//! [`parse_table`] (see the `csv-header` and `csv-transpose` examples):
333//!
334//! ```
335//! use c4::{CustomFormat, Loader, Options};
336//!
337//! # fn main() -> Result<(), c4::Error> {
338//! let table = CustomFormat::new("kv", ["kv"], |text, path, options| {
339//!     let rows = text
340//!         .lines()
341//!         .filter(|l| !l.trim().is_empty())
342//!         .map(|l| l.split_whitespace().map(str::to_owned).collect())
343//!         .collect();
344//!     c4::parse_table(rows, &c4::TableLayout::Kv, path, options)
345//! });
346//! let value: c4::Value = Loader::new(Options {
347//!         sources: vec![(table, "name c4 str\nport 8080 u16\ndebug true bool").into()],
348//!         ..Options::default()
349//!     })
350//!     .load()?;
351//! assert_eq!(value["name"].as_str(), Some("c4"));
352//! assert_eq!(value["port"].as_u64(), Some(8080));
353//! assert_eq!(value["debug"].as_bool(), Some(true));
354//! # Ok(())
355//! # }
356//! ```
357//!
358//! # Spreadsheet formats
359//!
360//! `excel` (`.xlsx`/`.xlsm`/`.xlsb`/`.xls`) and `ods` (`.ods`) read
361//! workbooks as table formats: each sheet is a grid anchored at cell A1,
362//! lowered to rows for the table stage — **db record grids by default**
363//! ([`Format::default_layout`]). Numbers, booleans and date-formatted
364//! cells convert to the text the stage expects (a `dt`/`date`/`time`
365//! column works on real spreadsheet dates), and error messages carry
366//! real spreadsheet row numbers. Both are binary formats, so they load
367//! from files only — a `(Format::Excel, text)` string source is an
368//! error.
369//!
370//! Which sheets are read — each sheet is treated like a file:
371//!
372//! - `sheetname_as_key: false` (default): every non-ignored sheet parses
373//!   and they all **deep-merge** into one value, in
374//!   [`order`](Options::order) by sheet name (later overrides earlier). A
375//!   workbook with no sheets left contributes nothing.
376//! - `sheetname_as_key: true`: every sheet becomes a key instead — see
377//!   [`Options::sheetname_as_key`].
378//! - Prefixed (`#`/`.`/`_`) and hidden sheets are skipped — see
379//!   [`Options::ignore_commented_sheets`] and
380//!   [`Options::ignore_hidden_sheets`].
381//! - A table source that names a sheet (always the 4-tuple) reads
382//!   exactly that sheet and merges it under the sheet name as key — see
383//!   [`Source`]:
384//!
385//! ```no_run
386//! use c4::{Format, Loader, Options};
387//!
388//! # fn main() -> Result<(), c4::Error> {
389//! // game.xlsx: sheet "items" is a record grid, "settings" is kv rows
390//! let value: c4::Value = Loader::new(Options {
391//!         sources: vec![
392//!             (Format::Excel, "game.xlsx", "items", "db").into(),
393//!             (Format::Excel, "game.xlsx", "settings", "kv").into(),
394//!         ],
395//!         ..Options::default()
396//!     })
397//!     .load()?;
398//! assert!(value["items"][0]["id"].as_u64().is_some());
399//! assert!(!value["settings"].is_null());
400//! # Ok(())
401//! # }
402//! ```
403//!
404//! The `xlsx-sheets` example composes five sheets of one workbook this
405//! way, `CustomLayout`s included.
406//!
407//! # Provenance
408//!
409//! [`Loader::trace`] returns a [`TracedValue`] tree that keeps, per leaf,
410//! the source it came from and the format it parsed as — the shape the CLI
411//! `--trace` prints and the fixtures assert. See [`Loader::trace`] and
412//! [`TracedValue`].
413
414#[cfg(not(any(
415    feature = "json",
416    feature = "jsonc",
417    feature = "yaml",
418    feature = "toml",
419    feature = "ini",
420    feature = "env",
421    feature = "csv",
422    feature = "excel",
423    feature = "ods"
424)))]
425compile_error!(
426    "c4: enable at least one format feature (json, jsonc, yaml, toml, ini, env, csv, excel, ods)"
427);
428
429mod de;
430mod error;
431mod format;
432mod loader;
433mod options;
434mod ser;
435mod source;
436mod trace;
437pub(crate) mod valid;
438mod value;
439
440pub use error::{Error, Result};
441pub use loader::Loader;
442pub use options::{
443    CustomFormat, CustomLayout, Format, FormatKind, FormatSpec, Options, Order, TableLayout,
444};
445pub use source::Source;
446pub use trace::{SourceRef, TracedValue};
447pub use value::Value;
448
449use std::path::{Path, PathBuf};
450
451use serde::de::DeserializeOwned;
452
453/// Load one path with default options — the shortest way in. An
454/// existing file loads as a single file source; anything else is
455/// treated as a folder (a missing path is [`Error::NotFound`]). The
456/// annotated target type decides what you get back:
457///
458/// ```no_run
459/// #[derive(serde::Deserialize)]
460/// struct MyConfig {
461///     host: String,
462///     port: u16,
463/// }
464///
465/// # fn main() -> Result<(), c4::Error> {
466/// let value: c4::Value = c4::load("config")?;   // a folder …
467/// let value: c4::Value = c4::load("app.yml")?;  // … or one file
468/// let cfg: MyConfig = c4::load("config")?;
469/// # Ok(())
470/// # }
471/// ```
472pub fn load<T: DeserializeOwned>(path: impl Into<PathBuf>) -> Result<T> {
473    Loader::new(Options {
474        sources: vec![Source::Path(path.into())],
475        ..Options::default()
476    })
477    .load()
478}
479
480/// The generic table stage: interpret a plain row table under an
481/// explicit [`TableLayout`] — `&TableLayout::Kv` for
482/// `key,value[,format]` rows (what the csv format feeds by default),
483/// `&TableLayout::Db` for a record grid, or a [`CustomLayout`] callback.
484/// Public so custom table-shaped formats (markdown tables, …) and custom
485/// layouts can lower their input into rows and reuse it; `path` labels
486/// errors. The layout is always passed — there is deliberately no
487/// defaulting variant.
488pub fn parse_table(
489    rows: Vec<Vec<String>>,
490    layout: &TableLayout,
491    path: &Path,
492    options: &Options,
493) -> Result<Value> {
494    format::table::parse(rows, layout, path, options)
495}